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

# AgentOS Client

> Connect to Agno AgentOS instances via REST API

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

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

Stream responses in real-time for a better user experience:

```python theme={null}
from agno.client import AgentOSClient
from agno.run.agent import RunContentEvent, RunCompletedEvent

client = AgentOSClient(base_url="http://localhost:7777")

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:

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

```python theme={null}
from agno.client import AgentOSClient
from agno.exceptions import RemoteServerUnavailableError

client = AgentOSClient(base_url="http://localhost:7777")

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

## API Reference

For complete method documentation, parameters, and response types, see the [AgentOSClient Reference](/reference/clients/agentos-client).

## Examples

<CardGroup cols={2}>
  <Card title="Basic Client" icon="plug" href="/agent-os/usage/client/basic-client">
    Connect and explore an AgentOS instance
  </Card>

  <Card title="Run Agents" icon="robot" href="/agent-os/usage/client/run-agents">
    Execute streaming and non-streaming agent runs
  </Card>

  <Card title="Run Teams" icon="users" href="/agent-os/usage/client/run-teams">
    Execute team runs with member coordination
  </Card>

  <Card title="Run Workflows" icon="diagram-project" href="/agent-os/usage/client/run-workflows">
    Execute workflow pipelines
  </Card>

  <Card title="Session Management" icon="messages" href="/agent-os/usage/client/session-management">
    Create, list, and manage sessions
  </Card>

  <Card title="Knowledge Search" icon="magnifying-glass" href="/agent-os/usage/client/knowledge-search">
    Search and upload knowledge content
  </Card>

  <Card title="Memory Operations" icon="brain" href="/agent-os/usage/client/memory-operations">
    Create, list, and manage user memories
  </Card>
</CardGroup>