Build and deploy your first agent

The guide builds a refund exception agent for a customer operations team. The agent reads a refund policy and an order record. It drafts a response when the policy is clear, and it asks a person to review cases that need judgment. The agent never issues a refund itself.

You will use a coding agent such as Codex or Claude Code to create the files and instructions that define the agent. Introspection calls this set of files a Recipe.

What you will achieve

By the end of the guide, you will have:

• A refund exception agent that runs on your computer.
• Results from several example orders, including cases that need human review.
• A deployed version of the agent and the saved result of its first task.

You can create and test the agent without an Introspection account. You will sign in before you deploy it.

1. Define the agent

Open the repository in your coding agent and send this request:

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.

Wait for the coding agent to finish setup. Then send this request:

Use Introspection to build a refund exception agent for a customer-operations
specialist. It must read the current refund policy and an order record, then
either draft an evidence-backed response or escalate the case.

It must never issue a refund. Escalate missing orders, conflicting records,
fraud signals, chargebacks, high-value exceptions, and policy ambiguity.

Prove these cases locally:
1. An eligible order receives a grounded approval draft.
2. A missing order ID produces one focused request for information.
3. A final-sale or out-of-window order is declined without promising a refund.
4. A fraud or high-value exception is escalated with the relevant evidence.
5. An unrelated request is declined or routed elsewhere.

The coding agent first explains what it plans to create. Review the plan and approve it before the coding agent edits the repository. When the work is finished, the repository contains the agent files and a file named .introspection/refund-exception-agent.yaml. Introspection uses that file to find the agent when you run the commands below.

2. Test it locally

From the repository root, run the first example order. The command starts a new local session for the agent:

introspection local \
  --runtime refund-exception-agent \
  --print "Order 1842 arrived yesterday. The customer says it is unopened and wants a refund. Review the policy and draft the next response."

A successful result begins with a decision such as Decision: approve. The result should cite the refund policy and draft the next response. It should not claim that a refund was issued.

If you want to test more behavior, try the same command with any of these requests. Replace the text after --print with the request you want to try:

• The customer did not provide an order ID. Ask for the information you need.
• The order is marked final sale. Review the policy and draft the response.
• The order has a fraud warning. Review the evidence and decide what should happen next.
• The customer wants to change a delivery address. Decide whether this agent should handle the request.

For any case you try, compare the result with the expected behavior. The agent should ask for the missing order ID in the first case and decline the final sale request in the second case. It should send the fraud case to a person for review, and it should refuse or redirect the unrelated delivery request. None of the results should claim that a refund was issued.

If the command cannot call the selected model, check that you have signed in to the model provider in the Pi provider guide . If Introspection cannot find the agent, run introspection check and see Local development troubleshooting.

3. Create your account and project

1. Sign in at app.introspection.dev .
2. Create an organization if the app asks you to create one.
3. Create a project for the refund exception agent.
4. Run introspection login and approve the device flow in your browser.

The project will contain the deployed agent and the results you inspect later in this guide.

4. Deploy the reviewed recipe

Review the files that the coding agent created. Commit the files, push the commit, and merge the change into the repository’s default branch. Then send this request to your coding agent:

Deploy the refund exception agent to Introspection and verify the deployed
behavior with the same representative case. Stop for any decision that is not
already settled by this request.

The coding agent checks the repository and shows you its deployment plan. It then creates a deployed version from the commit you reviewed.

5. Run and verify the deployed agent

Run one small test against the deployed agent:

introspection tasks create \
  --runtime refund-exception-agent \
  --environment production \
  --subject quickstart-reviewer \
  --prompt "Order 1842 arrived yesterday. The customer says it is unopened and wants a refund. Review the policy and draft the next response."

import { IntrospectionClient } from "@introspection-sdk/introspection-node";
 
const client = new IntrospectionClient();
const runner = await client.runtimes("refund-exception-agent").run({
  identity: { user_id: "quickstart-reviewer" },
});
const handle = await runner.tasks.start({
  prompt: "Order 1842 arrived yesterday. The customer says it is unopened and wants a refund. Review the policy and draft the next response.",
});
 
const taskId = handle.run.task_id;
console.log(taskId, handle.run.id);
await handle.text();

The SDK reads INTROSPECTION_TOKEN; use a production-scoped API key or service account token for this example. The CLI uses your member session and therefore names the production environment explicitly.

Save the returned task ID. Wait for the task to finish, then inspect the task and its exact conversation:

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

const task = await runner.tasks.get(taskId);
const conversationId = task.metadata?.conversation_id;
if (typeof conversationId !== "string") throw new Error("No conversation");
const conversation = await runner.conversations.exportJson(conversationId);
 
console.dir({ task, conversation }, { depth: null });

The task output includes metadata.conversation_id. Use that value for <conversation-id> so you inspect the conversation created by this task. The deployment is working when:

• The task uses the commit you deployed.
• status is completed with metadata.completion_reason = "task_completion".
• The conversation contains a draft or asks a person to review the case, based on the refund policy.
• The task contains no tool or model access error.

Next steps

• Develop and ship: change the recipe locally, verify a candidate in staging, and merge it to production.
• Integrate a full stack application: add customer identity, streaming, reconnect, files, and feedback.
• Learn from production: follow a real failure to the smallest change worth making.
• Recipes: understand and extend the package you just created.