AgentOS API

Learn how to use the AgentOS API to interact with your agentic system

AgentOS is a RESTful API that provides access to your agentic system.

It allows you to:

• Run Agents / Teams / Workflows: Create new runs for your agents, teams and workflows, either with a new session or a existing one.
• Manage Sessions: Retrieve, update and delete sessions.
• Manage Memories: Retrieve, update and delete memories.
• Manage Knowledge: Manage the content of your knowledge base.
• Manage Evals: Retrieve, create, delete and update evals.

This is the same API that powers the AgentOS Control Plane. However, the same endpoints can be used to power your own application!

See the full API reference for more details.

Authentication

AgentOS supports bearer-token authentication to secure your instance. When a Security Key is configured, all API routes require an Authorization: Bearer <token> header for access. Without a key configured, authentication is disabled.

For more details, see the AgentOS Security guide.

Running your Agent / Team / Workflow

The AgentOS API provides endpoints:

• Run an Agent: POST /agents/{agent_id}/runs (See the API reference)
• Run a Team: POST /teams/{team_id}/runs (See the API reference)
• Run a Workflow: POST /workflows/{workflow_id}/runs (See the API reference)

These endpoints support form-based input. Below is an example of how to run an agent with the API:

curl --location 'http://localhost:7777/agents/agno-agent/runs' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'message=Tell me about Agno.' \
    --data-urlencode 'stream=True' \
    --data-urlencode 'user_id=[e-mail]' \
    --data-urlencode 'session_id=session_123'

Passing agent parameters

Agent, Team and Workflow run() and arun() endpoints all support additional parameters. See the Agent arun schema, Team arun schema, Workflow arun schema for more details.

To pass these parameters to your agent, team or workflow, via the AgentOS API, you can simply specify them as form-based parameters.

Below is an example where dependencies are passed to the agent:

dependencies_to_agent.py

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.os import AgentOS

# Setup the database
db = PostgresDb(id="basic-db", db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

# Setup basic agents, teams and workflows
story_writer = Agent(
    id="story-writer-agent",
    name="Story Writer Agent",
    db=db,
    markdown=True,
    instructions="You are a story writer. You are asked to write a story about a robot. Always name the robot {robot_name}",
)

# Setup our AgentOS app
agent_os = AgentOS(
    description="Example AgentOS to show how to pass dependencies to an agent",
    agents=[story_writer],
)
app = agent_os.get_app()


if __name__ == "__main__":
    agent_os.serve(app="dependencies_to_agent:app", reload=True)

Then to test it, you can run the following command:

curl --location 'http://localhost:7777/agents/story-writer-agent/runs' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'message=Write me a 5 line story.' \
    --data-urlencode 'dependencies={"robot_name": "Anna"}'

Cancelling a Run

You can cancel a running agent, team or workflow by using the appropriate endpoint.

For example, to cancel an agent run:

curl --location 'http://localhost:7777/agents/story-writer-agent/runs/123/cancel'

• Agent API reference
• Team API reference
• Workflow API reference