# Remote Agent (/agent-os/remote-execution/remote-agent)



`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 [#prerequisites]

Start the [Remote Execution quickstart server](/agent-os/remote-execution/overview#1-set-up-a-remote-agentos-server), which registers `assistant-agent` on port 7778. Follow its server dependencies and model-key setup. Install `uv pip install -U "agno[os]"` in a separate client environment. The examples use the unauthenticated local server from that quickstart.

## Basic Usage [#basic-usage]

```python
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 [#streaming-responses]

Stream response content. The remaining snippets use `await` or `async for`; run them inside an `async def` function, as in Basic Usage:

```python
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 [#configuration-access]

Properties fetch metadata synchronously on a cache miss or after the default 300-second TTL expires. `get_agent_config()` fetches fresh configuration asynchronously. These wrapper metadata calls do not forward an `auth_token`; the example below requires metadata access without credentials. For protected metadata use [AgentOSClient](/agent-os/client/agentos-client#authentication) with explicit per-request headers.

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

## Authentication [#authentication]

For a server configured with JWT authentication, pass its token per run. A static-security-key server accepts its `OS_SECURITY_KEY` value in the same parameter. This authenticates the run, not subsequent wrapper metadata requests:

```python
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 [#error-handling]

```python
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 [#a2a-protocol-support]

`RemoteAgent` supports compatible A2A HTTP REST and JSON-RPC endpoints. Set the binding explicitly when the remote server uses JSON-RPC. Available operations depend on the server; gRPC is not supported.

### Connecting to Agno AgentOS via A2A interface [#connecting-to-agno-agentos-via-a2a-interface]

In the server terminal, install `uv pip install -U "agno[a2a]"`, enable `a2a_interface=True` on the quickstart server's `AgentOS`, and restart it.

```python
from agno.agent import RemoteAgent

agent = RemoteAgent(
    base_url="http://localhost:7778/a2a/agents/assistant-agent",  # Running on localhost for this example
    agent_id="assistant-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 [#connecting-to-google-adk]

This alternative assumes a separate [Google ADK A2A server](https://google.github.io/adk-docs/a2a/) serving `facts_agent` over JSON-RPC on port 8001.

```python
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 [#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.