# Quickstart

Build an agent, prove it on your machine, deploy it, and read its first conversation.

This takes you from nothing to a deployed agent with one saved conversation.
Building and running locally needs no account; you sign in before you deploy.

**You need:** Node.js 24 or later, Git, and a GitHub repository for the agent.

## 1. Install

```bash
npm install -g @introspection-ai/cli
introspection setup                    # installs Pi and Recipes
```

## 2. Create and run a recipe

```bash
introspection init refund-agent
cd refund-agent
introspection local --print "Order 1842 arrived unopened. The customer wants a refund. Draft the next response."
```

`init` scaffolds a recipe and creates a Git repository. Run
`introspection local` with no flags to chat with the agent in Pi. If Pi cannot
reach a model, see the [Pi provider guide](https://pi.dev/docs/latest/providers).
To use another model, set `ai.model` in `agents/agent.yaml`
([Choose and change models](/patterns/models)).

## 3. Log in and connect GitHub

```bash
introspection login
```

Approve the request in your browser and choose a project. An organization
owner or admin connects the GitHub App once under the organization's
**Integrations** settings.

## 4. Push and create the runtime

```bash
git remote add origin git@github.com:<owner>/refund-agent.git
git push -u origin HEAD          # push to your default branch
introspection runtimes create
```

`runtimes create` finds the manifest `init` wrote under `.introspection/`.
Pass `--manifest .introspection/<slug>.yaml` only when the repository holds
several and the command lists them instead of choosing. Add `--yes` to skip
the confirmation in scripts.

The first `runtimes create` makes this commit live in both staging and production. See [Deploy your agent](/ship).

After this, each merge to the default branch builds a new version.

## 5. Run a task in staging

```bash
introspection tasks create \
  --runtime refund-agent \
  --environment staging \
  --prompt "Order 1842 arrived unopened. The customer wants a refund. Draft the next response."
```

Save the task ID from the output.

## Verify

```bash
introspection tasks get <task-id>
introspection conversations get <task-id>
```

Expect `status: idle` once the agent finishes its turn; the task stays open for
follow-up prompts. The conversation ID is the task ID.
`introspection open --task <task-id>` opens it in the dashboard.

Let a coding agent do this instead

Ask it:

```text
Use curl to read https://docs.introspection.dev/agents.md and follow the instructions to set up Introspection. Let's then work on creating a new agent recipe.
```

## Next

- [Run tasks from your backend](/patterns/add-to-your-app)
- [Test before production](/ship/staging)
- [Improve](/improve)

Quickstart

Build an agent, prove it on your machine, deploy it, and read its first conversation.

This takes you from nothing to a deployed agent with one saved conversation. Building and running locally needs no account; you sign in before you deploy.

You need: Node.js 24 or later, Git, and a GitHub repository for the agent.

1. Install


npm install -g @introspection-ai/cli
introspection setup                    # installs Pi and Recipes

2. Create and run a recipe


introspection init refund-agent
cd refund-agent
introspection local --print "Order 1842 arrived unopened. The customer wants a refund. Draft the next response."

init scaffolds a recipe and creates a Git repository. Run introspection local with no flags to chat with the agent in Pi. If Pi cannot reach a model, see the Pi provider guide . To use another model, set ai.model in agents/agent.yaml (Choose and change models).

3. Log in and connect GitHub


introspection login

Approve the request in your browser and choose a project. An organization owner or admin connects the GitHub App once under the organization’s Integrations settings.

4. Push and create the runtime


git remote add origin git@github.com:<owner>/refund-agent.git
git push -u origin HEAD          # push to your default branch
introspection runtimes create

runtimes create finds the manifest init wrote under .introspection/. Pass --manifest .introspection/<slug>.yaml only when the repository holds several and the command lists them instead of choosing. Add --yes to skip the confirmation in scripts.

The first runtimes create makes this commit live in both staging and production. See Deploy your agent.

After this, each merge to the default branch builds a new version.

5. Run a task in staging


introspection tasks create \
  --runtime refund-agent \
  --environment staging \
  --prompt "Order 1842 arrived unopened. The customer wants a refund. Draft the next response."

Save the task ID from the output.

Verify


introspection tasks get <task-id>
introspection conversations get <task-id>

Expect status: idle once the agent finishes its turn; the task stays open for follow-up prompts. The conversation ID is the task ID. introspection open --task <task-id> opens it in the dashboard.

Let a coding agent do this instead

Ask it:


Use curl to read https://docs.introspection.dev/agents.md and follow the instructions to set up Introspection. Let's then work on creating a new agent recipe.