AI Model Access

AI Model Access lets a deployed agent run a server-side model loop and receive its final text result. Agent steps call the typed ctx.sapiom.models capability; Sapiom supplies the authenticated cloud connection when the deployed agent runs.

Model availability and routing labels are runtime contracts. Do not rely on a fixed count, a copied provider list, or raw provider model identifiers.

Choose the model call surface

What the agent needs	Recommended operation
A model loop that returns final text in the current step	`models.run(...)`
A model loop that should resume another step when it finishes	`models.launch(...)` plus `pauseUntilSignal(...)`
One prompt-and-response without a model loop	`llm.run(...)`
A coding task with a sandbox and optional repository	`models.coding.run(...)` or `.launch(...)`
An already-deployed Sapiom agent	`agents.run(...)` or `.launch(...)`

See Choose a call surface before substituting one operation for another. These surfaces return different result shapes and have different execution lifecycles.

Run a model loop inline

Omit model to let the platform use its normal route:

const run = await ctx.sapiom.models.run({
  prompt: `Turn these notes into a concise customer update:\n\n${input.notes}`,
  system: "State only facts supported by the supplied notes.",
  maxTokens: 800,
});

if (
  run.status !== "completed" ||
  !run.result?.success ||
  run.output === null
) {
  throw new Error(run.error?.message ?? `Model run ${run.status}`);
}

return {
  text: run.output,
  runId: run.runId,
  turns: run.result.turns,
  warnings: run.result.warnings ?? [],
};

models.run waits for a terminal result. The result contains status, nullable output, nullable execution details, and a nullable error. A completed transport lifecycle is not enough by itself; also check result.success before using the output.

Omit model unless the agent has a concrete routing requirement. If you supply a label the platform does not recognize, the run can fall back to the platform route and report that in result.warnings.

Dispatch longer work

models.launch returns a handle with a runId, status(), wait(), and the signal metadata required by pauseUntilSignal. Use the dispatch pattern when the workflow should suspend instead of holding the launching step open:

const handle = await ctx.sapiom.models.launch({
  prompt: input.researchBrief,
});

return pauseUntilSignal(handle, { resumeStep: "use-model-result" });

Declare the matching static pause edge on the launching step. The resumed step receives a plain model-run result, not the live handle. See Use signals.

Test the behavior locally

Local Run replaces ctx.sapiom.models.run and .launch with deterministic results. It does not invoke a model. Override models.run when the step parses or branches on particular output:

{
  "version": 1,
  "steps": {
    "draft-update": {
      "models.run": {
        "runId": "model-local",
        "status": "completed",
        "output": "The fixture customer update.",
        "result": {
          "success": true,
          "stopReason": "end_turn",
          "turns": 1,
          "modelUsed": "stub-model",
          "durationMs": 1,
          "costUsd": 0,
          "usage": {
            "inputTokens": 0,
            "outputTokens": 0,
            "cacheReadTokens": 0,
            "cacheCreateTokens": 0,
            "thinkingTokens": 0
          }
        },
        "error": null
      }
    }
  }
}

Use a separate fixture for the failed branch. After each run, assert the terminal output and require both unusedStubs and stubWarnings to be empty. Local success proves only the agent’s handling of that fixture; it does not prove prompt quality, model availability, routing, latency, or live usage.

Manage runtime usage

Each run can take multiple turns. Limit the context and requested output to what the task needs, avoid retrying the same failed request without changing the conditions, and inspect usage, warnings, and the run record when behavior differs from expectations.

Use the signed-in capability catalog for current model availability, limits, and pricing rather than copying a provider inventory or rate into the agent.

Choose a call surface Compare model loops, LLM calls, coding runs, and deployed agents.

Use signals Suspend a workflow on a dispatched model run.

Test locally Exercise output and failure branches with exact model fixtures.

Inspect a run Review status, output, logs, and execution details.