AgentOSClient provides a convenient interface for interacting with a running AgentOS instance. It supports all AgentOS operations including running agents, teams, and workflows, managing sessions and memories, and searching knowledge bases.
Basic Usage
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
base_url | str | Required | Base URL of the AgentOS instance (e.g., "http://localhost:7777") |
timeout | float | 60.0 | Request timeout in seconds |
Methods
Discovery & Configuration
aget_config
Get AgentOS configuration and metadata asynchronously.
ConfigResponse containing:
os_id: Unique identifier for the OS instancename: Name of the OS instanceagents: List of registered agentsteams: List of registered teamsworkflows: List of registered workflowsinterfaces: List of available interfaces
get_config
Synchronous version of aget_config.
list_agents
List all agents configured in the AgentOS instance.
List[AgentSummaryResponse]
aget_agent
Get detailed configuration for a specific agent.
agent_id(str): ID of the agent to retrieve
AgentResponse
list_teams
List all teams configured in the AgentOS instance.
List[TeamSummaryResponse]
aget_team
Get detailed configuration for a specific team.
team_id(str): ID of the team to retrieve
TeamResponse
list_workflows
List all workflows configured in the AgentOS instance.
List[WorkflowSummaryResponse]
aget_workflow
Get detailed configuration for a specific workflow.
workflow_id(str): ID of the workflow to retrieve
WorkflowResponse
Running Agents
run_agent
Execute an agent run (non-streaming).
| Parameter | Type | Default | Description |
|---|---|---|---|
agent_id | str | Required | ID of the agent to run |
message | str | Required | The message/prompt for the agent |
session_id | Optional[str] | None | Session ID for context persistence |
user_id | Optional[str] | None | User ID for the run |
images | Optional[Sequence[Image]] | None | Images to include |
audio | Optional[Sequence[Audio]] | None | Audio to include |
videos | Optional[Sequence[Video]] | None | Videos to include |
files | Optional[Sequence[File]] | None | Files to include |
session_state | Optional[Dict] | None | Session state dictionary |
dependencies | Optional[Dict] | None | Dependencies dictionary |
metadata | Optional[Dict] | None | Metadata dictionary |
knowledge_filters | Optional[Dict] | None | Filters for knowledge search |
RunOutput
run_agent_stream
Stream an agent run response.
run_agent
Yields: RunOutputEvent (one of RunStartedEvent, RunContentEvent, RunToolCallEvent, RunCompletedEvent, etc.)
continue_agent_run
Continue a paused agent run with tool results.
| Parameter | Type | Default | Description |
|---|---|---|---|
agent_id | str | Required | ID of the agent |
run_id | str | Required | ID of the run to continue |
tools | List[ToolExecution] | Required | Tool execution results |
session_id | Optional[str] | None | Session ID |
user_id | Optional[str] | None | User ID |
RunOutput
cancel_agent_run
Cancel an agent run.
Running Teams
run_team
Execute a team run (non-streaming).
| Parameter | Type | Default | Description |
|---|---|---|---|
team_id | str | Required | ID of the team to run |
message | str | Required | The message/prompt for the team |
session_id | Optional[str] | None | Session ID for context persistence |
user_id | Optional[str] | None | User ID for the run |
images | Optional[Sequence[Image]] | None | Images to include |
audio | Optional[Sequence[Audio]] | None | Audio to include |
videos | Optional[Sequence[Video]] | None | Videos to include |
files | Optional[Sequence[File]] | None | Files to include |
TeamRunOutput
run_team_stream
Stream a team run response.
TeamRunOutputEvent
cancel_team_run
Cancel a team run.
Running Workflows
run_workflow
Execute a workflow run (non-streaming).
| Parameter | Type | Default | Description |
|---|---|---|---|
workflow_id | str | Required | ID of the workflow to run |
message | str | Required | The message/prompt for the workflow |
session_id | Optional[str] | None | Session ID for context persistence |
user_id | Optional[str] | None | User ID for the run |
WorkflowRunOutput
run_workflow_stream
Stream a workflow run response.
WorkflowRunOutputEvent
cancel_workflow_run
Cancel a workflow run.
Memory Operations
create_memory
Create a new user memory.
| Parameter | Type | Default | Description |
|---|---|---|---|
memory | str | Required | The memory content to store |
user_id | str | Required | User ID to associate with the memory |
topics | Optional[List[str]] | None | Topics to categorize the memory |
db_id | Optional[str] | None | Database ID to use |
UserMemorySchema
list_memories
List user memories with filtering and pagination.
| Parameter | Type | Default | Description |
|---|---|---|---|
user_id | Optional[str] | None | Filter by user ID |
topics | Optional[List[str]] | None | Filter by topics |
search_content | Optional[str] | None | Search within memory content |
limit | int | 20 | Number of memories per page |
page | int | 1 | Page number |
PaginatedResponse[UserMemorySchema]
get_memory
Get a specific memory by ID.
UserMemorySchema
update_memory
Update an existing memory.
UserMemorySchema
delete_memory
Delete a specific memory.
Session Operations
create_session
Create a new session.
| Parameter | Type | Default | Description |
|---|---|---|---|
session_type | SessionType | SessionType.AGENT | Type of session (AGENT, TEAM, WORKFLOW) |
session_id | Optional[str] | None | Optional session ID (auto-generated if not provided) |
user_id | Optional[str] | None | User ID to associate with the session |
session_name | Optional[str] | None | Human-readable session name |
agent_id | Optional[str] | None | Agent ID (for agent sessions) |
team_id | Optional[str] | None | Team ID (for team sessions) |
workflow_id | Optional[str] | None | Workflow ID (for workflow sessions) |
AgentSessionDetailSchema, TeamSessionDetailSchema, or WorkflowSessionDetailSchema
get_sessions
List sessions with filtering and pagination.
PaginatedResponse[SessionSchema]
get_session
Get a specific session by ID.
AgentSessionDetailSchema, TeamSessionDetailSchema, or WorkflowSessionDetailSchema
get_session_runs
Get all runs for a specific session.
List[RunSchema | TeamRunSchema | WorkflowRunSchema]
rename_session
Rename a session.
delete_session
Delete a specific session.
Knowledge Operations
upload_knowledge_content
Upload content to the knowledge base.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | Optional[str] | None | Content name |
description | Optional[str] | None | Content description |
url | Optional[str] | None | URL to fetch content from |
file | Optional[File] | None | File object to upload |
text_content | Optional[str] | None | Raw text content |
reader_id | Optional[str] | None | Reader to use for processing |
chunker | Optional[str] | None | Chunking strategy |
ContentResponseSchema
search_knowledge
Search the knowledge base.
| Parameter | Type | Default | Description |
|---|---|---|---|
query | str | Required | Search query string |
max_results | Optional[int] | None | Maximum results to return |
filters | Optional[Dict] | None | Filters to apply |
search_type | Optional[str] | None | Search type (vector, keyword, hybrid) |
PaginatedResponse[VectorSearchResult]
list_knowledge_content
List all content in the knowledge base.
PaginatedResponse[ContentResponseSchema]
get_knowledge_config
Get knowledge base configuration.
KnowledgeConfigResponse
Trace Operations
get_traces
List execution traces with filtering and pagination.
PaginatedResponse[TraceSummary]
get_trace
Get detailed trace information.
TraceDetail or TraceNode (if span_id provided)
Metrics Operations
get_metrics
Retrieve AgentOS metrics and analytics data.
MetricsResponse
refresh_metrics
Manually trigger recalculation of system metrics.
List[DayAggregatedMetrics]
Error Handling
The client raisesRemoteServerUnavailableError when the remote server is unavailable:
httpx.HTTPStatusError.
Authentication
To include authentication headers in requests, pass theheaders parameter to any method: