Create Agent Run

Example server

Install the runtime and model dependencies, then set your model key and a shared API key:

uv pip install -U "agno[os]" openai sqlalchemy
export OPENAI_API_KEY="your-openai-api-key"
export OS_SECURITY_KEY="your-agentos-key"

Save this as reference_api.py and run python reference_api.py:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.os import AgentOS

agent = Agent(
    id="reference-agent",
    model=OpenAIChat(id="gpt-5.4-mini"),
    db=SqliteDb(db_file="tmp/reference-api.db"),
    add_history_to_context=True,
)
agent_os = AgentOS(agents=[agent])
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="reference_api:app", host="127.0.0.1", port=7777)

Send form fields and request a JSON response:

curl --fail-with-body http://127.0.0.1:7777/agents/reference-agent/runs \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -F 'message=Hello' -F 'session_id=reference-session' -F 'stream=false'

Keep the returned run_id and session_id for polling, cancellation and continuation. With stream=true, read Server-Sent Events (SSE).

Background responses

Local background execution requires the agent's database. A nonstreaming background submission returns 202 with run/session IDs and status, rather than the completed run shown by the generic response schema. Remote agents reject background execution.

background=true alone does not guarantee a durable queue job. Queue admission requires the durable queue setup and an eligible registered, nonfactory agent with a JSON-compatible request. Pinned versions, factory input and uploaded media prevent that queue path. See background execution for the execution modes.

Uploaded files must have a recognized type and the required reader dependencies; the selected model must support any media sent to it.

curl --request POST 'https://example.com/agents/string/runs' \  --form-string 'message=string'

null

{  "detail": "string",  "error_id": "string",  "error_type": "string"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}

{  "detail": "string"}

{  "detail": "string",  "error_id": "string",  "error_type": "string"}