# Build Your First Agent

From signup to a running agent execution in about five minutes — driven entirely from your coding agent.

## Navigation

**Getting Started:** [Get Started](/index.md) | [How Sapiom Works](/how-it-works.md)  
**Capabilities:** [Overview](/capabilities.md) | [Verify Users](/capabilities/verify.md) | [Search the Web](/capabilities/search.md) | [AI Model Access](/capabilities/ai-models.md) | [Generate Images](/capabilities/images.md) | [Audio Services](/capabilities/audio.md) | [Browser Automation](/capabilities/browser.md)  
**Direct Access:** [Remote MCP — direct tool calls](/integration/mcp-servers/remote.md) | [SDK & API](/integration/sdk.md)  
**Direct Access / Agent Frameworks:** [Overview](/integration/agent-frameworks.md) | [LangChain](/integration/agent-frameworks/langchain.md) | [LangChain Classic](/integration/agent-frameworks/langchain-classic.md)  
**Direct Access / HTTP Clients:** [Overview](/integration/http-clients.md) | [Axios](/integration/http-clients/axios.md) | [Fetch](/integration/http-clients/fetch.md) | [Node.js HTTP](/integration/http-clients/node-http.md)  
**Governance:** [Overview](/governance.md) | [Setting Up Rules](/governance/rules.md) | [Agents & Identity](/governance/agents.md) | [Activity](/governance/activity.md)  
**Reference:** [For AI Tools](/for-agents.md)  
**Reference / API Reference:** [Introduction](/api-reference/introduction.md)  
**Reference / API Reference / Endpoints:** [Agents Endpoints](/api-reference/endpoints/agents.md) | [Get agent by ID](/api-reference/endpoints/agents/v1-agents-by-id-get.md) | [Update agent](/api-reference/endpoints/agents/v1-agents-by-id-patch.md) | [List all agents](/api-reference/endpoints/agents/v1-agents-get.md) | [Create a new agent](/api-reference/endpoints/agents/v1-agents-post.md) | [API Endpoints](/api-reference/endpoints.md) | [Get Sapiom payment JWKS](/api-reference/endpoints/other/.well-known-sapiom-jwks.json-get.md) | [Analytics Endpoints](/api-reference/endpoints/other.md) | [Get analytics chart](/api-reference/endpoints/other/v1-analytics-chart-get.md) | [Get analytics leaderboards](/api-reference/endpoints/other/v1-analytics-leaderboards-get.md) | [Get analytics summary](/api-reference/endpoints/other/v1-analytics-summary-get.md) | [Rules Endpoints](/api-reference/endpoints/rules.md) | [Get rule by ID](/api-reference/endpoints/rules/v1-spending-rules-by-id-get.md) | [Update a rule](/api-reference/endpoints/rules/v1-spending-rules-by-ruleId-put.md) | [List all rules](/api-reference/endpoints/rules/v1-spending-rules-get.md) | [Create a new rule](/api-reference/endpoints/rules/v1-spending-rules-post.md) | [Transactions Endpoints](/api-reference/endpoints/transactions.md) | [Complete a transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-complete-post.md) | [List transaction costs](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-get.md) | [Add cost to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-post.md) | [Add facts to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-facts-post.md) | [Get transaction details](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-get.md) | [Reauthorize a transaction with x402 payment data](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-reauthorize-post.md) | [List transactions](/api-reference/endpoints/transactions/v1-transactions-get.md) | [Create a new transaction](/api-reference/endpoints/transactions/v1-transactions-post.md) | [Verification Endpoints](/api-reference/endpoints/verification.md) | [Check verification code](/api-reference/endpoints/verification/v1-services-verify-check-post.md) | [Send verification code](/api-reference/endpoints/verification/v1-services-verify-send-post.md)  
**Reference / SDK Reference:** [@sapiom/axios](/reference/sdk/axios.md) | [@sapiom/fetch](/reference/sdk/fetch.md) | [SDK Reference](/reference/sdk.md) | [@sapiom/langchain-classic](/reference/sdk/langchain-classic.md) | [@sapiom/langchain](/reference/sdk/langchain.md) | [@sapiom/node-http](/reference/sdk/node-http.md)  
**Reference:** [Concepts](/reference/concepts.md)

---

An **agent** (orchestration) is a small TypeScript project you author with your coding agent: `defineAgent({ entry, steps })`, where each step's `run(input, ctx)` does work and can call any paid Sapiom capability on `ctx.sapiom`. You write it as code, test it locally for free, then deploy it to run on Sapiom's cloud.

This guide goes from nothing to an agent running in the cloud — all from your terminal or IDE, no dashboard required.

> **Written for your coding agent:** You drive this from an AI coding agent (Claude Code, Cursor, …). The Sapiom MCP gives your agent the tools to scaffold, test, and deploy an agent, and this page is written so your agent can follow it end to end.

1. ## Add the Sapiom MCP

   Add the **`@sapiom/mcp`** server to your coding agent's MCP config:

   ```jsonc
   {
     "mcpServers": {
       "sapiom": { "command": "npx", "args": ["-y", "@sapiom/mcp"] }
     }
   }
   ```

   In Claude Code you can also add it from the terminal:

   ```bash
   claude mcp add sapiom -- npx -y @sapiom/mcp
   ```

   Restart your client so it loads the Sapiom tools — `sapiom_authenticate`, `sapiom_status`, and the `sapiom_dev_agents_*` lifecycle.

