Serve one AgentOS gateway over local and remote components
The gateway registers a local Agent alongside native AgentOS, Agno A2A REST, and Google ADK JSON-RPC components.
The gateway registers a local Agent alongside native AgentOS, Agno A2A REST, and Google ADK JSON-RPC components. Callers use one AgentOS API on port 7777 without needing to know which transport backs each entity.
"""
Serve one AgentOS gateway over local and remote components
==========================================================
The gateway registers a local Agent alongside native AgentOS, Agno A2A REST,
and Google ADK JSON-RPC components. Callers use one AgentOS API on port 7777
without needing to know which transport backs each entity.
Prerequisites: start all three files under `servers/`; set OPENAI_API_KEY and GOOGLE_API_KEY
Run: .venvs/demo/bin/python cookbook/05_agent_os/20_remote/05_gateway.py
Try: fetch GET http://127.0.0.1:7777/config, then run any listed entity
"""
from agno.agent import Agent, RemoteAgent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.team import RemoteTeam
from agno.workflow import RemoteWorkflow
# ---------------------------------------------------------------------------
# Create Local Component
# ---------------------------------------------------------------------------
db = SqliteDb(
id="remote-gateway-db",
db_file="tmp/remote_gateway.db",
)
gateway_agent = Agent(
id="gateway-agent",
name="Gateway Agent",
description="A local Agent registered beside remote components.",
model=OpenAIResponses(id="gpt-5.5"),
instructions="Answer briefly and identify yourself as the local gateway Agent.",
markdown=True,
)
# ---------------------------------------------------------------------------
# Create Remote Components
# ---------------------------------------------------------------------------
remote_agentos_agent = RemoteAgent(
base_url="http://127.0.0.1:7780",
agent_id="assistant-agent",
)
remote_a2a_agent = RemoteAgent(
base_url="http://127.0.0.1:7781/a2a/agents/a2a-assistant",
agent_id="a2a-assistant",
protocol="a2a",
a2a_protocol="rest",
)
remote_adk_agent = RemoteAgent(
base_url="http://127.0.0.1:8001",
agent_id="facts_agent",
protocol="a2a",
a2a_protocol="json-rpc",
)
remote_team = RemoteTeam(
base_url="http://127.0.0.1:7780",
team_id="research-team",
)
remote_workflow = RemoteWorkflow(
base_url="http://127.0.0.1:7780",
workflow_id="qa-workflow",
)
# ---------------------------------------------------------------------------
# Create Gateway AgentOS
# ---------------------------------------------------------------------------
agent_os = AgentOS(
id="remote-gateway-os",
name="Remote Gateway",
description="One AgentOS surface over local, AgentOS, and A2A components.",
db=db,
agents=[
gateway_agent,
remote_agentos_agent,
remote_a2a_agent,
remote_adk_agent,
],
teams=[remote_team],
workflows=[remote_workflow],
)
app = agent_os.get_app()
# ---------------------------------------------------------------------------
# Run Gateway AgentOS
# ---------------------------------------------------------------------------
if __name__ == "__main__":
agent_os.serve(app=app, host="127.0.0.1", port=7777)Run the Example
Set up your virtual environment
uv venv --python 3.12
source .venv/bin/activateInstall dependencies
uv pip install -U "agno[os]" openaiExport your OpenAI API key
export OPENAI_API_KEY="your_openai_api_key_here"Start the required upstream servers
Follow each linked server guide in its own terminal, installing its dependencies and setting its provider key there. Keep those processes running while this example executes.
| Server setup | Port |
|---|---|
| Native AgentOS | 7780 |
| Agno A2A | 7781 |
| Google ADK | 8001 |
Use the native server's default local setup with OS_SECURITY_KEY unset.
Wait for http://127.0.0.1:7780/health, http://127.0.0.1:7781/health, and http://127.0.0.1:8001/.well-known/agent-card.json to respond successfully. Gateway construction reads upstream metadata. Keep port 7777 free for the gateway.
Run the example
Save the code above as gateway.py, then run:
python gateway.pyFull source: cookbook/05_agent_os/20_remote/05_gateway.py