> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-docs-audit-20260719-0149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Remote Agent

> Execute agents hosted on remote AgentOS instances

`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 [Run Your AgentOS](/agent-os/run-your-os) to set one up.

## Basic Usage

```python theme={null}
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:

```python theme={null}
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",
    )

    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)

asyncio.run(main())
```

## Configuration Access

Access the remote agent's configuration:

```python theme={null}
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",
    )

    # 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
    await agent.refresh_config()

asyncio.run(main())
```

## Authentication

For authenticated AgentOS instances:

```python theme={null}
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",
    )

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

asyncio.run(main())
```

## Error Handling

```python theme={null}
import asyncio
from agno.agent import RemoteAgent
from agno.exceptions import RemoteServerUnavailableError

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

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

asyncio.run(main())
```

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

```python theme={null}
import asyncio
from agno.agent import RemoteAgent

async def main():
    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)

asyncio.run(main())
```

### Connecting to Google ADK

```python theme={null}
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())
```

## Developer Resources

* [RemoteAgent Reference](/reference/agents/remote-agent) for complete API documentation.
* [RemoteAgent Example](/agent-os/usage/remote-execution/remote-agent) for a complete example.
* [A2A Client](/agent-os/client/a2a-client) for direct A2A protocol access.