Sessions

A session persists conversation history between an agent and its caller. Pass the same session id across runs and the runtime auto-loads prior messages, appends the new exchange, and forwards the transcript to the model.

Calling with a session id

await client.agents.run({ agentId: "support", input: "Hi", sessionId: "user-42" });
await client.agents.run({ agentId: "support", input: "follow-up", sessionId: "user-42" });

The two calls share history. The second call sees the first turn in the model's context window automatically — no manual history management required.

Sessions are agent-scoped: (agentId, sessionId) in TypeScript and (agent_id, session_id) in Python. Two agents with the same session id keep independent histories.

Storage

Embedded

Sessions live in memory by default. They survive within the process but are lost on restart.

import { agntz } from "@agntz/sdk";
import { sqliteStore } from "@agntz/sdk/sqlite";

const client = await agntz({
  agents: "./agents",
  store: sqliteStore("./agntz.db"),
});

The same store also backs runs and traces, so durability extends across the local SDK surface.

Hosted

Sessions are stored in Postgres and scoped to the authenticated user. They survive restarts, redeploys, and SDK reconnects. No configuration needed — pass any session id string you want.

Reading local session messages

const store = sqliteStore("./agntz.db");
const client = await agntz({ agents: "./agents", store });

const messages = await store.getMessages("user-42");

What's in a session

A session record holds:

• Messages — every user input and assistant output for this session.
• Reply events — intermediate messages emitted via the reply tool where supported.
• Last run reference — hosted storage can use the most recent run id for fast trace lookup from a session.

Sessions do not persist agent state such as {{stepId.property}}. State is per-run and discarded once the run ends; messages are the durable surface.

Patterns

• One session per user. Pass the user's stable id and let the runtime track every interaction.
• One session per topic. Mint ids such as user-42:billing so the same user can have multiple parallel conversations.
• Anonymous trials. Generate a session id client-side and pass it through until the user signs up; then re-key sessions to the new user id at signup time.