Add an agent to your app

Your application keeps its authentication, business data, and user interface. Checkfu supplies the Agent, Environment admission, durable Session log, governed actions, and execution lanes. Before this guide, create or select:

a Workspace-bound API key held only by your backend;
an Agent; creating one also creates immutable AgentVersion 1;
an Environment that defines execution authority; and
model access for the model selected by the Agent.

Add tools, skills, Files, Memory, and Connections to the Agent or Session only when the corresponding capability is available. They are not required to prove the basic integration.

The Checkfu CLI and TypeScript SDK are private-alpha artifacts with no self-service public installation channel. Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it. Confirm capability status before making availability part of your application’s contract.

Create the server-side client

import { Checkfu } from "@checkfu/sdk"

const checkfu = new Checkfu({
  apiKey: process.env.CHECKFU_API_KEY!,
})

Never expose this client or its API key to the browser. An ordinary Workspace-bound key already selects its Workspace; do not add a Workspace selector header.

Create a Session

Create one Session when your application begins a durable agent interaction:

const session = await checkfu.sessions.create(
  {
    agent: { type: "agent", id: agentId },
    environment_id: environmentId,
    title: `${ticket.id}: ${ticket.subject}`,
  },
  { idempotencyKey: `support-session-${requestId}` },
)

The Agent is mutable, but this Session resolves and freezes one exact AgentVersion. It also freezes the admitted Environment authority. Updating the Agent or Environment affects later admissions, not work already inside this Session.

Send application context as user input

const inputEvent = await checkfu.sessions.events.send(
  session.id,
  {
    type: "user.message",
    payload: {
      content: `Ticket ${ticket.id}: ${ticket.subject}\n\n${prompt}`,
      caused_by: { kind: "api", request_id: requestId },
    },
  },
  { idempotencyKey: `support-message-${requestId}` },
)

Actor attribution comes from the authenticated request. Do not accept or insert a caller-supplied actor identifier into event bytes. Do not place provider keys, Connection credentials, or other secrets in the message. Checkfu keeps credential material out of model context, harness configuration, Session events, and the sandbox.

Read settlement from the event log

Request completion means the input was stored. It does not mean the turn finished. Resume after that stored event so the stream replays every later event without stopping on an earlier Session boundary:

const terminalSessionEvents = new Set([
  "session.status_completed",
  "session.status_failed",
  "session.status_canceled",
])

for await (const event of checkfu.sessions.events.stream(session.id, {
  lastEventId: inputEvent.seq,
})) {
  console.log(event.seq, event.type)

  if (
    terminalSessionEvents.has(event.type) ||
    (event.type === "session.status_idle" &&
      event.payload.stop_reason !== "requires_action")
  ) {
    break
  }
}

Runs, child Runs, subagents, approvals, checkpoints, recovery, and continuation remain part of this Session truth. A harness transcript or request duration is not an alternate authority. An idle boundary with requires_action is intermediate, so do not present the turn as complete until the admitted continuation settles. When a turn pauses for an ActionApproval, render the frozen action and send the human decision through your authorized backend. Follow Handle an approval; approval is a governance resource, not a chat event or browser-only confirmation.

Render the Session in your UI

Expose narrow, authenticated backend routes for the Session event page and SSE stream, then use Embed a Session view. Your backend must verify that the application user may observe the requested Session before attaching the Checkfu key upstream.

Add capabilities after the first turn

Tools and Connections

Add provider-neutral tools while keeping credentials out of the model and sandbox.

Files, Memory, and Skills

Add retained context through explicit resources and immutable versions.

Automations and triggers

Start fresh Session work from schedules, webhooks, or subscriptions.

Your own messaging app

Map each conversation in your messaging app to a Session through the API.

Computer

Use provider-neutral Computer authority and durable Screen observation only where support evidence permits.

Usage and Budgets

Attribute authoritative Usage before enforcing or presenting a Budget.

Retention, audit, and recovery

Choose standard or ZDR semantics and inspect governance and audit truth.

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Add an agent to your app

Create the server-side client

Create a Session

Send application context as user input

Read settlement from the event log

Render the Session in your UI

Add capabilities after the first turn

Tools and Connections

Files, Memory, and Skills

Automations and triggers

Your own messaging app

Computer

Usage and Budgets

Retention, audit, and recovery

​Create the server-side client

​Create a Session

​Send application context as user input

​Read settlement from the event log

​Render the Session in your UI

​Add capabilities after the first turn

Tools and Connections

Files, Memory, and Skills

Automations and triggers

Your own messaging app

Computer

Usage and Budgets

Retention, audit, and recovery

Create the server-side client

Create a Session

Send application context as user input

Read settlement from the event log

Render the Session in your UI

Add capabilities after the first turn