AgentOS Gateway

Create a unified API gateway for multiple AgentOS instances

The gateway pattern allows you to create a single AgentOS instance that aggregates agents, teams, and workflows from multiple remote AgentOS instances. This provides a unified API endpoint for your distributed agentic infrastructure.

Use Cases

  • Unified API: Single endpoint for all your agents across different servers
  • Load distribution: Spread specialized agents across multiple servers
  • Microservices architecture: Each service hosts its own agents
  • Hybrid deployments: Combine local and remote agents in one interface

Basic Gateway Setup

Install uv pip install -U "agno[os]". Each example is an alternative gateway.py configuration; replace the illustrative hostnames and resource IDs with separately running servers, then start it with python gateway.py. See the local walkthrough for a server and gateway you can run together.

from agno.agent import RemoteAgent
from agno.team import RemoteTeam
from agno.workflow import RemoteWorkflow
from agno.os import AgentOS

# Create the gateway AgentOS
gateway = AgentOS(
    id="api-gateway",
    description="Unified API gateway for distributed agents",
    agents=[
        RemoteAgent(base_url="http://server-1:7778", agent_id="assistant-agent"),
        RemoteAgent(base_url="http://server-2:7778", agent_id="researcher-agent"),
    ],
    teams=[
        RemoteTeam(base_url="http://server-3:7778", team_id="research-team"),
    ],
    workflows=[
        RemoteWorkflow(base_url="http://server-4:7778", workflow_id="qa-workflow"),
    ],
)

app = gateway.get_app()
if __name__ == "__main__":
    gateway.serve(app="gateway:app", port=7777)

Combining Local and Remote

For local OpenAI agents, also install openai and "psycopg[binary]", set OPENAI_API_KEY in the gateway terminal, and start PostgreSQL on port 5532 with the shown credentials, or replace db_url. The remote servers still need their own setup:

from agno.agent import Agent, RemoteAgent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.db.postgres import PostgresDb

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

# Local agent
local_agent = Agent(
    name="Q&A Agent",
    id="question-answer-agent",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions="You are a helpful question and answer assistant.",
    db=db,
)

# Remote agents from other servers
remote_assistant = RemoteAgent(
    base_url="http://assistant-server:7778",
    agent_id="assistant-agent",
)

remote_researcher = RemoteAgent(
    base_url="http://research-server:7778",
    agent_id="researcher-agent",
)

# Gateway combining both
gateway = AgentOS(
    id="hybrid-gateway",
    agents=[local_agent, remote_assistant, remote_researcher],
)

app = gateway.get_app()

if __name__ == "__main__":
    gateway.serve(app="gateway:app", port=7777)

Complete Gateway Example

Here's a complete example with remote agents, teams, and workflows, plus a local workflow:

from agno.agent import Agent, RemoteAgent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.team import RemoteTeam
from agno.workflow import RemoteWorkflow, Workflow
from agno.workflow.step import Step

# Database for local components
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

# Local agents for a local workflow
story_writer = Agent(
    name="Story Writer",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions="Write a 100 word story based on the given topic",
)

story_editor = Agent(
    name="Story Editor",
    model=OpenAIResponses(id="gpt-5.2"),
    instructions="Review and improve the story's grammar and flow",
)

# Local workflow using local agents
story_workflow = Workflow(
    name="Story Generation",
    id="story-workflow",
    description="Generate and edit stories",
    db=db,
    steps=[
        Step(name="write_story", agent=story_writer),
        Step(name="edit_story", agent=story_editor),
    ],
)

# Gateway combining local and remote components
gateway = AgentOS(
    id="content-gateway",
    description="Gateway for content generation services",
    agents=[
        # Remote agents from specialized servers
        RemoteAgent(base_url="http://server-1:7778", agent_id="assistant-agent"),
        RemoteAgent(base_url="http://server-1:7778", agent_id="researcher-agent"),
    ],
    teams=[
        # Remote team
        RemoteTeam(base_url="http://server-1:7778", team_id="research-team"),
    ],
    workflows=[
        # Remote workflow
        RemoteWorkflow(base_url="http://server-1:7778", workflow_id="qa-workflow"),
        # Local workflow
        story_workflow,
    ],
)

app = gateway.get_app()

if __name__ == "__main__":
    gateway.serve(app="gateway:app", reload=True, port=7777)

See the full example.

Authentication Considerations

Remote wrappers have no constructor-level headers setting. Their metadata discovery calls do not send the per-run auth_token, so a gateway cannot discover metadata from an upstream that requires a bearer credential on those calls. Per-run authentication does not resolve this limitation. Account for it when selecting a backend and its network/access policy.

For direct calls to protected metadata, use AgentOSClient and pass headers on each method. That is a direct-client alternative; it does not add authenticated discovery to the gateway wrappers.