# AgentOS Gateway (/agent-os/remote-execution/gateway)



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 [#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 [#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](/agent-os/remote-execution/overview) for a server and gateway you can run together.

```python
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 [#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](/database/providers/postgres/usage/postgres-for-agent) on port 5532 with the shown credentials, or replace `db_url`. The remote servers still need their own setup:

```python
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 [#complete-gateway-example]

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

```python
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](/agent-os/usage/remote-execution/gateway).

## Authentication Considerations [#authentication-considerations]

<Warning>
  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.
</Warning>

For direct calls to protected metadata, use [AgentOSClient](/agent-os/client/agentos-client#authentication) and pass headers on each method. That is a direct-client alternative; it does not add authenticated discovery to the gateway wrappers.
