Skip to Content
Platform
Getting startedQuickstart

Build and deploy your first agent

Describe the agent you need, run its recipe locally with Pi, and deploy that behavior to an Introspection runtime.

An agent is described by a recipe — the open format for vertical agents, built on Pi.

Prerequisites

  • Node.js 24+ 
  • A coding agent such as Codex or Claude Code. It installs the introspection CLI (@introspection-ai/cli) when needed and uses it in step 3.

You do not need an Introspection project or cloud credentials until step 4.

1. Describe the agent

Open the repository where the recipe should live, then give your coding agent the goal. Include the machine entrypoint so it can prepare everything itself:

First read https://docs.introspection.dev/agents.md and follow it.
Then use Introspection to complete this request: <describe the agent you need>.

The agent prepares the CLI and local toolchain itself. The user does not run setup.

Create a new agent

Use this prompt when you have an outcome but no existing agent:

Use introspection to build an agent that
<describe who uses the agent and what it should accomplish>

If you want to start from a recipe template , include its path or URL. If you want the coding agent to compare templates, describe the outcome and the capabilities the agent needs.

2. Build the recipe

The create or migrate workflow first reads the repository and works out the agent’s contract with you:

  1. Define the job. Who invokes the agent, what result it promises, which sources it may trust, what it may change, and when it must stop or ask for help.
  2. Choose representative cases. Agree on normal work, ambiguity, missing access, partial failure, and at least one request the agent should decline.
  3. Approve the plan. The coding agent explains whether it will start from scratch, use a template, or preserve an existing implementation. It does not edit the repository before you confirm that direction.
  4. Create the smallest useful recipe. The workflow writes a portable Pi package at a repository-local path such as apps/support-agent, plus a Runtime manifest at .introspection/<runtime-slug>.yaml naming that path. The manifest’s filename stem is the runtime slug you pass in step 3 and deploy in step 4. It adds instructions, skills, tools, or code only when the agreed cases require them.
  5. Try it locally. It checks the package and runs the agreed cases in fresh Pi sessions so you can review how the agent behaves.

The workflow prepares Pi and Recipes when it reaches a step that needs the local toolchain. It resolves model-provider configuration and authentication only when an approved test actually needs them.

3. Run it locally with Pi

Run the returned recipe from the repository root:

introspection local --runtime support-agent

--runtime names a Runtime manifest in .introspection/, so support-agent here resolves .introspection/support-agent.yaml. If the command reports that no local Runtime manifests were found, that file is missing — ask your coding agent to add it before continuing.

Try the ordinary case you care about, an important edge case, and a request the agent should not handle. If its behavior is not useful or repeatable, ask your coding agent to revise the recipe and run those cases again before deploying.

4. Deploy it to a runtime

Once the recipe behaves correctly in Pi, choose either path:

  • Ask your coding agent. Tell it to deploy the recipe to Introspection. It will inspect the repository and existing runtime state, explain what it is about to change, and then carry out the deployment — asking a deploy request is itself the approval for the work that request implies, including committing and pushing, creating the runtime version, and configuring staging. It pauses for decisions the request did not settle, such as creating a new GitHub repository or merging to production, and it verifies the deployed agent after it runs.
  • Use the Introspection app. Open your project, go to Runtimes, select New runtime, choose the GitHub repository containing the recipe, and follow the setup steps. After the runtime is created, run a representative task to confirm the deployed agent behaves like the local version.

The first runtime version becomes active in both staging and production, so create it only from a reviewed main commit. If the recipe is on a feature branch, merge its pull request first, update local main, then create the runtime. There is no staging-only first bootstrap.

What to do next

Last updated on