From agno-agentos-api
Interact with AgentOS Session API endpoints. For standard operations (listing, creating, renaming, deleting sessions, viewing runs), use the provided CLI script first. Only write custom Python when the script cannot handle the use case (e.g., persistent conversations, clearing history, bulk deletion, advanced filtering). Trigger when: managing sessions remotely, inspecting session history, creating session tests, or asking things like "find me all sessions from the researcher agent" or "get the latest runs from session X."
How this skill is triggered — by the user, by Claude, or both
Slash command
/agno-agentos-api:agentos-api-sessionsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use `agno.client.AgentOSClient` to create, list, inspect, rename, and delete sessions on a remote AgentOS instance. Sessions maintain conversation history and context across runs.
Use agno.client.AgentOSClient to create, list, inspect, rename, and delete sessions on a remote AgentOS instance. Sessions maintain conversation history and context across runs.
Start an AgentOS server with storage configured:
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.db.sqlite import SqliteDb
from agno.os import AgentOS
db = SqliteDb(db_file="tmp/app.db")
agent = Agent(
name="Assistant",
model=Claude(id="claude-sonnet-4-5"),
db=db,
add_history_to_context=True,
num_history_runs=5,
)
agent_os = AgentOS(agents=[agent])
agent_os.serve()
Always try the provided script first. It covers listing sessions, creating sessions, inspecting session details, viewing runs, renaming, and deleting — all from the command line with no custom code needed.
The script is at: scripts/manage_sessions.py
uv run scripts/manage_sessions.py --base-url http://localhost:7777
uv run scripts/manage_sessions.py --base-url http://localhost:7777 \
--agent-id researcher
uv run scripts/manage_sessions.py --base-url http://localhost:7777 \
--user-id [email protected]
uv run scripts/manage_sessions.py --base-url http://localhost:7777 \
--session-id abc-123
uv run scripts/manage_sessions.py --base-url http://localhost:7777 \
--session-id abc-123 --show-runs
uv run scripts/manage_sessions.py --base-url http://localhost:7777 \
--create --agent-id my-agent --user-id alice --name "Research Chat"
uv run scripts/manage_sessions.py --base-url http://localhost:7777 \
--session-id abc-123 --rename "New Name"
uv run scripts/manage_sessions.py --base-url http://localhost:7777 \
--session-id abc-123 --delete
uv run scripts/manage_sessions.py --help
Only write ad-hoc Python when the CLI script cannot handle your use case:
| Method | Path | Description |
|---|---|---|
| GET | /sessions | List sessions (paginated, filterable) |
| GET | /sessions/{session_id} | Get session by ID |
| GET | /sessions/{session_id}/runs | Get session runs |
| GET | /sessions/{session_id}/runs/{run_id} | Get specific run |
| POST | /sessions | Create new session |
| PATCH | /sessions/{session_id} | Update session |
| POST | /sessions/{session_id}/rename | Rename session |
| DELETE | /sessions/{session_id} | Delete session |
| POST | /sessions/{session_id}/clear | Clear session history |
| DELETE | /sessions | Delete multiple sessions |
import asyncio
from agno.client import AgentOSClient
async def main():
client = AgentOSClient(base_url="http://localhost:7777")
config = await client.aget_config()
agent_id = config.agents[0].id
session_id = "persistent-session-1"
# First message
result1 = await client.run_agent(
agent_id=agent_id,
message="My name is Alice.",
session_id=session_id,
)
# Second message — agent remembers
result2 = await client.run_agent(
agent_id=agent_id,
message="What's my name?",
session_id=session_id,
)
print(result2.content) # Should mention Alice
asyncio.run(main())
Erase all conversation history while keeping the session:
await client.clear_session("session-id-here")
The list endpoint supports filtering beyond what the CLI provides:
async def main():
client = AgentOSClient(base_url="http://localhost:7777")
sessions = await client.get_sessions(
type="agent",
session_name="Research",
sort_by="created_at",
sort_order="asc",
limit=50,
page=2,
)
for sess in sessions.data:
print(f" {sess.session_id}: {sess.session_name or 'Unnamed'}")
db= on agents — without storage, sessions don't persist between API callssession_id for continuous conversationsadd_history_to_context=True — without it, agents won't recall prior messageslimit and page when listing many sessionsFor advanced session management patterns, read references/api-patterns.md.
npx claudepluginhub ajshedivy/agno-cookbook --plugin agno-agentos-apiManages Claude AI sub-agent sessions via agent-deck CLI: launch child sessions, check status, retrieve outputs, attach MCP tools like exa.
Agent-to-agent messaging bus for Claude Code. Sends messages between local sessions, delegates tasks, fans-out work, and coordinates concurrent agents on the same machine.
Hands off sessions between agents using the entire CLI. Inspects recent sessions, summarizes checkpoints, and continues work without asking clarifying questions.