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

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