BuiltInAgent

Pre-built agent class powered by Vercel AI SDK

Overview

BuiltInAgent is a ready-to-use agent implementation that integrates with OpenAI, Anthropic, and Google models through the Vercel AI SDK. It handles message formatting, tool execution, state management, and streaming responses with minimal configuration.

Constructor

new BuiltInAgent(config: BuiltInAgentConfiguration)

Configuration

model · BuiltInAgentModel | LanguageModel · required

The language model to use. Can be a string identifier or a LanguageModel instance.

Supported models:

• OpenAI: "openai/gpt-5", "openai/gpt-4o", "openai/gpt-4o-mini", "openai/o3-mini"
• Anthropic: "anthropic/claude-sonnet-4.5", "anthropic/claude-opus-4", "anthropic/claude-3.5-haiku"
• Google: "google/gemini-2.5-pro", "google/gemini-2.5-flash"

model: 'openai/gpt-4o'
// or
model: 'anthropic/claude-sonnet-4.5'
// or custom LanguageModel instance
model: customModel

apiKey · string

API key for the model provider. If not provided, falls back to environment variables:

• OPENAI_API_KEY for OpenAI models
• ANTHROPIC_API_KEY for Anthropic models
• GOOGLE_API_KEY for Google models

apiKey: process.env.OPENAI_API_KEY

prompt · string

System prompt for the agent. Defines the agent’s behavior and personality.

prompt: 'You are a helpful assistant that specializes in customer support.'

maxSteps · number · default: "1"

Maximum number of tool-calling iterations. Controls how many times the agent can call tools in a single run.

maxSteps: 5  // Allow up to 5 tool calls

toolChoice · ToolChoice · default: "'auto'"

How tools are selected for execution:

• "auto": Model decides when to use tools
• "required": Model must use a tool
• "none": Model cannot use tools
• { type: "tool", toolName: "..." }: Force specific tool

toolChoice: 'required'  // Force tool use

maxOutputTokens · number

Maximum number of tokens to generate.

maxOutputTokens: 2000

temperature · number

Sampling temperature (range depends on provider). Higher values make output more random.

temperature: 0.7

topP · number

Nucleus sampling parameter. Alternative to temperature.

topP: 0.9

topK · number

Top-K sampling parameter.

topK: 40

presencePenalty · number

Penalty for token presence. Reduces repetition.

presencePenalty: 0.6

frequencyPenalty · number

Penalty for token frequency. Reduces repetition.

frequencyPenalty: 0.5

stopSequences · string[]

Sequences that will stop generation.

stopSequences: ['END', 'STOP']

seed · number

Seed for deterministic results (where supported by the provider).

seed: 42

maxRetries · number

Maximum number of retries for failed requests.

maxRetries: 3

providerOptions · Record<string, any>

Provider-specific options passed to the model.

providerOptions: {
  openai: {
    reasoningEffort: 'high'  // For o-series models
  }
}

overridableProperties · OverridableProperty[]

List of properties that can be overridden by forwardedProps from the client.

overridableProperties: ['temperature', 'maxOutputTokens']

mcpServers · MCPClientConfig[]

MCP (Model Context Protocol) server configurations.

mcpServers: [
  {
    type: 'http',
    url: 'https://mcp-server.example.com',
    options: {
      headers: { 'Authorization': 'Bearer token' }
    }
  }
]

tools · ToolDefinition[]

Server-side tools available to the agent. These tools execute on the server.

tools: [
  defineTool({
    name: 'getWeather',
    description: 'Get weather for a location',
    parameters: z.object({
      location: z.string()
    }),
    execute: async ({ location }) => {
      const response = await fetch(`/api/weather?loc=${location}`);
      return response.json();
    }
  })
]

forwardSystemMessages · boolean · default: "false"

Whether to forward system-role messages from input to the LLM.

forwardSystemMessages: true

forwardDeveloperMessages · boolean · default: "false"

Whether to forward developer-role messages from input to the LLM (as system messages).

forwardDeveloperMessages: true

Methods

run()

Execute the agent with given input. Inherited from AbstractAgent.

run(input: RunAgentInput): Observable<BaseEvent>

Returns an RxJS Observable that emits AG-UI protocol events.

abortRun()

Abort the currently running agent execution.

abortRun(): void

clone()

Create a copy of the agent with the same configuration.

clone(): BuiltInAgent

canOverride()

Check if a property can be overridden by forwardedProps.

canOverride(property: OverridableProperty): boolean

Usage Examples

Basic Agent

import { BuiltInAgent } from '@copilotkit/agent';

const agent = new BuiltInAgent({
  model: 'openai/gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  prompt: 'You are a helpful assistant.'
});

With Tools

import { BuiltInAgent, defineTool } from '@copilotkit/agent';
import { z } from 'zod';

const agent = new BuiltInAgent({
  model: 'openai/gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  prompt: 'You are a helpful assistant with access to tools.',
  
  tools: [
    defineTool({
      name: 'searchDatabase',
      description: 'Search the product database',
      parameters: z.object({
        query: z.string(),
        category: z.string().optional()
      }),
      execute: async ({ query, category }) => {
        const results = await database.search(query, category);
        return results;
      }
    }),
    
    defineTool({
      name: 'getInventory',
      description: 'Get current inventory levels',
      parameters: z.object({
        productId: z.string()
      }),
      execute: async ({ productId }) => {
        const inventory = await database.getInventory(productId);
        return inventory;
      }
    })
  ]
});

