TypeScript quickstart

You will run a tool on your laptop while Cereal runs the agent session. The result comes from a small bundled source collection, so you can inspect the evidence behind the answer.

Prerequisites

• Node.js 22+ and pnpm (the repository pins its pnpm version).
• Access to the Cereal repository. This starter uses its workspace SDK. If you do not have repository access, use the HTTP quickstart.
• A Cereal API key with read, data, and control in a development environment, created in the console's Settings → API keys.
• A key for a supported model provider you already use, and a model available to that account.

Get the starter

git clone https://github.com/trycereal/plane.git
cd cereal
pnpm install
pnpm --filter @trycereal/sdk build
cd examples/research-agent
cp .env.example .env

Set CEREAL_API_KEY, AI_GATEWAY_API_KEY, and RESEARCH_MODEL in .env. The sample uses Vercel AI Gateway and anthropic/claude-sonnet-4.6; choose a model enabled for your account. Your Cereal key configures the environment; the provider key pays for model calls.

To use another supported provider, change the primary declaration in src/agent.ts to its adapter type and credential. An OpenAI-compatible provider also needs baseUrl, the model provider's HTTPS endpoint. See provider configuration.

Run the first session

pnpm quickstart

The script initializes the agent and its development channel, asks about the Orion launch risks, prints the tool result and response, then closes the channel.

const agent = createResearchAgent()
try {
  const session = await agent.sessions.start({
    message: "What are the Orion launch risks? Cite your sources.",
    identity: { scope: "user", id: "ada" },
    metadata: { workspaceId: "ws_ada" }
  })
  console.log("Session:", session.id)
  for await (const event of agent.sessions.stream(session.id, {
    signal: AbortSignal.timeout(120_000)
  })) {
    if (event.type === "agent.message") console.log(event.text)
    if (event.type === "tool.call.completed") console.log("Tool result:", JSON.stringify(event))
    if (event.type === "session.status" && event.status === "idle") {
      if (event.stopReason !== "completed") throw new Error(`Turn stopped: ${event.stopReason}`)
      break
    }
  }
} finally {
  await agent.close()
}

Expect search_sources to find launch-plan and security-review, followed by read_source calls. The evidence identifies incomplete load testing and unfinished API key rotation documentation. The answer should cite those source IDs. The model's wording may vary. The script prints the session ID; find it under Sessions in the console, then inspect Trace and Events.

The source tools run in your application; the model loop runs in Cereal. A third tool, publish_brief, is reserved for the optional hook lesson. The initial research task finishes without an approval.

What happened

createResearchAgent calls defineAgent with a reusable provider reference. The sample .env sets NODE_ENV=development, which automatically selects local channels. agent.sessions.start() initializes the provider, opens the outbound channel and registers the agent before creating the session. The model loop runs in Cereal; your process serves the tools. There is no separate setup step. Call await agent.init() if you want to initialize early at app startup.

The fixed identity is appropriate for this terminal demonstration. The application tutorial derives identity from authenticated requests before starting sessions.

Next: add a browser to the same agent.