Skip to main content
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

​
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.py

​
2. 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

Create a gateway that aggregates multiple AgentOS instances: 
from agno.agent import RemoteAgent
from agno.team import RemoteTeam
from agno.workflow import RemoteWorkflow
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://remote-server: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

Using the A2A protocol, you can connect to any A2A-compatible server. Here is an example of connecting to a Google ADK A2A server: 
from agno.agent import RemoteAgent

# 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)

​
Learn More

Remote Agent

Detailed guide on using RemoteAgent

Remote Team

Detailed guide on using RemoteTeam

Remote Workflow

Detailed guide on using RemoteWorkflow

Gateway Pattern

Create a unified API gateway for multiple AgentOS instances