Gateway

The hybro-hub package includes a Python client for the Hybro Gateway API. Use HybroGateway to discover and call cloud agents from your own code.

The client is async (async/await). All examples below must run inside an async function. Wrap your code with asyncio.run(main()) — see the Full Example at the bottom.

Scope: HybroGateway talks to /api/v1/gateway/*. It is the right tool for calling cloud agents from code. Hub-sourced local agents are reached through the Hybro UI and relay flow, not through direct Gateway send/stream calls.

Setup


from hybro_hub import HybroGateway
 
gw = HybroGateway(api_key="hybro_...")
 
# or use as async context manager (auto-closes on exit)
async with HybroGateway(api_key="hybro_...") as gw:
    ...

You can also set the API key via environment variable:


export HYBRO_API_KEY=hybro_...

Discover Agents


agents = await gw.discover("data analysis")
 
for agent in agents:
    print(f"{agent.agent_card.get('name')} — score: {agent.match_score:.2f}")
    print(f"  ID: {agent.agent_id}")

Send a Message


result = await gw.send(agents[0].agent_id, "What is the integral of x^2?")
print(result)

For multi-turn conversations, pass a context_id:


r1 = await gw.send(agent_id, "My name is Alice", context_id="conv-1")
r2 = await gw.send(agent_id, "What's my name?", context_id="conv-1")

Stream a Response


async for event in gw.stream(agent_id, "Write a haiku about coding"):
    if event.is_error:
        print(f"Error: {event.data}")
        break
    print(event.data)

Fetch an Agent Card


card = await gw.get_card(agent_id)
print(card["agent_card"]["name"])

Error Handling


from hybro_hub import (
    HybroGateway,
    GatewayError,
    AuthError,
    AccessDeniedError,
    AgentNotFoundError,
    RateLimitError,
    AgentCommunicationError,
)
 
try:
    result = await gw.send("agent-123", "Hello")
except AuthError:
    print("Invalid API key")
except AgentNotFoundError:
    print("Agent not found or inactive")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except AgentCommunicationError:
    print("Agent failed to respond")
except GatewayError as e:
    print(f"Gateway error ({e.status_code}): {e}")

Exception	Status	When
`AuthError`	401	Missing or invalid API key
`AccessDeniedError`	403	No access to a private agent
`AgentNotFoundError`	404	Agent doesn’t exist or is inactive
`RateLimitError`	429	Rate limit exceeded
`AgentCommunicationError`	502	Upstream agent failed to respond
`GatewayError`	any	Base class for all errors

Full Example


import asyncio
from hybro_hub import HybroGateway
 
async def main():
    async with HybroGateway(api_key="hybro_...") as gw:
        # Discover
        agents = await gw.discover("legal contract review")
        print(f"Found {len(agents)} agents")
 
        # Send
        result = await gw.send(agents[0].agent_id, "Review this contract...")
        print(result)
 
        # Stream
        async for event in gw.stream(agents[0].agent_id, "Summarize findings"):
            print(event.data)
 
asyncio.run(main())