/output-dev-agent-class

name: output-dev-agent-class
description: Use the Agent class for multi-step tool loops, conversation history, and reusable LLM agents. Use when building agents with skills, structured output, or stateful conversations.
allowed-tools: [Read, Write, Edit]

Using the Agent Class

Overview

The `Agent` class extends AI SDK's `ToolLoopAgent` with Output prompt files and the skills system. Use it when you need multi-step tool execution, conversation history, or a reusable agent instance. For single-shot LLM calls without tools, `generateText` is simpler.

When to Use This Skill

• Building multi-step agents that call tools in a loop
• Using skills (lazy-loaded instructions) with an agent
• Creating agents with structured output via `Output.object()`
• Implementing stateful conversations with `conversationStore`
• Deciding between `Agent` and `generateText`

Import Pattern

import { Agent, createMemoryConversationStore, skill, Output } from '@outputai/llm';
import { z } from '@outputai/core';

`Agent`, `createMemoryConversationStore`, `skill`, and `Output` all come from `@outputai/llm`. Import `z` from `@outputai/core` (never from `zod` directly).

Construction

The prompt file is loaded and rendered at construction time. Variables, skills, and tools are fixed at construction. The agent is ready to call `generate()` or `stream()` immediately.

const agent = new Agent( {
  prompt: 'writing_assistant@v1',
  variables: {
    content_type: input.contentType,
    focus: input.focus,
    content: input.content
  },
  skills: [ audienceSkill ],
  output: Output.object( { schema: reviewSchema } ),
  maxSteps: 5
} );

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | `prompt` | `string` | *(required)* | Prompt file name (e.g. `'writing_assistant@v1'`) | | `variables` | `Record<string, unknown>` | `{}` | Template variables rendered at construction | | `skills` | `Skill[]` | `[]` | Skill packages for the LLM (see `output-dev-skill-file`) | | `tools` | `ToolSet` | `{}` | AI SDK tools available during the loop | | `maxSteps` | `number` | `10` | Maximum tool-loop iterations | | `stopWhen` | `StopCondition` | - | Custom stop condition (overrides `maxSteps`) | | `output` | `Output` | - | Structured output spec (e.g. `Output.object({ schema })`) | | `conversationStore` | `ConversationStore` | - | Pluggable store for multi-turn history | | `temperature` | `number` | - | Override prompt file temperature | | `onStepFinish` | `Function` | - | Callback after each tool-loop step | | `prepareStep` | `Function` | - | Customize each step before execution |

generate()

Run the agent and return when complete:

const result = await agent.generate();
console.log( result.text );   // Generated text
console.log( result.output ); // Structured output (when using Output.object)
console.log( result.usage );  // Token counts

The result has the same shape as `generateText`: `text`, `result` (alias for `text`), `output`, `usage`, `finishReason`, `toolCalls`, etc.

Passing Additional Messages

Extend the conversation with extra messages:

const result = await agent.generate( {
  messages: [ { role: 'user', content: 'Focus on the introduction section.' } ]
} );

Messages are appended after the initial prompt messages (and any conversation store history).

stream()

Stream the agent's response:

const stream = await agent.stream();

for await ( const chunk of stream.textStream ) {
  process.stdout.write( chunk );
}

Like `streamText`, the stream result provides `textStream` and `fullStream` iterables, plus promise-based properties (`text`, `usage`, `finishReason`) that resolve on completion.

**Important**: `stream()` does not automatically append messages to the conversation store. If you use streaming with a conversation store, persist messages manually.

Structured Output

Use `Output.object()` to get typed responses:

const reviewSchema = z.object( {
  issues: z.array( z.string() ).describe( 'List of issues found' ),
  suggestions: z.array( z.string() ).describe( 'Actionable suggestions' ),
  score: z.number().describe( 'Quality score 0-100' ),
  summary: z.string().describe( 'Brief overall assessment' )
} );

const agent = new Agent( {
  prompt: 'writing_assistant@v1',
  variables: { content_type: 'documentation', focus: 'clarity', content: markdownContent },
  output: Output.object( { schema: reviewSchema } ),
  maxSteps: 5
} );

const { output } = await agent.generate();
// output: { issues: string[], suggestions: string[], score: number, summary: string }

Use `.describe()` on schema fields instead of `.min()/.max()` for number constraints. Anthropic does not support `minimum`/`maximum` JSON Schema constraints in tool definitions.

Conversation Store

By default, Agent is stateless. Each `generate()` call starts fresh with only the initial prompt messages. Pass a `conversationStore` to maintain history across calls:

import { Agent, createMemoryConversationStore } from '@outputai/llm';

const store = createMemoryConversationStore();
const chatbot = new Agent( {
  prompt: 'chatbot@v1',
  conversationStore: store
} );

const r1 = await chatbot.generate( {
  messages: [ { role: 'user', content: 'Hello, tell me about Output.' } ]
} );
// r1.text: "Output is an AI framework for..."

const r2 = await chatbot.generate( {
  messages: [ { role: 'user', content: 'How does it handle retries?' } ]
} );
// r2 sees the full conversation history from r1

Custom Store

For production use, implement the `ConversationStore` interface with your database:

interface ConversationStore {
  getMessages(): ModelMessage[] | Promise<ModelMessage[]>;
  addMessages(messages: ModelMessage[]): void | Promise<void>;
}

`createMemoryConversationStore()` is the built-in in-memory implementation.

Using Agent in