Skip to main content
RemoteAgent allows you to execute agents that are running on a remote AgentOS instance as if they were local agents. This enables distributed architectures where specialized agents run on different servers.

​
Prerequisites

You need a running AgentOS instance with at least one agent. See Creating Your First OS to set one up.

​
Basic Usage

import asyncio
from agno.agent import RemoteAgent

async def main():
    # Connect to a remote agent
    agent = RemoteAgent(
        base_url="http://localhost:7778",  # Running on localhost for this example
        agent_id="assistant-agent",
    )
    
    # Run the agent
    response = await agent.arun("What is the capital of France?")
    print(response.content)

asyncio.run(main())

​
Streaming Responses

Stream responses in real-time for a better user experience: 
from agno.agent import RemoteAgent

agent = RemoteAgent(
    base_url="http://localhost:7778",  # Running on localhost for this example
    agent_id="assistant-agent",
)

async for event in agent.arun(
    "Tell me a story about a brave knight",
    stream=True,
):
    if hasattr(event, "content") and event.content:
        print(event.content, end="", flush=True)

​
Configuration Access

Access the remote agent’s configuration: 
from agno.agent import RemoteAgent

agent = RemoteAgent(
    base_url="http://localhost:7778",  # Running on localhost for this example
    agent_id="assistant-agent",
)

# Access cached properties
print(f"Name: {agent.name}")
print(f"Description: {agent.description}")
print(f"Tools: {agent.tools}")

# Get fresh configuration
config = await agent.get_agent_config()
print(f"Model: {config.model}")

# Force refresh cache
agent.refresh_config()

​
Authentication

For authenticated AgentOS instances: 
from agno.agent import RemoteAgent

agent = RemoteAgent(
    base_url="http://localhost:7778",  # Running on localhost for this example
    agent_id="assistant-agent",
)

response = await agent.arun(
    "Hello",
    auth_token="your-jwt-token",
)

​
Error Handling

from agno.agent import RemoteAgent
from agno.exceptions import RemoteServerUnavailableError

agent = RemoteAgent(
    base_url="http://localhost:7778",  # Running on localhost for this example
    agent_id="assistant-agent",
)

try:
    response = await agent.arun("Hello")
except RemoteServerUnavailableError as e:
    print(f"Cannot connect to server: {e.message}")
    # Handle fallback logic

​
A2A Protocol Support

RemoteAgent can also connect to any A2A-compatible server, enabling communication with agents built using other frameworks like Google ADK.

​
Connecting to Agno AgentOS via A2A interface

from agno.agent import RemoteAgent

agent = RemoteAgent(
    base_url="http://localhost:7778/a2a/agents/my-agent",  # Running on localhost for this example
    agent_id="my-agent",
    protocol="a2a",
    a2a_protocol="rest",  # Agno A2A servers use REST protocol by default
)

response = await agent.arun("Tell me an interesting fact")
print(response.content)

​
Connecting to Google ADK

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)

​
Developer Resources