Choose a call surface

Use ctx.sapiom to call a model or delegate work from a Sapiom agent step. The examples below go inside the step’s run(input, ctx) function.

For direct HTTP requests from your application, see the Router API reference.

Pick one

Your task	Method on ctx.sapiom
Summarize, extract, generate, or label with open-ended or multiple tags	llm.run
Answer yes/no, pick one of a fixed set, or place on a rubric, with probabilities	decisions.evaluate
Run an agent loop with tools	models.run
Write or edit files in a sandbox	models.coding.run
Run an agent you’ve already deployed	agents.run

One LLM request

llm.run returns an Anthropic Messages response. Use textOf to read its text. Leave model unset to use the platform default.

const reply = await ctx.sapiom.llm.run({
  request: {
    messages: [{ role: "user", content: "Summarize this review in one sentence: 'Setup took five minutes and support answered within the hour.'" }],
    max_tokens: 256,
  },
});

const text = ctx.sapiom.llm.textOf(reply);

For structured data, pass an output schema and read the result with structuredOf:

const reply = await ctx.sapiom.llm.run({
  request: {
    messages: [{ role: "user", content: "Extract the name and age from: 'Priya is 34.'" }],
    max_tokens: 256,
  },
  output: {
    name: "record_person",
    schema: {
      type: "object",
      properties: { name: { type: "string" }, age: { type: "number" } },
      required: ["name", "age"],
    },
  },
});

const person = ctx.sapiom.llm.structuredOf<{ name: string; age: number }>(reply);

A decision with a probability

When the answer is one of a set you can name up front, decisions.evaluate returns calibrated probabilities over those answers with no schema or reply parsing. Ask every independent question over the same state in one call.

const result = await ctx.sapiom.decisions.evaluate({
  state: { review: "This is fantastic!" },
  questions: {
    sentiment: {
      type: "choice",
      instructions: "What is the sentiment of `review`?",
      criteria: { positive: null, neutral: null, negative: null },
    },
  },
});

const sentiment = result.answers.sentiment.choice;
const confidence = result.answers.sentiment.confidence;

See Decisions for the noul and score question types and the HTTP request shape.

An agent loop with tools

models.run runs a multi-turn agent and waits for its result. Replace the MCP URL below with your own server that provides the tools needed for the task.

const result = await ctx.sapiom.models.run({
  prompt: "Look up the current weather in Lisbon, then summarize it in one sentence.",
  mcps: [{ url: "https://your-mcp-server.example/mcp" }],
});

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

For work that needs a filesystem and shell, use models.coding.run. See the coding agent example for launching a coding task and collecting its result.

A deployed agent

agents.run calls another Sapiom agent by its slug and waits for it to finish. Replace enrich-lead with a deployed agent’s slug and provide the input that agent expects.

const result = await ctx.sapiom.agents.run({
  definition: "enrich-lead",
  input: { domain: "acme.com" },
});

For long-running work, use models.launch, models.coding.launch, or agents.launch with pause and resume.

To review a call’s inputs and results, inspect the agent run.