Sessions

Sessions own the agent spec (system prompt, model, tool defs) and the full message history. Each send is a run scoped to the session.

const session = await client.createSession({
  systemPrompt: "You are a friendly REPL.",
  tools: [
    defineLocalTool({
      name: "today",
      description: "Get today's date as ISO 8601.",
      parameters: z.object({}),
      execute: () => new Date().toISOString().slice(0, 10),
    }),
  ],
});

const r1 = await session.send("What day is it?");
console.log(r1.text);

const r2 = await session.send("And what about tomorrow?");
console.log(r2.text);

await session.end();

Messages & file attachments

Runs and session turns accept either a prompt or a multi-role messages array. File inputs attach to the last user message. See Messages & file attachments for helpers and examples.

Resuming a session

A session lives on the server. Resuming from a different process re-binds your local tool handlers — pass them via resumeSession:

const session = await client.resumeSession(sessionId, {
  tools: [
    defineLocalTool({
      name: "today",
      parameters: z.object({}),
      execute: () => new Date().toISOString().slice(0, 10),
    }),
  ],
});

Local tool handlers are not persisted: the session stores definitions (name, schema, description) so that a restarted SDK can re-bind handlers and keep going. If you don’t pass tools to resumeSession, the session uses whatever it had at create time — which means subsequent send calls will fail to dispatch local tools because there are no handlers in this process.

Session metadata

Anything you pass as metadata at session creation is inherited by every run created via session.send. See Metadata for the validation rules and the per-message override pattern.

const session = await client.createSession({
  systemPrompt: "...",
  metadata: { customer: "acme", env: "prod" },
});

await session.send("trace this turn", {
  metadata: { trace_id: "trace_abc" }, // run-level keys win
});

Run guards (loop detection & tool budgets)

Loop detection and toolBudgets follow the same inheritance pattern: pass loopDetection / toolBudgets at session creation to set the session-default applied to every subsequent session.send, and override them per-message when a single turn needs different settings. Per-message overrides apply to that one run only and do not mutate the session’s stored value.

const session = await client.createSession({
  systemPrompt: "...",
  loopDetection: { consecutiveThreshold: 2, hardCutoffThreshold: 4 },
  toolBudgets:   { recall: { maxCalls: 8 } },
});

await session.send("deep-dive on this customer", {
  loopDetection: false,                    // disable loop detection for this turn
  toolBudgets:   {},                       // clear runtime defaults for this turn
});

Persisted-agent sessions

Pass agentId to create a session backed by a persisted MANTYX agent — see Persisted agents for the full semantics.

const session = await client.createSession({
  agentId: "agent_cm6abc123",
});
const r = await session.send("Summarise yesterday's tickets.");