Build your first agent

Build the same hello-sapiom starter in Agent Studio, Claude Code, or Codex. You will create the project, install its dependencies, validate it, and run both steps locally before signing in to Sapiom.

Start locally

No Sapiom account is required for this guide. Scaffolding and package installation use npm, but Local Run replaces Sapiom capability calls with stubs and creates no Sapiom capability spend. User-authored code remains ordinary local code and can have its own filesystem or network effects.

What the starter does

The default starter declares two steps:

start → finish

start accepts a name and passes a greeting to finish. finish completes the run with { "done": true }. Keep the starter unchanged so your result matches the verified output below.

1. Create hello-sapiom

   Agent Studio

   Open Browse templates from the welcome screen, or choose Add Workspace → Start from a template. Under Bundled starters, open Default starter, choose Use template, and select an empty destination named hello-sapiom.

   Choose Claude Code or Codex from the Coding agent menu, then select Start session. Studio asks that coding agent to create the shipped starter and install its dependencies. Wait for the session to report that both tasks completed.

   Your coding agent

   First connect Sapiom MCP to Claude Code or Codex. Create an empty hello-sapiom directory, start your coding agent there, and ask:

   Create the default Sapiom starter in this directory. Keep the shipped starter unchanged, install its dependencies, and read its AGENTS.md before continuing.

   Your coding agent chooses the project tools and supplies the absolute directory internally; you do not need to invoke a raw MCP tool or construct its JSON payload yourself.

   A successful scaffold reports the destination, the default template, the hello-sapiom project name, and whether Git initialization succeeded. Git setup is best-effort, so gitInitialized can be false when Git is unavailable.

2. Inspect the generated project

   Both paths produce the same authoring files:

   hello-sapiom/
   ├── index.ts
   ├── package.json
   ├── tsconfig.json
   ├── sapiom.json
   ├── AGENTS.md
   ├── CLAUDE.md
   ├── README.md
   ├── .gitignore
   ├── .sapiom-dev/stubs.json
   └── .claude/skills/sapiom-agent-authoring/SKILL.md

   Agent projects currently use TypeScript. sapiom.json marks this folder as an agent project and starts without a cloud credential. .sapiom-dev/stubs.json contains the committed local capability responses. Agent Studio separately owns an ignored .sapiom/ directory for session context and Canvas output.

   The scaffold is npm-install-ready but does not install dependencies itself. If your coding-agent session did not already complete installation, run:

   npm install

3. Run the TypeScript check

   From hello-sapiom, run:

   npm run typecheck

   A successful command exits without TypeScript errors. This checks the generated source against the installed agent and capability packages.

4. Check the agent

   In Agent Studio, enter this in the coding-agent session. Use the same request in standalone Claude Code or Codex:

   Check this Sapiom agent and summarize its entry step, step count, and any warnings.

   The successful starter has entry start, two steps, and no warnings. The complete tool response also contains build-specific artifact hashes; you do not need to compare those values.

5. Run both steps locally

   In Agent Studio or your standalone coding agent, ask:

   Run this agent locally with the input { "name": "Ada" } and show me the result of each step.

   The verified result, with only the run-specific execution ID omitted, is:

   {
     "outcome": "completed",
     "output": { "done": true },
     "steps": [
       {
         "step": "start",
         "status": "succeeded",
         "output": { "greeting": "hello from Sapiom, Ada" }
       },
       {
         "step": "finish",
         "status": "succeeded",
         "output": { "done": true }
       }
     ],
     "unusedStubs": [],
     "stubWarnings": []
   }

   completed proves the local runner reached a terminal directive. The two succeeded traces prove both real step bodies ran. Empty stub lists mean no supplied local response was ignored or malformed.

What you have now

You have a typed, checked agent project and a genuine local execution. You have not linked it to Sapiom Cloud, deployed it, or called a paid capability.

Create from a template Compare the live gallery with bundled starters and materialize either one safely.

Test locally Control stubs, cover branches, and interpret the per-step evidence.

Understand agents and projects Learn how the source folder, step graph, hosted identity, and runs relate.

Deploy your agent Sign in to Sapiom, create a cloud build, and start a production run.