Remote Execution
Execute agents, teams, and workflows hosted on remote AgentOS instances
Remote execution enables you to run agents, teams, and workflows that are hosted on remote AgentOS instances. This is useful for:
- Distributed architectures: Run specialized agents on different servers
- Microservices: Decompose your agentic system into independent services
- Gateway pattern: Create a unified API for multiple AgentOS instances
Agno supports remote connections to AgentOS instances and A2A-compatible servers.
See RemoteAgent, RemoteTeam, and RemoteWorkflow for more information.
Core Components
RemoteAgent
Execute agents on remote AgentOS instances
RemoteTeam
Execute teams on remote AgentOS instances
RemoteWorkflow
Execute workflows on remote AgentOS instances
AgentOSClient
Low-level client for direct API access to any AgentOS endpoint
A2AClient
Low-level client for direct API access to any A2A endpoint
Quick Start
Install the AgentOS server and OpenAI dependencies:
uv pip install -U "agno[os]" openaiExport your OpenAI API key:
export OPENAI_API_KEY="your_openai_api_key_here"1. Set Up a Remote AgentOS Server
First, create and run an AgentOS instance that will host your agents:
# server.py
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
agent = Agent(
name="Assistant",
id="assistant-agent",
model=OpenAIResponses(id="gpt-5.2"),
instructions="You are a helpful assistant.",
)
agent_os = AgentOS(
id="remote-server",
agents=[agent],
)
app = agent_os.get_app()
if __name__ == "__main__":
agent_os.serve(app="server:app", port=7778)Run the server:
python server.py2. Connect and Execute Remotely
Use RemoteAgent to execute the agent from another application:
import asyncio
from agno.agent import RemoteAgent
async def main():
agent = RemoteAgent(
base_url="http://localhost:7778", # Running on localhost for this example
agent_id="assistant-agent",
)
response = await agent.arun("Hello, how are you?")
print(response.content)
asyncio.run(main())3. Create an AgentOS Gateway
Save the following as gateway.py. Keep server.py running in its terminal, then run python gateway.py in a second terminal with the same dependencies and OPENAI_API_KEY. The gateway serves port 7777 and calls the example server on port 7778:
from agno.agent import Agent, RemoteAgent
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
local_agent = Agent(
name="Research Agent",
id="research-agent",
model=OpenAIResponses(id="gpt-5.2"),
instructions="You are a research assistant.",
)
gateway = AgentOS(
id="api-gateway",
agents=[
local_agent,
RemoteAgent(base_url="http://localhost:7778", agent_id="assistant-agent"),
],
)
app = gateway.get_app()
if __name__ == "__main__":
gateway.serve(app="gateway:app", port=7777)See Gateway Pattern for more details.
Connecting to A2A-Compatible Servers
Remote wrappers implement A2A HTTP REST and JSON-RPC bindings. Select the binding supported by the server; gRPC is not implemented.
This alternative assumes a separately running Google ADK A2A server exposing facts_agent over JSON-RPC on port 8001:
import asyncio
from agno.agent import RemoteAgent
async def main():
# Connect to a Google ADK A2A server
agent = RemoteAgent(
base_url="http://localhost:8001", # Running on localhost for this example
agent_id="facts_agent",
protocol="a2a",
a2a_protocol="json-rpc", # Google ADK uses JSON-RPC
)
response = await agent.arun("Tell me an interesting fact")
print(response.content)
asyncio.run(main())