Build your first agent

By the end of this tutorial, a Node.js script will send a request to Kestrel and read its terminal result. The script uses kestrel web, the authenticated loopback HTTP bridge to Local Core.

Before you start

You need Node.js 20 or newer and a configured local Kestrel installation. Run:

kestrel setup --profile reference
kestrel web

kestrel web prints KESTREL_RUNNER_SERVICE_URL and KESTREL_RUNNER_SERVICE_TOKEN. Export those values in the terminal that will run the script. Keep the token in server-side code.

The profile ID used by the SDK is reference. Its implementation is reference-react. Applications select the profile; they do not invent a new agent implementation name.

Install the SDK

pnpm add @kestrel-agents/sdk@0.7.0
pnpm add -D tsx

Create and run the agent

Create scripts/reference-agent-smoke.ts:

import { createAgent } from "@kestrel-agents/sdk";
 
const agent = createAgent({
  id: "reference-agent",
  profileId: "reference",
  target: {
    kind: "remote",
    baseUrl: process.env.KESTREL_RUNNER_SERVICE_URL!,
    authToken: process.env.KESTREL_RUNNER_SERVICE_TOKEN!,
  },
});
 
const context = {
  actor: {
    actorId: "user-123",
    actorType: "end_user" as const,
    displayName: "Taylor Example",
    tenantId: "acme",
  },
  tenantId: "acme",
};
 
const terminal = await agent.run(
  {
    sessionId: "reference-session-001",
    message: "Summarize the current project and identify the next useful task.",
  },
  context,
);
 
console.log(terminal.type);
console.log(terminal.payload.result.assistantText);
await agent.close();

Run it from the project directory:

pnpm exec tsx scripts/reference-agent-smoke.ts

kind: "remote" selects HTTP because the script is using the loopback bridge. The bridge forwards the request to Local Core, which remains responsible for execution and durable state. An explicit local SDK target instead uses Local Core's Unix socket and token.

Read the terminal result

terminal.type identifies whether the run completed, failed, was cancelled, or is waiting. For a completed run, terminal.payload.result.assistantText is the canonical text to show a person. Structured application data remains in terminal.payload.result.output.

Reuse reference-session-001 for a follow-up that belongs to the same conversation. Choose a new session ID for unrelated work.

Continue with your first streamed request or review terminal results.