# Remote Execution (/agent-os/remote-execution/overview)
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 [#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 [#quick-start]
Install the AgentOS server and OpenAI dependencies:
```bash
uv pip install -U "agno[os]" openai
```
Export your OpenAI API key:
Mac/Linux
Windows
```bash
export OPENAI_API_KEY="your_openai_api_key_here"
```
```powershell
$Env:OPENAI_API_KEY="your_openai_api_key_here"
```
### 1. Set Up a Remote AgentOS Server [#1-set-up-a-remote-agentos-server]
First, create and run an AgentOS instance that will host your agents:
```python
# 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
python server.py
```
### 2. Connect and Execute Remotely [#2-connect-and-execute-remotely]
Use `RemoteAgent` to execute the agent from another application:
```python
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 [#3-create-an-agentos-gateway]
Save the following as `gateway.py`. Keep `server.py` running in its terminal, then run `python gateway.py` in a second terminal with the same dependencies and `OPENAI_API_KEY`. The gateway serves port 7777 and calls the example server on port 7778:
```python
from agno.agent import Agent, RemoteAgent
from agno.models.openai import OpenAIResponses
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://localhost: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 [#connecting-to-a2a-compatible-servers]
Remote wrappers implement A2A HTTP REST and JSON-RPC bindings. Select the binding supported by the server; gRPC is not implemented.
This alternative assumes a separately running [Google ADK A2A server](https://google.github.io/adk-docs/a2a/) exposing `facts_agent` over JSON-RPC on port 8001:
```python
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())
```
## Learn More [#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