Function Calling Pattern | Bootspring Docs

Enable AI models to use tools and execute functions to interact with external systems and data.

Overview#

Function calling (also called tool use) allows AI models to request the execution of predefined functions. The model decides which functions to call based on the conversation, and your application executes them and returns results.

When to use:

AI agents with capabilities
Database queries via natural language
External API integration
Multi-step reasoning tasks
Automating workflows

Key features:

Tool definition with JSON Schema
Tool execution handling
Multi-tool conversations
Iterative tool loops
Error handling

Code Example#

Tool Definition#

// lib/ai/tools.ts
import { anthropic } from '@/lib/anthropic'

const tools = [
  {
    name: 'get_weather',
    description: 'Get the current weather for a location',
    input_schema: {
      type: 'object',
      properties: {
        location: {
          type: 'string',
          description: 'City and state, e.g., San Francisco, CA'
        }
      },
      required: ['location']
    }
  },
  {
    name: 'search_database',
    description: 'Search the product database',
    input_schema: {
      type: 'object',
      properties: {
        query: { type: 'string' },
        limit: { type: 'number', default: 10 }
      },
      required: ['query']
    }
  }
]

Tool Execution#

// lib/ai/tools.ts
import { prisma } from '@/lib/db'

async function executeTool(name: string, input: any) {
  switch (name) {
    case 'get_weather':
      // Call weather API
      const weatherResponse = await fetch(
        `https://api.weather.com/v1/current?location=${encodeURIComponent(input.location)}`
      )
      const weather = await weatherResponse.json()
      return JSON.stringify({
        temperature: weather.temp,
        condition: weather.condition
      })

    case 'search_database':
      // Search database
      const products = await prisma.product.findMany({
        where: {
          OR: [
            { name: { contains: input.query, mode: 'insensitive' } },
            { description: { contains: input.query, mode: 'insensitive' } }
          ]
        },
        take: input.limit ?? 10
      })
      return JSON.stringify(products)

    default:
      throw new Error(`Unknown tool: ${name}`)
  }
}

Chat with Tools#

// lib/ai/tools.ts
export async function chatWithTools(prompt: string) {
  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    tools,
    messages: [{ role: 'user', content: prompt }]
  })

  // Check for tool use
  for (const block of response.content) {
    if (block.type === 'tool_use') {
      const result = await executeTool(block.name, block.input)

      // Continue conversation with tool result
      const followUp = await anthropic.messages.create({
        model: 'claude-sonnet-4-20250514',
        max_tokens: 1024,
        messages: [
          { role: 'user', content: prompt },
          { role: 'assistant', content: response.content },
          {
            role: 'user',
            content: [
              {
                type: 'tool_result',
                tool_use_id: block.id,
                content: result
              }
            ]
          }
        ]
      })

      return followUp
    }
  }

  return response
}

Multi-Tool Loop#

// lib/ai/tools.ts
export async function chatWithToolLoop(
  prompt: string,
  maxIterations = 5
) {
  let messages: any[] = [{ role: 'user', content: prompt }]
  let iteration = 0

  while (iteration < maxIterations) {
    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      tools,
      messages
    })

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

    // Process tool uses
    const toolResults = []
    for (const block of response.content) {
      if (block.type === 'tool_use') {
        try {
          const result = await executeTool(block.name, block.input)
          toolResults.push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: result
          })
        } catch (error) {
          toolResults.push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
            is_error: true
          })
        }
      }
    }

    // Add to conversation
    messages.push({ role: 'assistant', content: response.content })
    messages.push({ role: 'user', content: toolResults })

    iteration++
  }

  throw new Error('Max iterations reached')
}

API Route with Tools#

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { chatWithToolLoop } from '@/lib/ai/tools'
import { auth } from '@/lib/auth'

export async function POST(request: NextRequest) {
  const { userId } = await auth()
  if (!userId) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { message } = await request.json()

  try {
    const result = await chatWithToolLoop(message)
    return NextResponse.json(result)
  } catch (error) {
    console.error('Chat error:', error)
    return NextResponse.json(
      { error: 'Failed to process request' },
      { status: 500 }
    )
  }
}

Typed Tool Definitions#

// lib/ai/tools/definitions.ts
import { z } from 'zod'

// Define tool schemas with Zod
const WeatherInput = z.object({
  location: z.string().describe('City and state, e.g., San Francisco, CA'),
  units: z.enum(['celsius', 'fahrenheit']).default('fahrenheit')
})

const SearchInput = z.object({
  query: z.string().describe('Search query'),
  category: z.string().optional().describe('Filter by category'),
  limit: z.number().min(1).max(50).default(10)
})

// Type-safe tool interface
interface Tool<T extends z.ZodType> {
  name: string
  description: string
  schema: T
  execute: (input: z.infer<T>) => Promise<string>
}

// Create tool with type inference
function createTool<T extends z.ZodType>(tool: Tool<T>) {
  return {
    name: tool.name,
    description: tool.description,
    input_schema: zodToJsonSchema(tool.schema),
    execute: async (input: unknown) => {
      const validated = tool.schema.parse(input)
      return tool.execute(validated)
    }
  }
}

// Usage
const weatherTool = createTool({
  name: 'get_weather',
  description: 'Get current weather for a location',
  schema: WeatherInput,
  execute: async (input) => {
    // input is typed as { location: string, units: 'celsius' | 'fahrenheit' }
    const data = await fetchWeather(input.location, input.units)
    return JSON.stringify(data)
  }
})

Usage Instructions#

Define tools: Create tool objects with name, description, and JSON Schema
Implement executors: Write functions that handle each tool
Send request: Include tools in the API call
Check for tool use: Look for tool_use blocks in the response
Execute and return: Run the tool and send results back
Continue or complete: Let the model decide if more tools are needed

Best Practices#

Clear descriptions - Write detailed tool descriptions to help the model choose correctly
Validate inputs - Use Zod or JSON Schema validation before executing
Handle errors - Return error messages as tool results, not exceptions
Set iteration limits - Prevent infinite loops with maxIterations
Log tool calls - Track what tools are being called for debugging
Keep tools focused - Each tool should do one thing well
Use meaningful names - Tool names should clearly indicate their purpose
Document parameters - Add descriptions to each parameter in the schema

AI Agents - Build autonomous agents with tools
Claude API - Basic Claude integration
Streaming - Stream tool-using responses