Core concepts
Agent Recipe → Runtime → Task → Conversation
↑ │
└──── Reviewed change ← Saved resultsHow the parts fit together
A Recipe is the set of files that defines an agent. It contains the agent definition, instructions, skills, extensions, permissions, and checks for good results. Git keeps a history of each Recipe version.
Pi is the program that runs the agent from its Recipe. Pi uses the same Recipe when you test on your computer and when Introspection runs the agent for you.
A runtime is one deployed Recipe version. The runtime keeps that version fixed and provides the agent identity, model access, connections, credentials, and computing resources needed to create its sandbox.
A task is one request to the runtime. Introspection creates a sandbox for each task. Each agent turn inside the task is a run.
After the task finishes, Introspection saves the messages, model calls, tool calls, errors, feedback, and result as a conversation. You can mark notable behavior in one conversation as an observation. Repeated observations form a pattern, and a judgement scores the behavior against rules stored in the Recipe.
Saved conversations help you test changes, but they never edit the agent. An evaluation, or eval, repeats useful cases against a proposed change. An experiment compares versions on live tasks when an eval does not give a clear answer. After you review a successful change, you add it to the Recipe and deploy a new version. A change can update instructions, skills, tools, evals, or checks for good results.
Where you work on the agent
You use four places while you develop and release an agent. Each place answers a different question before you send live work to the agent.
| Place | What you do there |
|---|---|
| Local Pi | Create the Recipe and test it on your computer before you deploy it. |
| Development runtime | Connect your application to Introspection while the agent still uses the files on your computer. Use it to test the same request flow that your deployed application will use. |
| Staging runtime | Test a deployed version and its staging settings before you merge the change or send production work to it. |
| Production runtime | Run approved work with the Recipe version that your team released, and save the results for later review. |
Start with Local Pi while you create the agent. Use development when you need to test your application with the files on your computer. Use staging for the deployed version you want to review, and use production after your team approves that version.
The Recipe defines the same behavior in every place. The services and credentials can differ between local development, staging, and production. Introspection stores those connections outside the Recipe and calls them bindings.
How versions and environments work
Each deployment creates a runtime version that cannot be edited. A runtime group keeps every version of the same agent under one stable name. Patterns can collect results across the group, and experiments can compare its versions.
An environment lane sets the runtime version that receives new tasks for an environment such as staging or production. Moving a lane sends new tasks to a different version without changing either version.
For example, suppose the refund-exception-agent runtime group contains three
versions. Your team can test version 3 in staging while production continues to
use version 2.
| Place | What it uses |
|---|---|
| Development | The Recipe files on your computer |
| Staging | Runtime version 3 |
| Production | Runtime version 2 |
Development works differently because it uses the Recipe on your computer.
Development does not point an environment lane to a deployed version.
introspection dev connects development tasks
from Introspection to your local files.
Bindings provide allowed service addresses, variables, and credentials when Introspection creates the sandbox. You can set a binding for a whole project, one runtime group, one version, or one environment. The agent can use a stored credential, but it cannot read the credential value.
Deployment can mean releasing a runtime version to an environment. It can also mean choosing where the Introspection system that runs tasks is hosted. See Deployment and security for hosted, dedicated, and self hosted options.
What happens when a task runs
- Introspection selects the runtime version assigned to the requested environment. The task keeps that version until it ends.
- Introspection creates one sandbox and loads the saved Recipe. It also adds the agent identity, model access, files, memory, and bindings that the task can use.
- Pi runs the selected agent with its allowed tools. A task can contain several runs, and each run uses the same sandbox.
- Introspection saves the conversation and the events used for monitoring and review.
- Introspection deletes the sandbox when the task finishes or reaches its time limit. Saved files, memory, conversations, observations, and judgements remain available.
Closing an application or losing its connection does not always stop the task. A completed status means that the task stopped, but it does not prove that the agent produced a useful result. When an application reconnects, it should resume the same task instead of creating a new one.
See Tasks and runs for the task lifecycle. See Task operations for statuses, interruptions, cancellation, reconnection, and error diagnosis.
Learn more
- Quickstart shows how to build, deploy, and test your first agent.
- Recipes explains how to change the files that define an agent.
- Runtimes explains how to manage deployed versions and environments.
- Glossary defines the terms used in the documentation.