Work with agent projects

Treat Sapiom MCP as a project interface for your coding agent, not as a command vocabulary you must memorize. State the result you want, include the intended project directory and test input when they matter, and ask for the evidence you need. Claude Code or Codex can choose and sequence the exact tools.

Before any workflow, connect and authenticate Sapiom MCP. Start the coding agent in the intended project directory so defaults cannot silently target a sibling checkout.

Create and locally run your first agent

In an empty directory, ask:

Create the default Sapiom starter here, keep it unchanged, get it ready to run, and run it locally with the input { "name": "Ada" }. Show me the checked agent name, entry step, step count, graph warnings, terminal outcome, each step result, unused stubs, and stub warnings.

The coding agent can scaffold, confirm whether the best-effort dependency install succeeded, repair setup if needed, check the project, and run it locally. You do not need to invoke setup commands or raw MCP tools yourself.

A correct default starter has entry start, two steps, no graph warnings, and this stable run evidence:

{
  "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": []
}

The full first-agent walkthrough explains what each field proves. This local workflow creates no hosted agent, deployment, production run, or capability spend.

Create from existing source

Use one source identity, not several:

A gallery templateId creates and clones a fork you own.
A forkId re-clones that existing fork.
A deployed agent definitionId clones its current build-repository source and pre-links the checkout.

For a gallery project, ask:

Create a local project in ./research-agent from the gallery template web-research-digest. Read its AGENTS.md and README.md, get its dependencies ready, check it, and tell me whether the checkout is linked or still source-only.

Template and fork clones remain source-only until link and deploy. A definition clone writes its hosted identity into sapiom.json, so it does not need a separate link before its next deploy. See Create from a template for destination and credential boundaries.

Change, check, and test an agent

Ask for the code change and its evidence together:

Add an approval branch to this agent. Preserve its existing input contract, check the full project, then locally run both approval outcomes with deliberate stubs. Show me every step attempt and require unusedStubs and stubWarnings to be empty.

The coding agent should use the project’s installed types and local instructions, then run the full Sapiom check. A rendered graph alone is not proof that TypeScript, bundling, import, manifest derivation, and graph validation passed.

Use Test locally for exact stub precedence, dispatched pauses, retries, and trace interpretation.

Link and deploy

When local evidence is clean, ask:

Link this checked project to an agent with the definition’s own name, creating it only if it does not exist. Deploy the current working tree, wait for the build result, and give me the exact definition ID and build ID. Do not start a production run yet.

Link resolves hosted identity and stores it in sapiom.json. Deploy packages source reachable from the current working tree, including uncommitted edits, then creates a cloud build. It does not start the agent.

Preserve the returned buildRunId. If a client wait ends before the build settles, inspect that build instead of immediately creating a duplicate. See Deploy for Git prerequisites and immutable build behavior.

Run and inspect in production

Starting and observing are distinct jobs:

Start one production run of this linked agent with the input { "name": "Ada" }. Preserve the execution ID, then inspect it with the bounded wait until it completes, fails, or pauses for a signal. Show the final status and dashboard link.

The start receipt contains an executionId; it is not terminal agent output. Inspection is compact by default. When a step fails, ask:

Inspect execution <execution-id>. Find the failed step from the compact summary, then fetch that step’s input and error fields only. Use its effective input to reproduce the failure locally with deliberate stubs.

This keeps large logs and state out of the first response while preserving a deterministic debug loop. Inspect documents selectable fields, truncation budgets, and dashboard evidence.

Schedule production runs

Preview a cadence before creating it:

For deployed agent daily-brief, preview the next five occurrences of 0 9 * * 1-5 in America/New_York. If they match weekday mornings, create that recurring schedule with the input { "audience": "operations" }, then inspect the saved schedule and show its next fire time.

The coding agent can use sapiom_dev_agents_cron_preview, sapiom_dev_agents_schedule, and sapiom_dev_agents_schedule_inspect. Preview creates nothing. A schedule is separate from a delayed child-agent dispatch and can start metered production runs.

To stop future fires, ask it to cancel the exact schedule ID with sapiom_dev_agents_schedule_cancel. Cancellation does not stop a run that already began. See Schedule for one-off triggers, bounds, jitter, and recent-fire inspection.

Resume a run with a signal

First inspect the paused execution and copy the declared signal identity. Then ask:

Deliver the signal named approval with correlation ID request-123 to execution <execution-id>, using payload { "approved": true }. Report the match count, then inspect the same execution until it settles.

sapiom_dev_agents_signal scopes ownership with the execution ID and matches the name plus correlation ID. It is not a generic resume control. Automatic capability callbacks resume their own waits without this manual tool. See Use signals for payload and duplicate-delivery behavior.

Released web-app preview tools

@sapiom/[email protected] advertises sapiom_dev_sandbox_configure, sapiom_dev_sandbox_check, and sapiom_dev_sandbox_preview. They configure and launch a temporary application resource rather than an agent.

Do not invoke this sequence as a supported public workflow. Its current hosted preview implementation provisions capability infrastructure directly, outside a Sapiom-managed production agent run. The tools remain in the exact reference so an approval prompt or older client can be identified, but the documentation does not carve out an unapproved direct-capability exception. A corrected product release must align or remove the sequence before this manual can teach it.

Send feedback

When you explicitly want to report a product issue, ask the coding agent to draft the wording first:

Draft one short feedback message saying that the deploy error should identify the failing build stage. Show me the exact message and wait for my confirmation before sending it to Sapiom.

After confirmation, sapiom_send_feedback sends plain-language message and optional context. Never include files, code, logs, stack traces, environment variables, keys, tokens, or other secrets. The fields also contribute to Sapiom’s tool-call analytics.

Evidence to preserve

Boundary	Keep
Check	Agent name, entry, step count, warnings, and the first concrete error when invalid.
Local Run	Outcome, every step attempt, `unusedStubs`, and `stubWarnings`.
Link	`definitionId` and the exact project whose `sapiom.json` was updated.
Deploy	`buildRunId` and terminal build status.
Production run	`executionId`, pinned build identity, final status or pause identity, and `webappUrl`.
Schedule	`scheduleId`, status, next fire, and execution IDs from recent fires.

Exact tool reference Inspect every released input schema, side effect, return contract, and expected failure.

Troubleshoot Sapiom MCP Start from connection, project, validation, deployment, or result-envelope evidence.