Guides
How to do things in Platos
28 task-oriented walkthroughs. Each one starts from a working install and ends with something you can ship.
Getting started
5 guidesQuickstart: your first agent in 10 minutes
Run docker compose, link a provider key, create an agent, send a chat turn.
Self-host with docker compose
Stand up the full Platos stack with one compose file. Includes Postgres, Redis, ClickHouse, MinIO, agent, webapp.
Add a provider key (BYOK)
Link your OpenAI, Anthropic, or other provider key to a Platos environment via environment variables.
Create your first agent
Walk through the agent creation wizard from name to first chat turn.
Invite a teammate to a project
Add a collaborator to your Platos project and pick their role.
Integrations
6 guidesConnect an entity (TypeScript)
Stand up an entity backend with @platosdev/platools-sdk, declare your tools, and wire it to Platos.
Connect an entity (Python)
Same as the TypeScript guide, but using the platools Python package.
Consume Platos via MCP
Connect Claude Desktop, Cursor, or any MCP client to Platos with a PAT.
Import a Claude skill from a URL
Paste a Claude-compatible skill manifest URL and Platos will fetch, parse, and surface it.
Embed a public agent on a website
Drop the Platos web component on a page and let visitors chat with a guest token.
Subscribe to conversation events
Receive a signed POST every time a conversation starts, ends, or hits a safety event.
Recipes
11 guidesVersion, canary, and roll back an agent
Promote a canary version, watch its evals, and roll back if it regresses.
Run an A/B eval suite
Build a golden set, define criteria, and compare two agent versions head to head.
Extract long-term memory from a conversation
Configure the memory extractor to pull profile facts, preferences, and entities from a chat.
Send an image or PDF attachment
Upload a file via presigned URL and let the agent see it as a multimodal input.
Spawn a long-running task (BGO)
Use the spawn_bgo meta-tool to kick off durable work that exceeds a single turn.
Schedule a recurring task
Use schedule_bgo to run a Platos task on a cron expression.
Add a human approval gate to a tool
Mark a tool as needing approval, then approve or reject from the inbox or via webhook.
Set a per-agent budget cap
Cap daily or monthly spend per agent and decide what happens when the cap hits.
Configure a PII filter
Block or redact specific PII categories per agent and log every hit.
Publish a Postman conversation template
Save a chat turn as a reusable template that teammates can replay.
Build an agent cluster
Group a chat agent and a BGO agent so they share user identity, memory, and threads.
Troubleshooting
6 guidesTrace a single turn end to end
Open the trace view, walk the spans, and find the slow tool.
Debug a sudden cost spike
Drill from the cost dashboard into the run that caused the spike.
Recover a stuck run
Diagnose and recover a run that's stuck DEQUEUED or running too long.
Fix an ENCRYPTION_KEY length error
The webapp refuses to boot because ENCRYPTION_KEY isn't 32 ASCII characters. Fix it.
Chat stream keeps disconnecting
Diagnose dropped WebSocket streams from the chat UI or your own SDK consumer.
Backup and restore Postgres, ClickHouse, MinIO
Snapshot Platos's three persistent stores and restore them onto a fresh host.
