Runa Guides¶

These guides assume you've read Getting Started with Runa. Each one stands alone. Read whichever covers what you're building today.

Start Here¶

• Getting Started with Runa. Install Runa, scaffold an app, and run your first agent.

Core Concepts¶

• Agents. The Agent class: attributes, instructions, run/run_sync/run_streamed, history, usage, and context.

• Tools. Exposing functions to the model with @tool.

• Guardrails. Checking input and output with @guardrail.

• Subagents. Composing agents with .handoff and .delegate.

Running Agents¶

• Sessions and Chat. Persisting conversation history with session=, and runa chat.

• Memory. Long-term, semantic memory that persists across conversations.

• Knowledge. Retrieving the application's own documents by meaning, before every turn.

• Cache. A minimal get/set/delete/clear cache, independent of Agent, Memory, and Sessions.

• MCP Servers. Connecting to external tool servers over MCP.

• Human Approval. Gating sensitive tool calls behind human approval, and how that differs from a guardrail.

Testing and Evaluation¶

• Evaluation. Behavioral evals with runa eval.

Observability¶

• Tracing and Hooks. What gets recorded for every run, runa traces, and lifecycle hooks.

Reference¶

• Model Providers. Which model string picks which provider, and where its API key lives.

• CLI Reference. Every runa command in one place.