Agents

The Agent class is the core runtime loop in the TypeScript SDK. It coordinates generations, tool calls, and lifecycle events, while a Trajectory records everything that happened.

Key types & signatures

class Agent {
  constructor(config: AgentConfig);
  run(options: RunOptions): Promise<AgentResult>;
  stream(options: RunOptions): AsyncGenerator<AgentEvent>;
}

function createAgent(config: AgentConfig): Agent;

class Trajectory {
  constructor(options: {
    sessionId?: string;
    agentId: string;
    agentName?: string;
    systemPrompt?: string;
  });
  get events(): readonly AgentEvent[];
  get messages(): Message[];
  get lastMessage(): Message | undefined;
}

const reactions: {
  continue(options?: { messages?: Message[]; feedback?: string }): Reaction;
  retry(): Reaction;
  retryWithFeedback(feedback: string): Reaction;
  fail(reason: string): Reaction;
  finish(result?: unknown): Reaction;
};

Create and run an agent

import { anthropic } from '@ai-sdk/anthropic';
import { createAgent, createGenerator } from '@dreadnode/agents';

const generator = await createGenerator(anthropic('claude-sonnet-4-20250514'));

const agent = createAgent({
  name: 'support-agent',
  generator,
  systemPrompt: 'You are a crisp, friendly support agent.',
});

async function main(): Promise<void> {
  const result = await agent.run({
    input: 'Summarize the Dreadnode platform in one sentence.',
  });

  const message = result.trajectory.lastMessage;
  if (message) {
    console.log(message.text);
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

Add reactions with hooks

Hooks listen to agent events and can return reactions to steer or stop the loop.

import { anthropic } from '@ai-sdk/anthropic';
import {
  createAgent,
  createGenerator,
  hook,
  reactions,
  type GenerationStepEvent,
} from '@dreadnode/agents';

const generator = await createGenerator(anthropic('claude-sonnet-4-20250514'));

const qualityHook = hook<GenerationStepEvent>('retry-on-empty', 'GenerationStep', (event) => {
  const hasOutput = event.messages.some((msg) => msg.role === 'assistant');
  return hasOutput ? null : reactions.retryWithFeedback('Please provide a complete answer.');
});

const agent = createAgent({
  name: 'quality-agent',
  generator,
  hooks: [qualityHook],
});

const result = await agent.run({ input: 'Write a one-line mission statement.' });
console.log(result.trajectory.lastMessage?.text ?? 'No output');

Trajectory highlights

The Trajectory records all events, messages, usage, and stop reasons. Use it to:

Inspect the final output (trajectory.lastMessage)
Review all events (trajectory.events)
Compute token usage (trajectory.usage)