> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

Create a gateway that aggregates remote agents from multiple servers:

```python theme={null}
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

Mix local agents with remote agents in the same gateway:

```python theme={null}
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:

```python theme={null}
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](https://agno-v2.mintlify.site/agent-os/usage/remote-execution/gateway.md).

## Authentication Considerations

> [!WARNING]
>
> If authorization is enabled on remote servers and all endpoints are protected, not all gateway functions will work correctly.
> Specifically, the following endpoints need to be unprotected on remote servers for the gateway to work:
>
> * `/config`
> * `/agents`
> * `/agents/{agent_id}`
> * `/teams`
> * `/teams/{team_id}`
> * `/workflows`
> * `/workflows/{workflow_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.