Agent Configuration

Agents are the core building blocks of our framework, designed to be both powerful individual workers and collaborative team members in multi-agent systems. Through the framework's agent graph architecture, each agent can seamlessly delegate tasks, share context, and work together using structured data components.

Creating an Agent

Every agent needs a unique identifier, and clear prompt that define its behavior:

import { agent } from "./builder/index";

const supportAgent = agent({
  id: "customer-support",
  name: "Customer Support Agent",
  description: "Handles customer inquiries and support tickets",
  prompt: `You are a customer support specialist. Always be helpful, professional, and empathetic.`,
});

Agent Options

The framework supports rich agent configuration. Here are the options you can configure:

const agent = agent({
  // Required
  id: "my-agent-id", // Stable agent identifier (required for consistency)
  name: "My Agent", // Human-readable agent name
  description: "Agent description", // Brief description of the agent's purpose
  prompt: "Detailed behavior guidelines", // System prompt

  // Optional - AI Model Settings
  models: {
    base: {
      model: "anthropic/claude-4-sonnet-20250514",
      providerOptions: {
        temperature: 0.7,
        maxTokens: 2048,
        timeout: 30000,
      },
    },
    structuredOutput: {
      model: "openai/gpt-4.1-mini-2025-04-14", // For structured JSON output
      providerOptions: {
        temperature: 0.1,
        maxTokens: 1024,
      },
    },
    summarizer: {
      model: "openai/gpt-4.1-nano-2025-04-14", // For summaries
      providerOptions: {
        temperature: 0.5,
        maxTokens: 1000,
      },
    },
  },

  // Optional - Tools Integration
  tools: {
    searchTool: mySearchTool, // Custom tools
    mcpTool: myMCPTool, // MCP (Model Context Protocol) tools
  },

  // Optional - Data Components (Structured Outputs)
  dataComponents: [
    {
      id: "customer-info",
      name: "CustomerInfo",
      description: "Customer information display component",
      props: {
        type: "object",
        properties: {
          name: { type: "string", description: "Customer name" },
          email: { type: "string", description: "Customer email" },
          issue: { type: "string", description: "Customer issue description" },
        },
        required: ["name", "email", "issue"],
      },
    },
  ],

  // Optional - Artifact Components (Structured Outputs from tools or agents)
  artifactComponents: [
    {
      id: "customer-info",
      name: "CustomerInfo",
      description: "Customer information display component",
      summaryProps: {
        type: "object",
        properties: {
          name: { type: "string", description: "Customer name" },
        },
        required: ["name"],
      },
      fullProps: {
        type: "object",
        properties: {
          customer_info: {
            type: "string",
            description: "Customer information",
          },
        },
        required: ["customer_info"],
      },
    },
  ],

  // Optional - Agent Relationships (for multi-agent systems)
  canTransferTo: () => [agent1], // Agents this can hand off to
  canDelegateTo: () => [agent2], // Agents this can delegate to
});

Parameter	Type	Required	Description
`id`	string	Yes	Stable agent identifier used for consistency and persistence
`name`	string	Yes	Human-readable name for the agent
`description`	string	Yes	Brief description of the agent's purpose and capabilities
`prompt`	string	Yes	Detailed behavior guidelines and system prompt for the agent
`models`	object	No	AI model settings with separate settings for base, structuredOutput, and summarizer models
`tools`	object	No	MCP tools that the agent can use. See MCP Servers for details
`dataComponents`	array	No	Structured output components for rich, interactive responses. See Data Components for details
`artifactComponents`	array	No	Components for handling tool or agent outputs. See Artifact Components for details
`canTransferTo`	function	No	Function returning array of agents this agent can transfer to. See Transfer Relationships for details
`canDelegateTo`	function	No	Function returning array of agents this agent can delegate to. See Delegation Relationships for details

Model Settings

The models object allows you to configure different models for different tasks, each with their own provider options:

models: {
  base: {
    model: "anthropic/claude-4-sonnet-20250514", // Primary model for text generation
    providerOptions: {
      temperature: 0.7,
      maxTokens: 2048
    }
  },
  structuredOutput: {
    model: "openai/gpt-4o-mini-2024-07-18", // For structured JSON output only
    providerOptions: {
      temperature: 0.1,
      maxTokens: 1024
    }
  },
  summarizer: {
    model: "anthropic/claude-3-haiku-20240307", // For summaries and status updates
    providerOptions: {
      temperature: 0.5,
      maxTokens: 1000
    }
  }
}

Model Types

base: Primary model used for conversational text generation and reasoning
structuredOutput: Model used for structured JSON output only (falls back to base if not configured and nothing to inherit)
summarizer: Model used for summaries and status updates (falls back to base if not configured and nothing to inherit)

Default Models

When no model settings are configured at any level (project, graph, or agent), the system uses these defaults:

Default base model: anthropic/claude-4-sonnet-20250514
Default structured output model: openai/gpt-4.1-mini-2025-04-14
Default summarizer model: openai/gpt-4.1-nano-2025-04-14

Required API Keys: For the system defaults to work properly, you need both:

ANTHROPIC_API_KEY (for the base model)
OPENAI_API_KEY (for structured output and summarizer models)

Provider Options

Each model settings can include providerOptions with provider-specific settings:

temperature: Response creativity (0.0-1.0)
maxTokens: Maximum response length
timeout: Request timeout in milliseconds (e.g., 30000 for 30 seconds)
Provider-specific options vary by provider

Inheritance

If no models settings are specified, the agent will inherit the models settings from its agent graph, which may inherit from the project settings.

Graph Prompt Integration

Agents automatically receive any graph-level prompt configuration in addition to their individual prompt:

// Graph-level prompt that gets added to all agents
const graph = agentGraph({
  id: "support-graph",
  graphPrompt: `You work for Acme Corp. Always be professional and helpful. 
Follow company policies and escalate complex issues appropriately.`,
  agents: () => [supportAgent, escalationAgent],
});

The graphPrompt is injected into each agent's system prompt, providing consistent context and behavior guidelines across all agents in the graph.

Agent Configuration

On this page