AgentOS Read Endpoints

Inspect runs, replay sessions, and list approval requirements over HTTP

AgentOS can list and inspect past runs, replay a session’s transcript, and list which tools require approval — all over HTTP, with 503 (not an empty list) when the underlying store is missing.

Quick Start

1. Attach a ledger and serve

   Attaching a SQLiteRunLedger unlocks /api/runs and /api/runs/{run_id}.

   from praisonai import AgentOS
   from praisonaiagents import Agent
   from praisonaiagents.runs import SQLiteRunLedger
   
   app = AgentOS(agents=[Agent(instructions="Be helpful")])
   app.run_ledger = SQLiteRunLedger()   # unlocks /api/runs and /api/runs/{id}
   app.serve(port=8000)

2. Read runs over HTTP

   curl http://localhost:8000/api/runs?limit=10
   curl http://localhost:8000/api/runs/<run_id>

Enabling Each Endpoint

Each endpoint reads a store you attach to the AgentOS instance.

from praisonaiagents.runs import SQLiteRunLedger

app.run_ledger = SQLiteRunLedger()

from praisonaiagents.session import DefaultSessionStore

app.session_store = DefaultSessionStore()

from praisonaiagents.approval import add_approval_requirement

add_approval_requirement("delete_file", risk_level="high")

Endpoint Reference

Five read-only routes, each returning 503 naming what to configure when its store is absent.

Response Shapes

Every response matches the endpoint’s contract exactly.

{ "runs": [ { "run_id": "r1", "status": "done" } ], "count": 1 }

{ "run_id": "r1", "status": "done", "agent": "researcher" }

{ "sessions": [ { "session_id": "s1", "messages": 4 } ], "count": 1 }

{ "session_id": "s1", "messages": [ { "role": "user", "content": "hi" } ] }

{ "requirements": [ { "tool": "delete_file", "agent": null, "risk_level": "high" } ] }

Why the Errors Look Like This

Choosing an Endpoint

This decision diagram maps a question to the endpoint that answers it.

How Operators Interact

An operator lists runs; the ledger either answers or the endpoint says what to attach.

Best Practices

Related