With Multiple Steps

const agent = new BuiltInAgent({
  model: 'openai/gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  prompt: 'You are a research assistant. Use tools to gather information.',
  maxSteps: 5,  // Allow multiple tool calls
  tools: [researchTools]
});

With Custom Temperature

const agent = new BuiltInAgent({
  model: 'anthropic/claude-sonnet-4.5',
  apiKey: process.env.ANTHROPIC_API_KEY,
  prompt: 'You are a creative writing assistant.',
  temperature: 1.0,  // More creative
  maxOutputTokens: 2000
});

With Overridable Properties

const agent = new BuiltInAgent({
  model: 'openai/gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  temperature: 0.7,
  maxOutputTokens: 1000,
  
  // Allow clients to override these
  overridableProperties: ['temperature', 'maxOutputTokens']
});

// Client can now override:
// forwardedProps: { temperature: 0.9, maxOutputTokens: 2000 }

With MCP Servers

const agent = new BuiltInAgent({
  model: 'openai/gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  
  mcpServers: [
    {
      type: 'http',
      url: 'https://filesystem-mcp.example.com',
      options: {
        headers: {
          'Authorization': `Bearer ${process.env.MCP_TOKEN}`
        }
      }
    },
    {
      type: 'sse',
      url: 'https://database-mcp.example.com',
      headers: {
        'X-API-Key': process.env.MCP_API_KEY
      }
    }
  ]
});

Multi-Model Configuration

const openAIAgent = new BuiltInAgent({
  model: 'openai/gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
  prompt: 'You are a customer service agent.'
});

const anthropicAgent = new BuiltInAgent({
  model: 'anthropic/claude-sonnet-4.5',
  apiKey: process.env.ANTHROPIC_API_KEY,
  prompt: 'You are a technical support specialist.'
});

const geminiAgent = new BuiltInAgent({
  model: 'google/gemini-2.5-pro',
  apiKey: process.env.GOOGLE_API_KEY,
  prompt: 'You are a research assistant.'
});

With Reasoning Models

const reasoningAgent = new BuiltInAgent({
  model: 'openai/o3-mini',
  apiKey: process.env.OPENAI_API_KEY,
  prompt: 'You are a problem-solving assistant.',
  providerOptions: {
    openai: {
      reasoningEffort: 'high'  // o-series specific
    }
  }
});

Custom LanguageModel

import { createOpenAI } from '@ai-sdk/openai';

const customProvider = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: 'https://custom-endpoint.example.com/v1'
});

const agent = new BuiltInAgent({
  model: customProvider('gpt-4o'),
  prompt: 'You are a helpful assistant.'
});

State Management

BuiltInAgent automatically handles application state updates through special tools:

State Snapshot

Replace the entire application state:

// Agent calls AGUISendStateSnapshot tool
{
  snapshot: {
    user: { id: '123', name: 'John' },
    items: [...]
  }
}

// Client receives STATE_SNAPSHOT event

State Delta

Apply incremental updates using JSON Patch operations:

// Agent calls AGUISendStateDelta tool
{
  delta: [
    { op: 'replace', path: '/user/name', value: 'Jane' },
    { op: 'add', path: '/items/-', value: { id: '456' } }
  ]
}

// Client receives STATE_DELTA event

These tools are automatically available to all BuiltInAgent instances.

Runtime Integration

Use with CopilotRuntime:

import { CopilotRuntime } from '@copilotkit/runtime';
import { BuiltInAgent } from '@copilotkit/agent';

const runtime = new CopilotRuntime({
  agents: {
    'default': new BuiltInAgent({
      model: 'openai/gpt-4o',
      apiKey: process.env.OPENAI_API_KEY
    }),
    
    'research': new BuiltInAgent({
      model: 'anthropic/claude-sonnet-4.5',
      apiKey: process.env.ANTHROPIC_API_KEY,
      tools: [researchTools],
      maxSteps: 10
    })
  }
});

Model Resolution

The resolveModel() helper function converts string identifiers to LanguageModel instances:

import { resolveModel } from '@copilotkit/agent';

// Automatic resolution
const model = resolveModel('openai/gpt-4o', process.env.OPENAI_API_KEY);

// Supports various formats
resolveModel('openai/gpt-4o');
resolveModel('anthropic:claude-sonnet-4.5');
resolveModel('google/gemini-2.5-pro');

Error Handling

BuiltInAgent emits error events through the Observable:

const subscription = agent.run(input).subscribe({
  next: (event) => {
    if (event.type === 'RUN_ERROR') {
      console.error('Agent error:', event.message);
    }
  },
  error: (err) => {
    console.error('Fatal error:', err);
  }
});

Performance Considerations

• maxSteps: Higher values allow more tool interactions but increase latency
• temperature: Lower values (0.1-0.3) are faster and more deterministic
• maxOutputTokens: Limit token generation for faster responses
• Streaming: Events are streamed as generated (real-time feedback)

See Also

• defineTool - Tool definition helper
• AbstractAgent - Agent interface
• CopilotRuntime - Runtime configuration