AI Agents Pattern | Bootspring Docs

Build autonomous AI agents that can reason, use tools, and complete multi-step tasks.

Overview#

AI agents are systems that can break down complex tasks, decide which tools to use, and iterate until they achieve a goal. They combine LLM reasoning with tool execution to handle tasks that require multiple steps or external interactions.

When to use:

Autonomous task completion
Research and information gathering
Multi-step workflows
Tool orchestration
Complex reasoning tasks

Key features:

Agent loop with tool execution
Multiple tool integration
Streaming agent responses
Error handling and recovery
Maximum iteration limits

Code Example#

Basic Agent Loop#

// lib/agents/base.ts
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic()

interface Tool {
  name: string
  description: string
  input_schema: object
  execute: (input: any) => Promise<string>
}

export async function runAgent(
  systemPrompt: string,
  userMessage: string,
  tools: Tool[],
  maxIterations = 10
) {
  const messages: Anthropic.MessageParam[] = [
    { role: 'user', content: userMessage }
  ]

  const anthropicTools = tools.map(t => ({
    name: t.name,
    description: t.description,
    input_schema: t.input_schema
  }))

  for (let i = 0; i < maxIterations; i++) {
    const response = await client.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 4096,
      system: systemPrompt,
      tools: anthropicTools,
      messages
    })

    // Check if we're done
    if (response.stop_reason === 'end_turn') {
      const textBlock = response.content.find(b => b.type === 'text')
      return textBlock?.text ?? ''
    }

    // Process tool uses
    const toolUses = response.content.filter(b => b.type === 'tool_use')

    if (toolUses.length === 0) {
      const textBlock = response.content.find(b => b.type === 'text')
      return textBlock?.text ?? ''
    }

    // Add assistant message
    messages.push({ role: 'assistant', content: response.content })

    // Execute tools and add results
    const toolResults = await Promise.all(
      toolUses.map(async (toolUse) => {
        const tool = tools.find(t => t.name === toolUse.name)
        if (!tool) {
          return {
            type: 'tool_result' as const,
            tool_use_id: toolUse.id,
            content: `Error: Tool ${toolUse.name} not found`
          }
        }

        try {
          const result = await tool.execute(toolUse.input)
          return {
            type: 'tool_result' as const,
            tool_use_id: toolUse.id,
            content: result
          }
        } catch (error) {
          return {
            type: 'tool_result' as const,
            tool_use_id: toolUse.id,
            content: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        }
      })
    )

    messages.push({ role: 'user', content: toolResults })
  }

  throw new Error('Max iterations reached')
}

Research Agent#

// lib/agents/research.ts
import { runAgent } from './base'

const webSearchTool = {
  name: 'web_search',
  description: 'Search the web for information',
  input_schema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'The search query' }
    },
    required: ['query']
  },
  execute: async (input: { query: string }) => {
    const response = await fetch(
      `https://api.search.com/search?q=${encodeURIComponent(input.query)}`
    )
    const data = await response.json()
    return JSON.stringify(data.results.slice(0, 5))
  }
}

const readUrlTool = {
  name: 'read_url',
  description: 'Read the contents of a URL',
  input_schema: {
    type: 'object',
    properties: {
      url: { type: 'string', description: 'The URL to read' }
    },
    required: ['url']
  },
  execute: async (input: { url: string }) => {
    const response = await fetch(input.url)
    const html = await response.text()
    // Extract text from HTML (simplified)
    return html.replace(/<[^>]*>/g, '').slice(0, 5000)
  }
}

export async function researchTopic(topic: string) {
  const systemPrompt = `You are a research assistant. Your job is to research topics thoroughly using web search and URL reading tools. Provide comprehensive, well-sourced information.`

  return runAgent(
    systemPrompt,
    `Research the following topic and provide a detailed summary: ${topic}`,
    [webSearchTool, readUrlTool]
  )
}

Task Execution Agent#

// lib/agents/task.ts
import { runAgent } from './base'
import { prisma } from '@/lib/db'

const createTaskTool = {
  name: 'create_task',
  description: 'Create a new task in the system',
  input_schema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      description: { type: 'string' },
      priority: { type: 'string', enum: ['low', 'medium', 'high'] },
      dueDate: { type: 'string', description: 'ISO date string' }
    },
    required: ['title']
  },
  execute: async (input: any) => {
    const task = await prisma.task.create({
      data: {
        title: input.title,
        description: input.description,
        priority: input.priority ?? 'medium',
        dueDate: input.dueDate ? new Date(input.dueDate) : null
      }
    })
    return `Created task: ${task.id}`
  }
}

const listTasksTool = {
  name: 'list_tasks',
  description: 'List all tasks',
  input_schema: {
    type: 'object',
    properties: {
      status: { type: 'string', enum: ['pending', 'completed', 'all'] }
    }
  },
  execute: async (input: any) => {
    const where = input.status === 'all' ? {} : { status: input.status }
    const tasks = await prisma.task.findMany({ where })
    return JSON.stringify(tasks)
  }
}

export async function processTaskRequest(userRequest: string) {
  const systemPrompt = `You are a task management assistant. Help users create, list, and manage their tasks using the available tools.`

  return runAgent(
    systemPrompt,
    userRequest,
    [createTaskTool, listTasksTool]
  )
}

Streaming Agent#

// lib/agents/streaming.ts
import Anthropic from '@anthropic-ai/sdk'

interface Tool {
  name: string
  description: string
  input_schema: object
  execute: (input: any) => Promise<string>
}

export async function* streamingAgent(
  systemPrompt: string,
  userMessage: string,
  tools: Tool[]
) {
  const client = new Anthropic()
  const messages: Anthropic.MessageParam[] = [
    { role: 'user', content: userMessage }
  ]

  while (true) {
    const stream = client.messages.stream({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 4096,
      system: systemPrompt,
      tools: tools.map(t => ({
        name: t.name,
        description: t.description,
        input_schema: t.input_schema
      })),
      messages
    })

    let currentToolUse: any = null

    for await (const event of stream) {
      if (event.type === 'content_block_start' && event.content_block.type === 'text') {
        yield { type: 'text_start' }
      }

      if (event.type === 'content_block_delta') {
        if (event.delta.type === 'text_delta') {
          yield { type: 'text', content: event.delta.text }
        }
      }

      if (event.type === 'content_block_start' && event.content_block.type === 'tool_use') {
        currentToolUse = event.content_block
        yield { type: 'tool_start', name: currentToolUse.name }
      }
    }

    const finalMessage = await stream.finalMessage()

    if (finalMessage.stop_reason === 'end_turn') {
      yield { type: 'done' }
      break
    }

    // Handle tool execution and continue loop...
    // Add tool results to messages and continue
  }
}

Usage Instructions#

Define tools: Create tool objects with name, description, schema, and execute function
Set up the agent: Initialize with a system prompt and available tools
Run the loop: Let the agent decide which tools to use
Handle results: Process tool outputs and continue until complete
Set limits: Always set a maximum iteration count

Best Practices#

Clear tool descriptions - Help the AI understand when to use each tool
Set iteration limits - Prevent runaway agents with maxIterations
Handle errors gracefully - Return error messages as tool results
Log tool calls - Track what the agent is doing for debugging
Use specific system prompts - Guide the agent's behavior
Implement timeouts - Set time limits on tool execution
Validate tool inputs - Check inputs before executing
Stream for long tasks - Show progress during multi-step operations

Function Calling - Tool definition and execution
Streaming - Real-time response streaming
Claude API - Basic Claude integration