AgentOS Teams API

Prerequisites

Start an AgentOS server with teams configured:

export ANTHROPIC_API_KEY=sk-...
uv run start_agentos.py  # See agno-agentos skill

Default: Use the CLI Script

Always try the provided script first. It covers listing teams, running teams (streaming and non-streaming), and session persistence — all from the command line with no custom code needed.

The script is at: scripts/run_teams.py

List all teams

uv run scripts/run_teams.py --base-url http://localhost:7777

Show full AgentOS config

uv run scripts/run_teams.py --base-url http://localhost:7777 --config

Show team-specific config (members, models, tools)

uv run scripts/run_teams.py --base-url http://localhost:7777 --config --team-id my-team

Run a team with a message

uv run scripts/run_teams.py --base-url http://localhost:7777 \
  --team-id research-team \
  -m "Compare Python and Rust"

Stream a response

uv run scripts/run_teams.py --base-url http://localhost:7777 \
  --team-id research-team \
  -m "Analyze Tesla stock" --stream

Persistent sessions

uv run scripts/run_teams.py --base-url http://localhost:7777 \
  --team-id research-team \
  -m "Analyze NVIDIA" --session-id research-1

uv run scripts/run_teams.py --base-url http://localhost:7777 \
  --team-id research-team \
  -m "Now compare to AMD" --session-id research-1

Run against a remote server

uv run scripts/run_teams.py --base-url http://my-server:8000 \
  -m "Research AI trends"

Full CLI reference

uv run scripts/run_teams.py --help

When to Write Custom Python

Only write ad-hoc Python when the CLI script cannot handle your use case:

• Cancel a team run mid-execution
• Chaining multiple team calls in a single script
• Custom error handling or retry logic
• Programmatic inspection of team config beyond what --config shows
• Integration tests that assert on response content
• Authentication with custom headers (e.g., JWT tokens)

API Endpoints

Method	Path	Description
GET	/teams	List all teams
GET	/teams/{team_id}	Get team details
POST	/teams/{team_id}/runs	Create team run
POST	/teams/{team_id}/cancel_run	Cancel team run

Custom Python Examples

Cancel Team Run

await client.cancel_team_run(
    team_id=team_id,
    run_id=run_id,
)

Authentication

When the AgentOS instance has a security key configured:

result = await client.run_team(
    team_id=team_id,
    message="Research topic",
    headers={"Authorization": "Bearer your-jwt-token"},
)

Error Handling

from agno.client import AgentOSClient, RemoteServerUnavailableError

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

Anti-Patterns

• Don't write custom Python for basic list/run operations — use the CLI script
• Don't forget await — all client methods are async
• Don't hardcode team IDs — discover them from aget_config() or the CLI script
• Don't confuse team and agent imports — teams use from agno.run.team import RunContentEvent
• Don't skip discovery — always call aget_config() first to verify teams exist
• Don't forget the server — start AgentOS before running client code

Further Reading

For advanced team API patterns, read references/api-patterns.md.