2. ## Authenticate

   Run **`sapiom_authenticate`**. It opens a browser login — **sign up or log in, then approve**. That one step provisions and caches an API key for you (in `~/.sapiom/credentials.json`); there's nothing to copy or paste.

   Confirm with **`sapiom_status`**:

   ```text
   Authenticated as Your Organization (tenant: 37c9…)
   ```

   
> **Why this matters:** Authenticating this way makes your agent an **API-key principal**. Agents you create inherit that authority, which is what lets their steps call paid capabilities when they run. (Authoring against a bare login session instead leaves executions unable to spend.)
   

3. ## Scaffold a project

   Ask your agent to scaffold an agent, or call **`sapiom_dev_agents_scaffold`** with a target directory. (It also takes a `template`: `"default"` — the minimal starter used here — or `"coding-pause"` for the non-blocking coding-agent pattern; see the authoring guide.) It writes a ready-to-run TypeScript project:

   ```text
   my-agent/                    # git-initialized for you
   ├── index.ts                 # your agent
   ├── package.json
   ├── tsconfig.json
   ├── AGENTS.md                # authoring guide — your agent should read this first
   ├── CLAUDE.md                # points your coding agent at AGENTS.md
   ├── README.md
   ├── .gitignore
   └── .sapiom-dev/stubs.json   # capability stubs for run_local
   ```

   Install dependencies:

   ```bash
   npm install
   ```

   
> Open **`AGENTS.md`** first — it's the full authoring reference (step graph, the local test loop, capability stubs, pause/resume, determinism). Your agent should read it before writing step code. Scaffolded projects also ship the `sapiom-agent-authoring` skill at `.claude/skills/`, which auto-loads in Claude Code.
   

4. ## Write a step

   Your scaffold's `index.ts` is already a runnable two-step starter (`start → finish`). Open it and edit: a step is `defineStep({ name, next, run })`, its `run(input, ctx)` is ordinary code, and every Sapiom capability is on `ctx.sapiom` — pre-authed and tenant-scoped. Here's the shape of a step that calls a capability:

   ```typescript
   import { defineAgent, defineStep, terminate } from "@sapiom/agent";

   const main = defineStep({
     name: "main",
     next: [],
     terminal: true,
     async run(input, ctx) {
       ctx.logger.info("starting", { input });
       // Capabilities live on ctx.sapiom — e.g. sandboxes, repositories, the coding agent, file storage.
       const sandbox = await ctx.sapiom.sandboxes.create({ name: "demo" });
       ctx.logger.info("created sandbox", { sandbox });
       return terminate({ done: true });
     },
   });

   export const agent = defineAgent({
     name: "my-agent",
     entry: "main",
     steps: { main },
   });
   ```

   
> **The types are the source of truth:** What's available on `ctx.sapiom` is defined by `@sapiom/tools`. Use your editor's autocomplete and `npm run typecheck` rather than guessing — a wrong capability or method name fails the type check. See [Capabilities](/capabilities.md) for the full catalog.
   

5. ## Test locally — free

   Validate the step graph, then run the whole agent on your machine with every capability **stubbed** — no cloud calls, no cost:

   - **`npm run typecheck`** — confirms the code compiles and every `ctx.sapiom.*` capability/method you used actually exists.
   - **`sapiom_dev_agents_check`** — bundles `index.ts` and validates the step graph. Offline and instant.
   - **`sapiom_dev_agents_run_local`** — runs your real step code against stub capabilities and returns a per-step trace:

   ```json
   {
     "outcome": "completed",
     "steps": [
       { "step": "main", "status": "succeeded", "output": { "done": true } }
     ]
   }
   ```

   
> `run_local` needs no stubs to start — capabilities return sensible defaults, so a fresh agent runs end to end with zero setup. Add overrides in `.sapiom-dev/stubs.json` only when a step branches on a specific result.
   

6. ## Deploy and run

   When local runs look right, ship it:

   - **`sapiom_dev_agents_link`** — registers the agent under your tenant.
   - **`sapiom_dev_agents_deploy`** — builds and deploys it to the cloud.
   - **`sapiom_dev_agents_run`** — starts a real execution.
   - **`sapiom_dev_agents_inspect`** — watch status, steps, and spend.

   This is a real cloud execution, so it bills your tenant for the capabilities the agent actually uses.

## What you just did

You authored an agent as code, tested it for free, and ran it in the cloud — entirely from your coding agent, with no setup beyond installing the MCP. From here:

- [Browse capabilities](/capabilities.md) - Everything your steps can call on ctx.sapiom — scraping, compute, data, search, AI, media, and more.

Next in this track: a deeper **authoring guide** (the same material your scaffold's `AGENTS.md` covers — failure handling, pause/resume for long-running steps, sub-agents) and **operating** your agents (watching executions, spend, and failures across your fleet).

> **Heads up:** The authoring MCP currently targets **production**. A first-class staging/local target is in progress.