# Build Your First Workflow

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

## Navigation

**Getting Started:** [All You Need](/index.md) | [Getting Started](/introduction.md) | [How Sapiom Works](/how-it-works.md) | [Quick Start](/quick-start.md) | [Using Services](/using-services.md) | [For AI Tools](/for-agents.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)  
**Integration / Agent Frameworks:** [Overview](/integration/agent-frameworks.md) | [LangChain](/integration/agent-frameworks/langchain.md) | [LangChain Classic](/integration/agent-frameworks/langchain-classic.md)  
**Integration / 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 / 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)

---

A **workflow** (orchestration) is a small TypeScript project you author with your coding agent: `defineOrchestration({ 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 a workflow 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 a workflow, 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_orchestrations_*` 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**. Workflows 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 runs unable to spend.)
   

3. ## Scaffold a project

   Ask your agent to scaffold a workflow, or call **`sapiom_dev_orchestrations_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-workflow/                 # git-initialized for you
   ├── index.ts                 # your orchestration
   ├── 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.
   

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 { defineOrchestration, defineStep, terminate } from "@sapiom/orchestration";

   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 orchestration = defineOrchestration({
     name: "my-workflow",
     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 workflow 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_orchestrations_check`** — bundles `index.ts` and validates the step graph. Offline and instant.
   - **`sapiom_dev_orchestrations_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 workflow 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_orchestrations_link`** — registers the workflow under your tenant.
   - **`sapiom_dev_orchestrations_deploy`** — builds and deploys it to the cloud.
   - **`sapiom_dev_orchestrations_run`** — starts a real execution.
   - **`sapiom_dev_orchestrations_inspect`** — watch status, steps, and spend.

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

## What you just did

You authored a workflow 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-workflows) and **operating** your workflows (watching runs, spend, and failures across your fleet).

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