Skip to content
Swift AI SDK

Overview

This page adapts the original AI SDK documentation: Agents Overview.

Agents

Section titled “Agents”

Agents are large language models (LLMs) that use tools in a loop to accomplish tasks.

These components work together:

  • LLMs process input and decide the next action
  • Tools extend capabilities beyond text generation (reading files, calling APIs, writing to databases)
  • Loop orchestrates execution through:
    • Context management - Maintaining conversation history and deciding what the model sees (input) at each step
    • Stopping conditions - Determining when the loop (task) is complete

Agent Class

Section titled “Agent Class”

The Agent class handles these three components. Here’s an agent that uses multiple tools in a loop to accomplish a task:

import SwiftAISDK
import OpenAIProvider


struct WeatherQuery: Codable, Sendable { let location: String }
struct FahrenheitWeather: Codable, Sendable {
  let location: String
  let temperature: Double
}


struct TemperatureFahrenheit: Codable, Sendable { let temperature: Double }
struct TemperatureCelsius: Codable, Sendable { let celsius: Double }


// Tool: get weather (Fahrenheit)
let weather = tool(
  description: "Get the weather in a location (in Fahrenheit)",
  inputSchema: WeatherQuery.self
) { query, _ in
  let temp = Double(72 + Int.random(in: -10...10))
  FahrenheitWeather(location: query.location, temperature: temp)
}


// Tool: F → C
let toCelsius = tool(
  description: "Convert temperature from Fahrenheit to Celsius",
  inputSchema: TemperatureFahrenheit.self
) { reading, _ in
  TemperatureCelsius(celsius: (reading.temperature - 32) * (5.0 / 9.0))
}


let agent = Agent<Never, Never>(settings: .init(
  model: .v3(openai("gpt-4o")),
  tools: [
    "weather": weather.eraseToTool(),
    "convertFahrenheitToCelsius": toCelsius.eraseToTool()
  ]
  // Default stopWhen is stepCountIs(20)
))


let result = try await agent.generate(prompt: .text("What is the weather in San Francisco in celsius?"))
print(result.text)  // final answer
print(result.steps) // steps taken by the agent

The agent automatically:

  1. Calls the weather tool to get the temperature in Fahrenheit
  2. Calls convertFahrenheitToCelsius to convert it
  3. Generates a final text response with the result

The Agent class handles the loop, context management, and stopping conditions.

Why Use the Agent Class?

Section titled “Why Use the Agent Class?”

The Agent class is the recommended approach for building agents with the AI SDK because it:

  • Reduces boilerplate - Manages loops and message arrays
  • Improves reusability - Define once, use throughout your application
  • Simplifies maintenance - Single place to update agent configuration

For most use cases, start with the Agent class. Use core functions (generateText, streamText) when you need explicit control over each step for complex structured workflows.

Structured Workflows

Section titled “Structured Workflows”

Agents are flexible and powerful, but non-deterministic. When you need reliable, repeatable outcomes with explicit control flow, use core functions with structured workflow patterns combining:

  • Conditional statements for explicit branching
  • Standard functions for reusable logic
  • Error handling for robustness
  • Explicit control flow for predictability

Explore workflow patterns to learn more about building structured, reliable systems.

Next Steps

Section titled “Next Steps”