Sessions

A session is one run of an agent toward a goal. You create it, follow its work, optionally answer its questions, and control its execution.

Creating a session

const session = await client.createSession({
  integrationId: "your_integration_id",
  goal: "Design a challenging game level",
  context: { projectId: "proj_1", sceneId: "scene_main" },
});

context is arbitrary structured data passed to the agent — use it to scope the run to a project, file, scene, or record.

Reconnecting

Sessions outlive a page refresh. Persist the session ID and reconnect later, then poll for status and new messages:

const session = await client.getSession(savedSessionId);
const info = await session.getInfo();
const { messages } = await session.getMessages({ limit: 50 });

Use client.getSessionInfo(sessionId) to read status and cost without creating a full Session object.

Controlling a running session

await session.pause("Need to review progress");
await session.resume({ newBudget: 5.0 });
await session.redirect("Focus on the boss arena instead");
await session.cancel("No longer needed");

Human input

When the agent needs a decision, its status becomes waiting_human. Respond by input ID with an approval, a choice, or free text:

// Approval
await session.respondToHumanInput(inputId, { approved: true });
// Selection from choices
await session.respondToHumanInput(inputId, { choiceId: "option_1" });
// Free text
await session.respondToHumanInput(inputId, { freeText: "Medieval theme" });

Note

The inputId will be delivered on the human_input_needed event once streaming is available. Until then, the response calls above work over REST, but surfacing a pending request’s inputId in real time relies on the upcoming stream.

Inspecting a session

const info = await session.getInfo();
console.log(info.status, info.cost);

const { messages } = await session.getMessages({ limit: 50 });

Next steps

• Streaming Events — the planned event reference.