LanguageEN繁
Home
Docs

SDK tutorial · 1 of 10

Build your first agent

Use Heddle's quickstart runner to prove the model, credentials, conversation state, and streaming output before you design a custom product surface.

Customization depth

Level 1 · Default conversation loop

Hosting depth

One Node.js 20+ process

Documentation status

Runnable reference

Assumptions

  • Your project uses Node.js 20 or newer and ESM-compatible TypeScript.
  • You installed @roackb2/heddle and configured one supported model credential.
  • For this first step, Heddle may own an interactive terminal prompt and plain-text output.
Heddle owns
  • Resolve the workspace, local state root, model, and credential before opening the conversation.
  • Create and persist the conversation session, run turns, and render streaming text and status.
  • Record traces and artifacts under the resolved local state root.
Your product owns
  • Choose the model and provide its credential.
  • Supply product-specific system context and decide when to replace the terminal experience.
  • Choose a durable application-data location before treating the local defaults as production storage.

What you will build

You will run a persisted conversational agent from a TypeScript entrypoint. This is an SDK evaluation path, not the full Heddle coding-agent CLI. It deliberately owns the local prompt loop so you can verify the runtime before adding product UI, tools, hosting, or custom storage.

1. Install the runtime package

Shell
npm install @roackb2/heddle

The root package is the curated Node.js SDK. Do not import it into browser code; remote browser clients use the separate @roackb2/heddle-remote package later in the hosting path.

2. Configure a model

For the stable OpenAI path:

Shell
export OPENAI_API_KEY=your_key_here
export HEDDLE_MODEL=gpt-5.4

For Anthropic, use ANTHROPIC_API_KEY and select a Claude model. Local and OpenAI-compatible providers use their documented provider prefixes. Keep credentials in your server environment or secret manager—never put them in prompts, system context, or persisted product records.

3. Create the entrypoint

TypeScript
import { runQuickstartConversationCli } from '@roackb2/heddle'

await runQuickstartConversationCli()

If the project does not already have a TypeScript runner, install tsx and run the entrypoint directly:

Shell
npm install --save-dev tsx
npx tsx src/agent.ts

The equivalent runnable example in the Heddle repository is:

Shell
yarn example:sdk:interactive

What the quickstart resolves

With no options, the runner uses:

  • the current working directory as workspaceRoot;
  • .heddle inside that workspace as stateRoot;
  • the first configured model from HEDDLE_MODEL, HEDDLE_EXAMPLE_MODEL, OPENAI_MODEL, or ANTHROPIC_MODEL, followed by Heddle's built-in OpenAI default;
  • credential preflight that fails before session creation when the selected model cannot authenticate;
  • no default hard step budget;
  • no automatic memory-maintenance run;
  • persisted conversation state and a plain-text streaming host.

The runner prints the selected model and credential source. That is useful evidence when a machine has more than one possible credential path.

Add a small amount of product behavior

Stay on the quickstart layer while the terminal loop is still acceptable:

TypeScript
import { runQuickstartConversationCli } from '@roackb2/heddle'

await runQuickstartConversationCli({
  model: process.env.MY_PRODUCT_MODEL,
  systemContext: 'You help users understand their project workspace.',
  promptLabel: 'project> ',
  credentialPreflight: {
    missingCredentialHint: 'Configure a model credential for this product first.',
  },
})

Only set maxSteps when your product intentionally wants a hard turn budget. An arbitrary small value can stop a valid tool workflow before it finishes.

Verify the checkpoint

Before continuing, confirm that:

  1. credential preflight identifies the model and auth source;
  2. a prompt produces streamed output and a final result;
  3. the process creates durable state beneath the configured stateRoot;
  4. a later prompt in the same run continues the persisted conversation.

Move to the conversation engine when your product needs its own rendering, commands, approval UI, session browser, or lifecycle.

Canonical sources