Agent Configuration

Sonamu allows you to build AI agents based on the Vercel AI SDK. It supports various LLM providers like OpenAI and Anthropic, and you can define custom tools to enable agents to perform specific tasks.

What is an AI Agent?

An AI Agent is a system that provides tools to a conversational AI model (LLM), allowing it to automatically perform complex tasks. Characteristics:

LLM selects and executes appropriate tools based on context
Automatically performs multi-step tasks
Maintains context throughout conversations

Required Package Installation

To use AI agents, you need to install the Vercel AI SDK and LLM provider packages.

Using OpenAI

pnpm add ai @ai-sdk/openai

Using Anthropic

pnpm add ai @ai-sdk/anthropic

Using Both

pnpm add ai @ai-sdk/openai @ai-sdk/anthropic

Basic Configuration

Environment Variables

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

LLM Model Initialization

OpenAI
Anthropic
Custom

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

const model = openai('gpt-4o');  // GPT-4 Optimized

Supported Models:

gpt-4o: GPT-4 Optimized (latest)
gpt-4-turbo: GPT-4 Turbo
gpt-4: GPT-4
gpt-3.5-turbo: GPT-3.5 Turbo

import { anthropic } from '@ai-sdk/anthropic';

const model = anthropic('claude-3-5-sonnet-20241022');  // Claude 3.5 Sonnet

Supported Models:

claude-3-5-sonnet-20241022: Claude 3.5 Sonnet (latest)
claude-3-opus-20240229: Claude 3 Opus
claude-3-sonnet-20240229: Claude 3 Sonnet
claude-3-haiku-20240307: Claude 3 Haiku

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

const model = openai('gpt-4o', {
  baseURL: 'https://api.custom.com/v1',
  apiKey: process.env.CUSTOM_API_KEY,
});

AgentConfig

The agent configuration object.

import type { AgentConfig } from "sonamu/ai";

const config: AgentConfig = {
  model: openai('gpt-4o'),
  instructions: "You are a hotel booking assistant.",
  toolChoice: 'auto',
  temperature: 0.7,
  maxOutputTokens: 1000,
};

Key Options

model
instructions
toolChoice
temperature

LLM Model (required)

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

config: {
  model: openai('gpt-4o'),
  // model: anthropic('claude-3-5-sonnet-20241022'),
}

System Prompt

config: {
  model: openai('gpt-4o'),
  instructions: `
    You are a friendly customer support chatbot.
    Always respond politely and use tools when necessary.
  `,
}

Tool Usage Strategy

config: {
  model: openai('gpt-4o'),
  toolChoice: 'auto',  // 'auto' | 'none' | 'required'
}

Options:

'auto': AI uses tools when needed (default)
'none': No tool usage
'required': Must use tools

Creativity Control

config: {
  model: openai('gpt-4o'),
  temperature: 0.7,  // 0.0 ~ 2.0
}

Range: 0.0 ~ 2.0

0.0: Deterministic (consistent responses)
0.7: Balanced (default)
1.5+: Creative (varied responses)

Additional Options

const config: AgentConfig = {
  model: openai('gpt-4o'),

  // Token limits
  maxOutputTokens: 1000,

  // Advanced parameters
  topP: 0.9,                    // Top-P sampling
  topK: 50,                     // Top-K sampling
  presencePenalty: 0.0,         // Topic repetition suppression
  frequencyPenalty: 0.0,        // Word repetition suppression

  // Stop conditions
  stopSequences: ['\n\n'],      // Stop sequences

  // Reproducibility
  seed: 12345,                  // Fixed seed

  // HTTP headers
  headers: {
    'X-Custom-Header': 'value',
  },
};

Practical Configuration Examples

1. Customer Support Chatbot

import { openai } from '@ai-sdk/openai';
import type { AgentConfig } from "sonamu/ai";

const config: AgentConfig = {
  model: openai('gpt-4o'),
  instructions: `
    You are an e-commerce customer support chatbot.
    - Help with order lookup, delivery tracking, and refund processing.
    - Always respond politely and clearly.
    - Use tools when needed to provide accurate information.
  `,
  toolChoice: 'auto',
  temperature: 0.3,  // Consistent responses
  maxOutputTokens: 500,
};

2. Creative Content Generation

import { anthropic } from '@ai-sdk/anthropic';
import type { AgentConfig } from "sonamu/ai";

const config: AgentConfig = {
  model: anthropic('claude-3-5-sonnet-20241022'),
  instructions: `
    You are a blog writing assistant.
    - Write creative content on given topics.
    - Consider SEO optimization.
    - Search for related information when needed.
  `,
  toolChoice: 'auto',
  temperature: 1.0,  // Creative
  maxOutputTokens: 2000,
};

3. Data Analysis Agent

import { openai } from '@ai-sdk/openai';
import type { AgentConfig } from "sonamu/ai";

