Skip to main content
The AgentOSClient provides a Python interface for interacting with running AgentOS instances. It enables you to:
  • Run agents, teams, and workflows programmatically with streaming support
  • Manage sessions for conversation persistence across runs
  • Search and manage knowledge in connected knowledge bases
  • Access memories stored for users
  • Monitor traces for debugging and observability

​
Quick Start

import asyncio
from agno.client import AgentOSClient

async def main():
    # Connect to AgentOS
    client = AgentOSClient(base_url="http://localhost:7777")
    
    # Get configuration and available agents
    config = await client.aget_config()
    print(f"Connected to: {config.name or config.os_id}")
    print(f"Available agents: {[a.id for a in config.agents]}")
    
    # Run an agent
    if config.agents:
        result = await client.run_agent(
            agent_id=config.agents[0].id,
            message="Hello, how can you help me?",
        )
        print(f"Response: {result.content}")

asyncio.run(main())

​
Streaming Responses

The client supports streaming for real-time response handling: 
from agno.run.agent import RunContentEvent, RunCompletedEvent

async for event in client.run_agent_stream(
    agent_id="my-agent",
    message="Tell me a story",
):
    if isinstance(event, RunContentEvent):
        print(event.content, end="", flush=True)
    elif isinstance(event, RunCompletedEvent):
        print(f"\nCompleted! Run ID: {event.run_id}")

​
Authentication

When connecting to authenticated AgentOS instances, pass headers with your requests: 
headers = {"Authorization": "Bearer your-jwt-token"}

config = await client.aget_config(headers=headers)
result = await client.run_agent(
    agent_id="my-agent",
    message="Hello",
    headers=headers,
)

​
Error Handling

from agno.exceptions import RemoteServerUnavailableError

try:
    config = await client.aget_config()
except RemoteServerUnavailableError as e:
    print(f"Server unavailable: {e.message}")
    print(f"URL: {e.base_url}")

​
Examples

Basic Client

Connect and explore an AgentOS instance

Run Agents

Execute streaming and non-streaming agent runs

Run Teams

Execute team runs with member coordination

Run Workflows

Execute workflow pipelines

Session Management

Create, list, and manage sessions

Knowledge Search

Search and upload knowledge content

Memory Operations

Create, list, and manage user memories

​
API Reference

For complete method documentation and parameters, see the AgentOSClient Reference.