> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/agent-os/remote-execution/remote-agent), [RemoteTeam](/agent-os/remote-execution/remote-team), and [RemoteWorkflow](/agent-os/remote-execution/remote-workflow) for more information.
## Core Components
Execute agents on remote AgentOS instances
Execute teams on remote AgentOS instances
Execute workflows on remote AgentOS instances
Low-level client for direct API access to any AgentOS endpoint
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:
```python theme={null}
# 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:
```bash theme={null}
python server.py
```
### 2. Connect and Execute Remotely
Use `RemoteAgent` to execute the agent from another application:
```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",
)
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:
```python theme={null}
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](/agent-os/remote-execution/gateway) 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:
```python theme={null}
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
Detailed guide on using RemoteAgent
Detailed guide on using RemoteTeam
Detailed guide on using RemoteWorkflow
Create a unified API gateway for multiple AgentOS instances