Guides

This is the documentation for unreleased changes on main. For the released library, read v0.1.

Each guide is one feature: what it is for, the code that uses it, and the mistakes that are easy to make. They are the same files that ship as skills for coding agents (psych skills install), so there is one copy and it is the tested one.

If you have not run an agent yet, start with Get started.

Give an agent things to do

• Define an agent: instructions, model, limits, what stops a Run.
• Connect Python functions as tools.
• Call an HTTP endpoint as a tool, with no function to write.
• Connect MCP servers, and authenticate to one with OAuth 2.1.
• Work with other agents over A2A, in both directions.
• Run code the model writes, in a subprocess or a container.
• Load instructions on demand with skills.
• Remember facts across runs.
• Delegate to subagents.
• Run fixed steps as a workflow, and build either with the fluent builder.

Control a run

• Require approval for selected tool calls.
• Stop or steer a running agent.
• Pause a run and resume it later: questions, webhooks, waiting on a clock.
• Keep a long conversation inside the window.

Read a run

• Stream results and reconnect.
• Inspect a run: report, status, answer.
• Track token usage and cost.
• Export spans with OpenTelemetry.

Operate it

• Persist and recover runs: PostgreSQL, MySQL, DynamoDB, and what the in-memory store is for.
• Handle large tool results.
• Serve multiple tenants safely: Scope, Policy, egress.
• Test agents without a network.
• First run, in detail: the full walkthrough, including the long form session() expands to.