SwiftAgent SDK

Create tools by conforming to the Tool protocol. Use Apple's @Generable macro on nested Arguments and Output structs to provide type-safe, schema-free definitions. SwiftAgent validates these types so the model can interact with Swift code without manual JSON parsing.

Note: When initializing a session with tools, pass them as variadic arguments (e.g., tools: ToolA(), ToolB()) rather than an array.

import FoundationModels
import OpenAISession

struct WeatherTool: Tool {
  let name = "get_weather"
  let description = "Get current weather for a location"

  @Generable
  struct Arguments {
    @Guide(description: "City name")
    let city: String

    @Guide(description: "Temperature unit")
    let unit: String
  }

  @Generable
  struct Output {
    let temperature: Double
    let condition: String
    let humidity: Int
  }

  func call(arguments: Arguments) async throws -> Output {
    return Output(
      temperature: 22.5,
      condition: "sunny",
      humidity: 65
    )
  }
}

let session = OpenAISession(
  tools: WeatherTool(),
  instructions: "You are a helpful assistant.",
  apiKey: "sk-...",
)

let response = try await session.respond(to: "What's the weather like in San Francisco?")
print(response.content)

To avoid working with raw GeneratedContent events, use the @SessionSchema macro to define a strongly typed schema for your session. This allows SwiftAgent to decode transcript entries into typed cases for tools, groundings, and structured outputs.

Key macros:

• @Tool: Links a tool implementation to decoded entries, providing typed arguments, outputs, and errors.
• @Grounding: Registers values injected into prompts (e.g., dates, search results) so they can be replayed alongside prompt text.
• @StructuredOutput: Binds a guided generation schema to its decoded result, supporting both partial streaming updates and final values.

Pass the schema instance to your session object (e.g., OpenAISession) during initialization.

@SessionSchema
struct SessionSchema {
  @Tool var weatherTool = WeatherTool()
  @Tool var calculatorTool = CalculatorTool()

  @Grounding(Date.self) var currentDate
  @Grounding(VectorSearchResult.self) var searchResults

  @StructuredOutput(WeatherReport.self) var weatherReport
  @StructuredOutput(CalculatorOutput .self) var calculatorOutput
}

let sessionSchema = SessionSchema()
let session = OpenAISession(
  schema: sessionSchema,
  instructions: "You are a helpful assistant.",
  apiKey: "sk-...",
)

SwiftAgent provides helpers to keep SwiftUI views stable during streaming.

For ToolRun objects:

• currentArguments: Returns a partially generated variant of the argument type with an isFinal flag. This is ideal for stable UI projections.
• finalArguments: Returns the fully validated payload once the model finalizes arguments.
• argumentsPhase: An enum (.partial, .final, or .none) used to branch logic based on streaming progress.

For structured outputs, use snapshot.currentContent for partial projections, and snapshot.contentPhase to check the streaming status.

struct WeatherToolRunView: View {
  let run: ToolRun<WeatherTool>

  var body: some View {
    // 1. Stable UI projection
    if let currentArguments = run.currentArguments {
      Text("City: \(currentArguments.city ?? "-")")
      if currentArguments.isFinal { Text("Locked in") }
    }

    // 2. Fully validated payload
    if let finalArguments = run.finalArguments {
      Text("Resolved: \(finalArguments.city)")
    }

    // 3. Phase-based branching
    switch run.argumentsPhase {
    case let .partial(partialArguments):
      Text("Awaiting... \(partialArguments.city ?? "-")")
    case let .final(finalArguments):
      Text("Final: \(finalArguments.city)")
    case .none:
      EmptyView()
    }
  }
}

To build an agent, you define a @SessionSchema struct that declares your tools, grounding data, and structured outputs. You then initialize a session (e.g., OpenAISession) with this schema and instructions. You interact with the agent using the .respond(to:groundingWith:generating:) method.

Key components of a schema include:

• @Tool: Declares tools the agent can call.
• @Grounding: Provides context or data to the agent.
• @StructuredOutput: Defines the shape of the final response.

After a response, you can use schema.resolve(session.transcript) to inspect the execution history, including tool runs and prompt sources.

import OpenAISession

@SessionSchema
struct CityExplorerSchema {
  @Tool var cityFacts = CityFactsTool()
  @Tool var reservation = ReservationTool()

  @Grounding(Date.self) var travelDate
  @Grounding([String].self) var mustVisitIdeas

  @StructuredOutput(ItinerarySummary.self) var itinerary
}

@MainActor
func planCopenhagenWeekend() async throws {
  let schema = CityExplorerSchema()
  let session = OpenAISession(
    schema: schema,
    instructions: "Design cinematic weekends. Call tools for local intel and reservations.",
    apiKey: "sk-..."
  )

  let response = try await session.respond(
    to: "Coffee, design, and dinner plans for two days in Copenhagen.",
    groundingWith: [
      .travelDate(Date(timeIntervalSinceNow: 86_400)),
      .mustVisitIdeas(["Coffee Collective, Nørrebro", "Designmuseum Denmark"])
    ],
    generating: \.itinerary
  )

  print(response.content.headline)

  // Accessing the transcript to see what happened
  for entry in try schema.resolve(session.transcript) {
    if case let .toolRun(.cityFacts(run)) = entry, let output = run.output {
      print("Local picks:", output)
    }
  }
}

You can develop and test agents without making live API calls using SimulatedSession. This requires defining a @SessionSchema and providing a SimulationConfiguration that contains mock generations (reasoning, tool runs, and responses).

To mock tools, implement the MockableTool protocol, which allows you to define mockArguments() and mockOutput() to simulate tool behavior.

import OpenAISession
import SimulatedSession

// 1. Create mockable tool wrappers
struct WeatherToolMock: MockableTool {
  var tool: WeatherTool

  func mockArguments() -> WeatherTool.Arguments {
    .init(city: "San Fransico", unit: "Celsius")
  }

  func mockOutput() async throws -> WeatherTool.Output {
    .init(
      temperature: 22.5,
      condition: "sunny",
      humidity: 65
    )
  }
}

// 2. Define the session schema
@SessionSchema
struct SessionSchema {
  @Tool var weatherTool = WeatherTool()
}

// 3. Configure the simulation
let sessionSchema = SessionSchema()
let configuration = SimulationConfiguration(defaultGenerations: [
  .reasoning(summary: "Simulated Reasoning"),
  .toolRun(tool: WeatherToolMock(tool: WeatherTool())),
  .response(text: "It's a beautiful sunny day in San Francisco with 22.5°C!"),
])

// 4. Initialize and use the simulated session
let session = SimulatedSession(
  schema: sessionSchema,
  instructions: "You are a helpful assistant.",
  configuration: configuration,
)

let response = try await session.respond(to: "What's the weather like in San Francisco?")
print(response.content) // "It's a beautiful sunny day in San Francisco with 22.5°C!"