const config: AgentConfig = {
  model: openai('gpt-4o'),
  instructions: `
    You are a data analysis expert.
    - Generate and execute SQL queries.
    - Analyze data and provide insights.
    - Create visualization charts.
  `,
  toolChoice: 'required',  // Always use tools
  temperature: 0.0,  // Accurate queries
  maxOutputTokens: 1500,
};

4. Multimodal Agent

import { openai } from '@ai-sdk/openai';
import type { AgentConfig } from "sonamu/ai";

const config: AgentConfig = {
  model: openai('gpt-4o'),  // Image support
  instructions: `
    You are an image analysis and description expert.
    - Analyze images and describe them in detail.
    - Search for related information when needed.
  `,
  toolChoice: 'auto',
  temperature: 0.5,
  maxOutputTokens: 1000,
};

Environment-Specific Configuration

Development Environment

const isDevelopment = process.env.NODE_ENV === 'development';

const config: AgentConfig = {
  model: isDevelopment
    ? openai('gpt-3.5-turbo')  // Fast and cheap
    : openai('gpt-4o'),        // For production

  instructions: "...",

  temperature: isDevelopment ? 0.0 : 0.7,  // Development: consistency
  maxOutputTokens: isDevelopment ? 500 : 2000,
};

Production Environment

const config: AgentConfig = {
  model: openai('gpt-4o', {
    apiKey: process.env.OPENAI_API_KEY,
  }),

  instructions: "...",

  // Stable settings
  temperature: 0.5,
  maxOutputTokens: 1000,

  // Reproducibility
  seed: parseInt(process.env.AGENT_SEED || '0'),

  // Monitoring headers
  headers: {
    'X-Environment': 'production',
    'X-Version': process.env.APP_VERSION,
  },
};

Cost Optimization

Model Selection

Model	Performance	Cost	Speed	Recommended Use
GPT-4o	Highest	High	Medium	Complex tasks
GPT-4 Turbo	High	Medium	Fast	General tasks
GPT-3.5 Turbo	Medium	Low	Very fast	Simple tasks
Claude 3.5 Sonnet	Highest	Medium	Fast	Coding, analysis
Claude 3 Haiku	Low	Very low	Very fast	Simple tasks

Token Limits

const config: AgentConfig = {
  model: openai('gpt-4o'),

  // Output token limit
  maxOutputTokens: 500,  // Cost savings

  // Concise instructions
  instructions: "Respond briefly.",
};

Precautions

Important considerations when configuring agents:

API Key Security: Environment variables required

// ❌ Hardcoded
model: openai('gpt-4o', { apiKey: 'sk-...' })

// ✅ Environment variable
model: openai('gpt-4o', { apiKey: process.env.OPENAI_API_KEY })

Token Limits: Set maxOutputTokens

maxOutputTokens: 1000,  // Cost control

Temperature Range: 0.0 ~ 2.0

temperature: 0.7,  // Appropriate value

toolChoice Selection: Configure based on use case

// Data analysis: required
// General conversation: auto
// Pure conversation: none

Instructions Clarity: Specific instructions

// ❌ Vague
instructions: "Help me"

// ✅ Clear
instructions: "Customer support chatbot that helps with order lookup, delivery tracking, and refund processing"

Cost Monitoring: Track token usage in production

Next Steps

Creating Agents

Build agents with BaseAgentClass

Using the AI SDK

Leverage the Vercel AI SDK

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

What is an AI Agent?

Required Package Installation

Using OpenAI

Using Anthropic

Using Both

Basic Configuration

Environment Variables

LLM Model Initialization

AgentConfig

Key Options

Additional Options

Practical Configuration Examples

1. Customer Support Chatbot

2. Creative Content Generation

3. Data Analysis Agent

4. Multimodal Agent

Environment-Specific Configuration

Development Environment

Production Environment

Cost Optimization

Model Selection

Token Limits

Precautions

Next Steps

Creating Agents

Using the AI SDK

​What is an AI Agent?

​Required Package Installation

​Using OpenAI

​Using Anthropic

​Using Both

​Basic Configuration

​Environment Variables

​LLM Model Initialization

​AgentConfig

​Key Options

​Additional Options

​Practical Configuration Examples

​1. Customer Support Chatbot

​2. Creative Content Generation

​3. Data Analysis Agent

​4. Multimodal Agent

​Environment-Specific Configuration

​Development Environment

​Production Environment

​Cost Optimization

​Model Selection

​Token Limits

​Precautions

​Next Steps

Creating Agents

Using the AI SDK

What is an AI Agent?

Required Package Installation

Using OpenAI

Using Anthropic

Using Both

Basic Configuration

Environment Variables

LLM Model Initialization

AgentConfig

Key Options

Additional Options

Practical Configuration Examples

1. Customer Support Chatbot

2. Creative Content Generation

3. Data Analysis Agent

4. Multimodal Agent

Environment-Specific Configuration

Development Environment

Production Environment

Cost Optimization

Model Selection

Token Limits

Precautions

Next Steps