SwiftAgent

https://github.com/swiftedmind/swiftagent
Admin
SwiftAgent is a native Swift SDK for building autonomous AI agents, offering a clean and intuitive...
Tokens:93,390
Snippets:606
Trust Score:8.4
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Minimum Working Example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/index.md

A minimal example showing how to create an OpenAISession and send a response request.

```APIDOC
## OpenAISession - respond

### Description
Creates an OpenAISession with instructions and an API key, then sends a user message and prints the response content.

### Method
Swift method call

### Endpoint
N/A (SDK method)

### Parameters
- **instructions** (String) - Required - System instructions for the assistant.
- **apiKey** (String) - Required - API key for authentication.
- **message** (String) - Required - The user message to respond to.

### Request Example
```swift
import OpenAISession

let session = OpenAISession(
  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)
```

### Response
#### Success Response
- **content** (String) - The response content from the assistant.
```

--------------------------------

### Example: Structured output with thinking

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicsession.md

Shows how to use a schema, custom configuration, and generation options to get structured output with thinking.

```APIDOC
## Example: Structured output with thinking

### Description
Demonstrates structured output generation with thinking using a schema and custom configuration.

### Code
```swift
import AnthropicSession

struct WeatherReport: StructuredOutput {
  static let name = "weatherReport"

  @Generable
  struct Schema {
    let temperature: Double
    let condition: String
  }
}

let session = AnthropicSession(
  schema: SessionSchema(),
  instructions: "You are a helpful assistant.",
  configuration: .proxy(through: URL(string: "https://proxy.example.com")!)
)

let options = AnthropicGenerationOptions(
  maxOutputTokens: 2048,
  thinking: .init(budgetTokens: 1024),
)

do {
  let report = try await session.withAuthorization(token: turnToken) {
    try await session.respond(
      to: "Weather in Lisbon?",
      generating: WeatherReport.self,
      options: options,
    )
  }
  print(report.content.condition)
} catch let error as GenerationError {
  print("Generation failed: \(error.errorCode)")
}
```
```

--------------------------------

### Proxy configuration example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicconfiguration.md

Shows how to create a proxy configuration and use it with an AnthropicSession. The withAuthorization call installs the token context required for the proxy to set the Authorization header.

```swift
let configuration = AnthropicConfiguration.proxy(
  through: URL(string: "https://api.your-backend.com")!
)
let session = AnthropicSession(
  instructions: "You are a helpful assistant.",
  configuration: configuration
)
let response = try await session.withAuthorization(token: turnToken) {
  try await session.respond(to: "Hello")
}
```

--------------------------------

### Example: Recording HTTP fixtures with OpenAISession

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/httpreplayrecorder.md

Shows how to set up an HTTPReplayRecorder with an OpenAI session, record a response, and print the fixture snippet. The example uses includeHeaders: true and prettyPrintJSON: true.

```swift
import OpenAISession
import SwiftAgent

let recorder = HTTPReplayRecorder(
  options: .init(includeRequests: false, includeHeaders: true, prettyPrintJSON: true)
)

var interceptors = HTTPClientInterceptors(
  prepareRequest: { request in
    request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
  }
)
interceptors = interceptors.recording(to: recorder)

let configuration = HTTPClientConfiguration(
  baseURL: URL(string: "https://api.openai.com")!,
  jsonEncoder: JSONEncoder(),
  jsonDecoder: JSONDecoder(),
  interceptors: interceptors
)

let httpClient = URLSessionHTTPClient(configuration: configuration)
let session = OpenAISession(
  instructions: "You are a helpful assistant.",
  configuration: OpenAIConfiguration(httpClient: httpClient)
)

_ = try await session.respond(to: "Hello!")

await recorder.printSwiftFixtureSnippet()
```

--------------------------------

### Direct configuration example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicconfiguration.md

Shows how to create a direct configuration and an AnthropicSession. The betaHeaders parameter enables beta features like prompt caching.

```swift
let configuration = AnthropicConfiguration.direct(
  apiKey: "sk-ant-...",
  apiVersion: "2023-06-01",
  betaHeaders: ["prompt-caching-2024-07-31"]
)
let session = AnthropicSession(
  instructions: "You are a helpful assistant.",
  configuration: configuration
)
```

--------------------------------

### Complete example with session and response

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/sessionschema-macro.md

Demonstrates a full usage: defining a schema, creating a session, and responding with a structured output and grounding. Shows how to use the generated key paths and grounding enum.

```swift
@SessionSchema
struct SessionSchema {
  @Tool var weatherTool = WeatherTool()
  @StructuredOutput(WeatherReport.self) var weatherReport
  @Grounding(Date.self) var currentDate
}

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

let response = try await session.respond(
  to: "What's the weather like in San Francisco?",
  generating: \.weatherReport,
  groundingWith: [.currentDate(Date())],
) { input, sources in
  PromptTag("context") {
    for source in sources {
      if case let .currentDate(date) = source {
        "Today is \(date)."
      }
    }
  }
  PromptTag("user-query") { input }
}
```

--------------------------------

### Example: building a prompt with PromptBuilder

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/promptbuilder.md

Shows how to compose a prompt using the builder DSL with a string, a PromptSection, and a PromptTag, then send it to a session and print the response.

```swift
let prompt = Prompt {
  "You are a concise assistant."
  PromptSection("Instructions") {
    "Be concise"
    PromptTag("formatting", attributes: ["style": "bullets"]) {
      "Answer in three bullet points."
    }
  }
}

let response = try await session.respond(to: prompt)
print(response.content)
```

--------------------------------

### Enable Logging with SwiftAgentConfiguration

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Enable comprehensive logging and full request/response network logging for debugging. Network logging is very verbose but helpful. The example also shows the log output format including agent start, tool call, tool output, and finish markers.

```swift
// Enable comprehensive logging
SwiftAgentConfiguration.setLoggingEnabled(true)

// Enable full request/response network logging (very verbose but helpful for debugging)
SwiftAgentConfiguration.setNetworkLoggingEnabled(true)

// Logs show:
// 🟢 Agent start — model=gpt-5 | tools=weather, calculator
// 🛠️ Tool call — weather [abc123]
// 📤 Tool output — weather [abc123]
// ✅ Finished
```

--------------------------------

### Production example using proxy(through:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaiconfiguration.md

Shows the recommended production pattern: create a proxy configuration, create an OpenAISession, issue a turn token, and wrap the response call in withAuthorization. The proxy must forward /v1/responses to OpenAI with the secret API key.

```swift
let configuration = OpenAIConfiguration.proxy(through: URL(string: "https://api.your-backend.com")!)
let session = OpenAISession(
  instructions: "You are a helpful assistant.",
  configuration: configuration
)

let token = try await backend.issueTurnToken(for: userId)
let response = try await session.withAuthorization(token: token) {
  try await session.respond(to: "Summarize yesterday's sales numbers.")
}
```

--------------------------------

### OpenAIGenerationOptions Usage Example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaigenerationoptions.md

An example showing how to create OpenAIGenerationOptions and use it with a session response.

```APIDOC
## Example

```swift
import OpenAISession

let options = OpenAIGenerationOptions(
  maxOutputTokens: 1000,
  temperature: 0.7,
)

let response = try await session.respond(
  to: "What's the weather like in San Francisco?",
  using: .gpt5,
  options: options,
)
```
```

--------------------------------

### Example: Basic text response

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicsession.md

Shows how to create a session and request a basic text response.

```APIDOC
## Example: Basic text response

### Description
Creates a session with instructions and an API key, then responds to a prompt.

### Code
```swift
import AnthropicSession

let session = AnthropicSession(
  instructions: "You are a helpful assistant.",
  apiKey: "sk-ant-...",
)

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

--------------------------------

### Structured output with thinking example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicsession.md

Example of using AnthropicSession with a schema, custom configuration, and AnthropicGenerationOptions to generate structured output with thinking. Shows error handling for GenerationError.

```swift
import AnthropicSession

struct WeatherReport: StructuredOutput {
  static let name = "weatherReport"

  @Generable
  struct Schema {
    let temperature: Double
    let condition: String
  }
}

let session = AnthropicSession(
  schema: SessionSchema(),
  instructions: "You are a helpful assistant.",
  configuration: .proxy(through: URL(string: "https://proxy.example.com")!)
)

let options = AnthropicGenerationOptions(
  maxOutputTokens: 2048,
  thinking: .init(budgetTokens: 1024),
)

do {
  let report = try await session.withAuthorization(token: turnToken) {
    try await session.respond(
      to: "Weather in Lisbon?",
      generating: WeatherReport.self,
      options: options,
    )
  }
  print(report.content.condition)
} catch let error as GenerationError {
  print("Generation failed: \(error.errorCode)")
}
```

--------------------------------

### HTTP client configuration and send example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/httpclient.md

Shows how to configure a URLSessionHTTPClient with a base URL and an interceptor that adds an Authorization header, then send a POST request and decode the response.

```swift
let configuration = HTTPClientConfiguration(
  baseURL: URL(string: "https://api.openai.com")!,
  interceptors: HTTPClientInterceptors(
    prepareRequest: { request in
      request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
    }
  )
)
let httpClient = URLSessionHTTPClient(configuration: configuration)

let response: ResponseObject = try await httpClient.send(
  path: "/v1/responses",
  method: .post,
  queryItems: nil,
  headers: nil,
  body: requestBody,
  responseType: ResponseObject.self,
)
```

--------------------------------

### WeatherToolMock example implementation

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/simulationconfiguration.md

Example implementation of MockableTool for a WeatherTool. It provides mock arguments for San Francisco with Celsius units and a mock output with temperature, condition, and humidity.

```swift
struct WeatherToolMock: MockableTool {
  var tool: WeatherTool

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

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

--------------------------------

### Run AgentRecorder CLI with OpenAI API key

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/configuration.md

Example bash invocation from the README that sets the OPENAI_API_KEY environment variable and runs the AgentRecorder binary with the OpenAI provider and a specific scenario. The binary path is under ./.tmp/DerivedData/Build/Products/Debug/.

```bash
OPENAI_API_KEY=sk-... ./.tmp/DerivedData/Build/Products/Debug/AgentRecorder \
  --provider openai --scenario openai/streaming-tool-calls/weather
```

--------------------------------

### Using AgentResponse with respond

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/agentresponsesnapshot.md

Example of using the respond method to get an AgentResponse and accessing its content, token usage, and transcript count.

```swift
let response = try await session.respond(to: "What is 2 + 2?")
print("Answer: \(response.content)")
print("Used \(response.tokenUsage?.totalTokens ?? 0) tokens")
print("Added \(response.transcript.count) transcript entries")
```

--------------------------------

### Basic text response example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicsession.md

Example of creating an AnthropicSession with a direct API key and requesting a basic text response using the respond(to:) method.

```swift
import AnthropicSession

let session = AnthropicSession(
  instructions: "You are a helpful assistant.",
  apiKey: "sk-ant-...",
)

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

--------------------------------

### URLSessionHTTPClient Example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/httpclient.md

An example demonstrating how to configure and use URLSessionHTTPClient to send an HTTP request with a custom interceptor for authentication.

```APIDOC
## URLSessionHTTPClient Example

### Description
Demonstrates creating an HTTP client with a base URL and an interceptor that adds an Authorization header, then sending a POST request.

### Example
```swift
let configuration = HTTPClientConfiguration(
  baseURL: URL(string: "https://api.openai.com")!,
  interceptors: HTTPClientInterceptors(
    prepareRequest: { request in
      request.setValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
    }
  )
)
let httpClient = URLSessionHTTPClient(configuration: configuration)

let response: ResponseObject = try await httpClient.send(
  path: "/v1/responses",
  method: .post,
  queryItems: nil,
  headers: nil,
  body: requestBody,
  responseType: ResponseObject.self,
)
```
```

--------------------------------

### Example: Handling tool run results and rejections

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/toolrun.md

Shows how to iterate over resolved transcript entries, extract a `.toolRun(.cityFacts(run))` case, and access streaming-stable projections, final arguments, output, and rejection details.

```swift
for entry in try sessionSchema.resolve(session.transcript) {
  if case let .toolRun(.cityFacts(run)) = entry {
    // Streaming-stable projection
    if let current = run.currentArguments {
      print(current.city ?? "-", current.isFinal)
    }
    // Fully validated arguments
    if let arguments = run.finalArguments {
      print("Resolved:", arguments.city)
    }
    // Output or rejection
    if let output = run.output {
      print("Output:", output)
    } else if let rejection = run.rejection {
      print("Rejected:", rejection.reason, rejection.details)
    }
  }
}
```

--------------------------------

### Create an OpenAISession and respond

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Creates an OpenAISession with instructions and an API key, then calls respond to get a single-turn answer. The session tracks conversation state automatically.

```swift
import OpenAISession

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

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

// Process response
print(response.content)
```

--------------------------------

### SimulatedSession usage example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/simulatedsession.md

Example of creating a SimulatedSession with a schema, mock tool, and scripted generations. It responds to a prompt and prints the simulated response. If generations are exhausted, it throws SimulationConfigurationError.missingGenerations.

```swift
import OpenAISession
import SimulatedSession

struct WeatherToolMock: MockableTool {
  var tool: WeatherTool

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

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

@SessionSchema
struct SessionSchema {
  @Tool var weatherTool = WeatherTool()
}

let schema = 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!"),
])

let session = SimulatedSession(
  schema: schema,
  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!"
```

--------------------------------

### withAuthorization

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/languagemodelprovider.md

Runs `perform` with a task-local bearer-token authorization context installed so every internal network request for the turn inherits the same token. Used with `*Configuration.proxy(through:)`.

```APIDOC
## withAuthorization

### Description
Runs `perform` with a task-local bearer-token authorization context installed so every internal network request for the turn (reasoning, tool calls, final answer) inherits the same token. Used with `*Configuration.proxy(through:)`.

### Method
Swift function

### Signature
```swift
@discardableResult
nonisolated func withAuthorization<T>(
  token: String?,
  refresh: (@Sendable () async throws -> String)? = nil,
  perform: @Sendable () async throws -> T,
) async rethrows -> T
```

### Parameters
- **token** (`String?`) - Required - Bearer token to authorize the turn. If `nil`, `perform` runs with no context.
- **refresh** (`(@Sendable () async throws -> String)?`) - Optional - Default: `nil` - Closure returning a fresh token when a proxy answers `401 Unauthorized`.
- **perform** (`@Sendable () async throws -> T`) - Required - The async work (typically a `respond` / `streamResponse` call).

### Returns
- `T` - The result of `perform`.

### Precondition
If `token` is non-nil it must not be empty, otherwise a `precondition` failure is raised.

### Throws
Rethrows whatever `perform` (or the network layer) throws.

### Example
```swift
let turnToken = try await backend.issueTurnToken(for: userId)
let response = try await session.withAuthorization(token: turnToken) {
  try await session.respond(to: "Summarize yesterday's sales numbers.")
}
```
```

--------------------------------

### proxy(through:apiVersion:betaHeaders:) factory method

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicconfiguration.md

Creates a configuration that routes requests through a proxy backend. The SDK appends /v1/messages to the base URL. Requires an AuthorizationContext to be installed via withAuthorization; otherwise a preconditionFailure is raised.

```swift
public static func proxy(
  through baseURL: URL,
  apiVersion: String = "2023-06-01",
  betaHeaders: [String]? = nil,
) -> AnthropicConfiguration
```

--------------------------------

### init(schema:instructions:apiKey:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaisession.md

Initializes an OpenAISession with a schema, instructions, and a direct API key. The schema enumerates tools, structured outputs, and groundings.

```APIDOC
## init(schema:instructions:apiKey:)

### Description
Initializes an OpenAISession with a schema, instructions, and a direct API key. The schema enumerates tools, structured outputs, and groundings.

### Method
Initializer

### Signature
```swift
public init(
  schema: SessionSchema,
  instructions: String,
  apiKey: String,
)
```

### Parameters
- **schema** (`SessionSchema`) - Required - Schema enumerating tools, structured outputs and groundings.
- **instructions** (`String`) - Required - Default system instructions.
- **apiKey** (`String`) - Required - OpenAI API key for direct authentication.
```

--------------------------------

### init(schema:instructions:configuration:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaisession.md

Initializes an OpenAISession with a schema, instructions, and a custom OpenAIConfiguration for routing and authentication.

```APIDOC
## init(schema:instructions:configuration:)

### Description
Initializes an OpenAISession with a schema, instructions, and a custom OpenAIConfiguration for routing and authentication.

### Method
Initializer

### Signature
```swift
public init(
  schema: SessionSchema,
  instructions: String,
  configuration: OpenAIConfiguration,
)
```

### Parameters
- **schema** (`SessionSchema`) - Required - Schema backing the session.
- **instructions** (`String`) - Required - Default system instructions.
- **configuration** (`OpenAIConfiguration`) - Required - Routing/auth configuration (e.g. `.proxy(through:)`).
```

--------------------------------

### StructuredOutputSnapshot usage example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/structuredoutputsnapshot.md

Example of defining a WeatherReport schema and streaming a response, then resolving the transcript to access structured segments.

```swift
struct WeatherReport: StructuredOutput {
  static let name = "weatherReport"

  @Generable
  struct Schema {
    let temperature: Double
    let condition: String
  }
}

for try await snapshot in session.streamResponse(
  to: "Weather in Lisbon?",
  generating: WeatherReport.self,
) {
  if let current = snapshot.content {
    print(current.temperature as Any, current.condition as Any)
  }
}

// Decoded resolved transcript access:
for entry in try sessionSchema.resolve(session.transcript) {
  if case let .response(response) = entry,
     case let .weatherReport(report) = response.structuredSegments[0].content {
    switch report.contentPhase {
    case let .partial(partial):
      print("Partial:", partial.temperature as Any)
    case let .final(final):
      print("Final:", final.temperature)
    case nil:
      print("Not yet available")
    }
  }
}
```

--------------------------------

### init(tools:instructions:apiKey:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaisession.md

Initializes an OpenAISession with a variadic list of tools and a direct API key. The session schema is set to NoSchema.

```APIDOC
## init(tools:instructions:apiKey:)

### Description
Initializes an OpenAISession with a variadic list of tools and a direct API key. The session schema is set to NoSchema.

### Method
Initializer

### Signature
```swift
public init<each ToolType>(
  tools: repeat each ToolType,
  instructions: String = "",
  apiKey: String,
) where
  SessionSchema == NoSchema,
  repeat (each ToolType): FoundationModels.Tool,
  repeat (each ToolType).Arguments: Generable,
  repeat (each ToolType).Output: Generable
```

### Parameters
- **tools** (`repeat each ToolType`, variadic, each a `FoundationModels.Tool` with `Generable` Arguments/Output) - Optional - Tools available to the agent.
- **instructions** (`String`) - Optional, default `""` - Default system instructions for every turn.
- **apiKey** (`String`) - Required - OpenAI API key for direct authentication.

### Notes
- Unlike Apple's `LanguageModelSession`, `OpenAISession` takes `tools` as variadic arguments — pass `tools: WeatherTool(), OtherTool()` (no array literal).
```

--------------------------------

### Build SDK with xcodebuild

Source: https://github.com/swiftedmind/swiftagent/blob/main/AGENTS.md

Builds the ExampleApp scheme for the iOS Simulator. Use this to verify the SDK compiles after code changes.

```bash
xcodebuild -workspace SwiftAgent.xcworkspace -scheme ExampleApp -destination "platform=iOS Simulator,name=iPhone 17 Pro,OS=latest" build -quiet
```

--------------------------------

### init(tools:instructions:configuration:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaisession.md

Initializes an OpenAISession with a variadic list of tools and a custom OpenAIConfiguration. The session schema is set to NoSchema.

```APIDOC
## init(tools:instructions:configuration:)

### Description
Initializes an OpenAISession with a variadic list of tools and a custom OpenAIConfiguration. The session schema is set to NoSchema.

### Method
Initializer

### Signature
```swift
public init<each ToolType>(
  tools: repeat each ToolType,
  instructions: String = "",
  configuration: OpenAIConfiguration,
) where SessionSchema == NoSchema,
  repeat (each ToolType): FoundationModels.Tool,
  repeat (each ToolType).Arguments: Generable,
  repeat (each ToolType).Output: Generable
```

### Parameters
- **tools** (`repeat each ToolType`, variadic) - Optional - Tools available to the agent.
- **instructions** (`String`) - Optional, default `""` - Default system instructions.
- **configuration** (`OpenAIConfiguration`) - Required - Routing/auth configuration.

### Notes
- Unlike Apple's `LanguageModelSession`, `OpenAISession` takes `tools` as variadic arguments — pass `tools: WeatherTool(), OtherTool()` (no array literal).
```

--------------------------------

### Catching GenerationError

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/errors.md

Example of catching GenerationError thrown by session.respond(to:) and handling its various cases.

```APIDOC
## Catching GenerationError

### Description
Demonstrates how to catch and handle `GenerationError` thrown by `session.respond(to:)`.

### Usage
```swift
do {
  let response = try await session.respond(to: "Hello")
} catch let error as GenerationError {
  print(error.errorCode)          // machine-readable code
  print(error.localizedDescription)

  switch error {
  case let .toolExecutionFailed(context):
    print("Tool \(context.toolName) failed: \(context.underlyingError)")
  case let .providerError(context):
    print("Provider error \(context.statusCode ?? -1): \(context.message)")
  case .cancelled:
    print("Cancelled")
  default:
    break
  }
}
```

### Notes
- `GenerationError` is also produced from networking errors by package-level mappers: `fromRequest`, `fromStream`, `fromHTTP`, `fromParsing`, and `isCancellation`.
- Providers add their own `from(_:)` mappers (see OpenAI Adapter / Anthropic Adapter).
```

--------------------------------

### init(tools:instructions:configuration:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/simulatedsession.md

Initializes a SimulatedSession with a variadic list of tools, optional instructions, and a required SimulationConfiguration. This initializer is available when SessionSchema is NoSchema and all tools conform to the required protocols.

```APIDOC
## init(tools:instructions:configuration:)

### Description
Initializes a SimulatedSession with a variadic list of tools, optional instructions, and a required SimulationConfiguration. This initializer is available when SessionSchema is NoSchema and all tools conform to the required protocols.

### Method
Initializer

### Signature
```swift
public init<each ToolType>(
  tools: repeat each ToolType,
  instructions: String = "",
  configuration: SimulationConfiguration,
) where
  SessionSchema == NoSchema,
  repeat (each ToolType): FoundationModels.Tool,
  repeat (each ToolType).Arguments: Generable,
  repeat (each ToolType).Output: Generable
```

### Parameters
- **tools** (variadic) - Optional - Tools the simulated agent can "call".
- **instructions** (String) - Optional - Default system instructions. Defaults to `""`.
- **configuration** (SimulationConfiguration) - Required - Scripted generations, delay, token usage.

### Example
```swift
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!"),
])

let session = SimulatedSession(
  tools: WeatherTool(),
  instructions: "You are a helpful assistant.",
  configuration: configuration,
)
```
```

--------------------------------

### Obtain resolver via schema

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/transcriptresolver.md

Shows how to get a resolver from the session schema and resolve a transcript.

```swift
let resolver = sessionSchema.transcriptResolver()
let resolved = try resolver.resolve(session.transcript)
```

--------------------------------

### Initializer: Schema-backed with direct API key

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicsession.md

Creates a session with a schema and a direct API key.

```APIDOC
## Initializer: Schema-backed with direct API key

### Description
Creates a session with a schema and a direct API key.

### Declaration
```swift
public init(
  schema: SessionSchema,
  instructions: String,
  apiKey: String,
  apiVersion: String = "2023-06-01",
  betaHeaders: [String]? = nil,
)
```

### Parameters
- **schema** (SessionSchema) - Required - Backing schema.
- **instructions** (String) - Required - Default system instructions.
- **apiKey** (String) - Required - Anthropic API key.
- **apiVersion** (String) - Optional, default "2023-06-01" - Value of the anthropic-version header.
- **betaHeaders** ([String]?) - Optional, default nil - Optional anthropic-beta header flags.
```

--------------------------------

### Create an AnthropicSession and respond

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Creates an AnthropicSession with instructions and an API key, then calls respond to get a single-turn answer.

```swift
import AnthropicSession

let session = AnthropicSession(
  instructions: "You are a helpful assistant.",
  apiKey: "sk-ant-...",
)

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

print(response.content)
```

--------------------------------

### init(schema:instructions:configuration:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/simulatedsession.md

Initializes a SimulatedSession with a schema, instructions, and a required SimulationConfiguration. This initializer is used when a session schema is provided.

```APIDOC
## init(schema:instructions:configuration:)

### Description
Initializes a SimulatedSession with a schema, instructions, and a required SimulationConfiguration. This initializer is used when a session schema is provided.

### Method
Initializer

### Signature
```swift
public init(
  schema: SessionSchema,
  instructions: String,
  configuration: SimulationConfiguration,
)
```

### Parameters
- **schema** (SessionSchema) - Required - The session schema.
- **instructions** (String) - Required - Default system instructions.
- **configuration** (SimulationConfiguration) - Required - Scripted generations, delay, token usage.

### Example
```swift
let schema = 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!"),
])

let session = SimulatedSession(
  schema: schema,
  instructions: "You are a helpful assistant.",
  configuration: configuration,
)
```
```

--------------------------------

### ToolRunRejection usage example

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/errors.md

Shows how to throw ToolRunRejection inside a tool's call method to signal a recoverable rejection when a customer is not found.

```swift
func call(arguments: Arguments) async throws -> Output {
  guard let customer = try await directory.loadCustomer(id: arguments.customerId) else {
    throw ToolRunRejection(
      reason: "Customer not found",
      details: ["issue": "customerNotFound", "customerId": arguments.customerId]
    )
  }
  return Output(summary: customer.summary)
}
```

--------------------------------

### Create an OpenAISession and respond with grounding

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Instantiate the schema and create an OpenAISession with instructions and an API key. Call respond(to:groundingWith:generating:) to send a user prompt, provide grounding data (travel date and must-visit ideas), and request structured output. The response content is then printed.

```swift
@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",
        "Kødbyens Fiskebar"
      ])
    ],
    generating: \.itinerary
  )

  print(response.content.headline)
  print(response.content.mustTry.joined(separator: " → "))
}
```

--------------------------------

### Build and run AgentRecorder CLI from Terminal

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Commands to build the AgentRecorder scheme with xcodebuild and run recording scenarios. Set OPENAI_API_KEY before running. The --list-scenarios flag lists available scenarios, and the second command runs a specific scenario.

```bash
xcodebuild -workspace SwiftAgent.xcworkspace -scheme AgentRecorder -destination "platform=macOS" -derivedDataPath .tmp/DerivedData build
OPENAI_API_KEY=sk-... ./.tmp/DerivedData/Build/Products/Debug/AgentRecorder --list-scenarios
OPENAI_API_KEY=sk-... ./.tmp/DerivedData/Build/Products/Debug/AgentRecorder --provider openai --scenario openai/streaming-tool-calls/weather
```

--------------------------------

### Using AgentSnapshot with streamResponse

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/agentresponsesnapshot.md

Example of streaming responses with streamResponse and processing each snapshot's partial content, transcript count, and token usage.

```swift
let stream = try session.streamResponse(to: "What's the weather like in San Francisco?")

for try await snapshot in stream {
  if let content = snapshot.content {
    print(content) // partial text as it streams
  }
  print("Transcript entries so far:", snapshot.transcript.count)
  if let usage = snapshot.tokenUsage {
    print("Tokens so far:", usage.totalTokens ?? 0)
  }
}
```

--------------------------------

### SimulationGenerationOptions.init()

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/simulationgenerationoptions.md

Initializes a SimulationGenerationOptions with default values, equivalent to init(simulatedGenerations: []).

```APIDOC
## Initializer

### Description
Creates a new `SimulationGenerationOptions` with default values.

### Signature
```swift
public init()
```

### Notes
Equivalent to `init(simulatedGenerations: [])`.
```

--------------------------------

### Usage example of @SessionSchema

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/sessionschema-macro.md

Shows how to apply @SessionSchema to a struct, using the @Tool, @Grounding, and @StructuredOutput property wrappers to declare tools, groundings, and structured outputs.

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

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

  @StructuredOutput(WeatherReport.self) var weatherReport
}
```

--------------------------------

### OpenAIConfiguration.direct(apiKey:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaiconfiguration.md

Builds a configuration that talks directly to https://api.openai.com. Sends the API key as an Authorization: Bearer header. Intended for prototyping only.

```APIDOC
## OpenAIConfiguration.direct(apiKey:)

### Description
Builds a configuration that talks directly to `https://api.openai.com`. The API key is sent as `Authorization: Bearer <key>`. Intended for prototyping only; do not ship an API key in an app binary.

### Declaration
```swift
public static func direct(apiKey: String) -> OpenAIConfiguration
```

### Parameters
- **apiKey** (String) - Required - OpenAI API key; sent as `Authorization: Bearer <key>`.

### Behavior
- JSON encoder uses `.sortedKeys` output formatting (important for reliable cache hits).
- `prepareRequest` interceptor sets the `Authorization` header.
- `onUnauthorized` returns `false` (no auto retry).
- Request timeout is `60` seconds.

```

--------------------------------

### SimulationGenerationOptions.init(simulatedGenerations:minimumStreamingSnapshotInterval:tokenUsageOverride:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/simulationgenerationoptions.md

Initializes a SimulationGenerationOptions instance with optional simulated generations, streaming snapshot interval, and token usage override.

```APIDOC
## Initializer

### Description
Creates a new `SimulationGenerationOptions` with the given parameters.

### Signature
```swift
public init(
  simulatedGenerations: [SimulatedGeneration] = [],
  minimumStreamingSnapshotInterval: Duration? = nil,
  tokenUsageOverride: TokenUsage? = nil,
)
```

### Parameters
- **simulatedGenerations** (`[SimulatedGeneration]`) - Optional - Generations for this turn; overrides the configuration's `defaultGenerations` when non-empty.
- **minimumStreamingSnapshotInterval** (`Duration?`) - Optional - Min time between emitted streaming snapshots.
- **tokenUsageOverride** (`TokenUsage?`) - Optional - Token usage emitted at the end of the run; takes precedence over `SimulationConfiguration.tokenUsage`.

### Example
```swift
let options = SimulationGenerationOptions(
  simulatedGenerations: [
    .reasoning(summary: "Checking the weather…"),
    .response(text: "Sunny, 22.5°C in San Francisco."),
  ],
  tokenUsageOverride: TokenUsage(inputTokens: 120, outputTokens: 40, totalTokens: 160),
)
```
```

--------------------------------

### init(for:)

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/transcriptresolver.md

Initializes a TranscriptResolver with a session schema provider.

```APIDOC
## init(for:)

### Description
Initializes a TranscriptResolver with a session schema provider.

### Declaration
```swift
public init(for provider: SessionSchema)
```

### Parameters
- **provider** (SessionSchema) - Required - The session schema that provides tools and structured outputs.

```

--------------------------------

### Initializer: Schema-backed with custom configuration

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicsession.md

Creates a session with a schema and a custom AnthropicConfiguration.

```APIDOC
## Initializer: Schema-backed with custom configuration

### Description
Creates a session with a schema and a custom AnthropicConfiguration.

### Declaration
```swift
public init(
  schema: SessionSchema,
  instructions: String,
  configuration: AnthropicConfiguration,
)
```

### Parameters
- **schema** (SessionSchema) - Required - Backing schema.
- **instructions** (String) - Required - Default system instructions.
- **configuration** (AnthropicConfiguration) - Required - Routing/auth options.
```

--------------------------------

### Define a StructuredOutput type and request a typed response with session.respond

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Conform a type to StructuredOutput and pass it to session.respond to get a fully typed response. SwiftAgent validates the payload against the schema, so the data can be used immediately without defensive decoding.

```swift
import FoundationModels
import OpenAISession

struct WeatherReport: StructuredOutput {
  static let name: String = "weatherReport"

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

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?",
  generating: WeatherReport.self,
)

// Fully typed response content
print(response.content.temperature)
print(response.content.condition)
print(response.content.humidity)
```

--------------------------------

### Initializer: Tool-only with direct API key

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/anthropicsession.md

Creates an AnthropicSession with tools and a direct API key, defaulting SessionSchema to NoSchema.

```APIDOC
## Initializer: Tool-only with direct API key

### Description
Creates a session with tools and a direct API key. SessionSchema defaults to NoSchema.

### Declaration
```swift
public init<each ToolType>(
  tools: repeat each ToolType,
  instructions: String = "",
  apiKey: String,
  apiVersion: String = "2023-06-01",
  betaHeaders: [String]? = nil,
) where
  SessionSchema == NoSchema,
  repeat (each ToolType): FoundationModels.Tool,
  repeat (each ToolType).Arguments: Generable,
  repeat (each ToolType).Output: Generable
```

### Parameters
- **tools** (variadic) - Optional - Tools available to the agent.
- **instructions** (String) - Optional, default "" - Default system instructions.
- **apiKey** (String) - Required - Anthropic API key.
- **apiVersion** (String) - Optional, default "2023-06-01" - Value of the anthropic-version header.
- **betaHeaders** ([String]?) - Optional, default nil - Optional anthropic-beta header flags.
```

--------------------------------

### Basic text response with OpenAISession

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaisession.md

Initializes an OpenAISession with instructions and an API key, then sends a prompt and prints the response content. Uses the default configuration.

```swift
import OpenAISession

let session = OpenAISession(
  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)
```

--------------------------------

### Issue and use a per-turn authorization token

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Before calling respond or streamResponse, obtain a short-lived token from your backend that identifies the signed-in user and expires after one turn. withAuthorization installs the token in a task-local context so all internal requests for that turn inherit the same bearer token.

```swift
let turnToken = try await backend.issueTurnToken(for: userId)
let response = try await session.withAuthorization(token: turnToken) {
  try await session.respond(to: "Summarize yesterday's sales numbers.")
}
```

--------------------------------

### Streaming with SimulationGenerationOptions

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/simulationgenerationoptions.md

Shows how to pass per-turn options to streamResponse. The options are honored exactly like the configuration's defaults, and the stream is iterated with for try await to print content snapshots.

```swift
let stream = try session.streamResponse(
  to: "What's the weather?",
  options: SimulationGenerationOptions(simulatedGenerations: [
    .reasoning(summary: "Consulting the mock weather service…"),
    .toolRun(tool: WeatherToolMock(tool: WeatherTool())),
    .response(text: "Sunny and 22.5°C."),
  ])
)

for try await snapshot in stream {
  if let content = snapshot.content {
    print(content)
  }
}
```

--------------------------------

### proxy(through:) factory method

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/openaiconfiguration.md

Creates a configuration that sends requests through a proxy backend. The baseURL is the proxy's base URL; the SDK appends /v1/responses. Requires an AuthorizationContext to be installed; otherwise a preconditionFailure is raised. On unauthorized, refreshes the token and retries once. Timeout is 60 seconds.

```swift
public static func proxy(through baseURL: URL) -> OpenAIConfiguration
```

--------------------------------

### Resolve transcript into structured snapshots

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/transcript.md

Resolves the transcript using a schema resolver to obtain structured snapshots. The example handles a typed tool run for the weather tool, printing its final arguments and output, and prints prompt sources for prompt entries. Use this to access resolved, typed data from the transcript.

```swift
let resolved = try sessionSchema.resolve(session.transcript)
for entry in resolved {
  switch entry {
  case let .toolRun(.weatherTool(run)):
    print(run.finalArguments?.city as Any, run.output as Any)
  case let .prompt(prompt):
    print("Groundings:", prompt.sources)
  default:
    break
  }
}
```

--------------------------------

### Access structured output from response and transcript with @StructuredOutput

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

When requesting structured data, decoded responses slot values directly into the schema. Use the generating parameter to specify the structured output key, then access the result from the live response or from the resolved transcript. The example shows switching on .response and .structuredSegments to extract the WeatherReport object.

```swift
import FoundationModels
import OpenAISession

@SessionSchema
struct SessionSchema {
  @Tool var weatherTool = WeatherTool()
  @StructuredOutput(WeatherReport.self) var weatherReport
}

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

let response = try await session.respond(
  to: "What's the weather like in San Francisco?",
  generating: \.weatherReport, // or schema.weatherReport, or WeatherReport.self
)

print(response.content) // WeatherReport object

// Access the structured output in the resolved transcript
for entry in try sessionSchema.resolve(session.transcript) {
  switch entry {
  case let .response(response):
    switch response.structuredSegments[0].content {
    case let .weatherReport(weatherReport):
      if let weatherReport = weatherReport.finalContent {
        print(weatherReport.condition, weatherReport.humidity, weatherReport.temperature)
      }
    case .unknown:
      print("Unknown output")
    }

  default: break
  }
}
```

--------------------------------

### ToolRun Initializers

Source: https://github.com/swiftedmind/swiftagent/blob/main/_autodocs/api-reference/toolrun.md

Initializers for creating a ToolRun instance with various configurations.

```APIDOC
## ToolRun Initializers

### Description
Initializers for creating a ToolRun instance.

### Initializer 1
```swift
public init(
  id: String,
  argumentsPhase: ArgumentsPhase,
  output: Output? = nil,
  rejection: Rejection? = nil,
  rawArguments: GeneratedContent,
  rawOutput: GeneratedContent? = nil,
)
```

### Initializer 2
```swift
public init(
  id: String,
  output: Output? = nil,
  rejection: Rejection? = nil,
  error: TranscriptResolvingError.ToolRunResolution,
  rawArguments: GeneratedContent,
  rawOutput: GeneratedContent? = nil,
)
```

```

--------------------------------

### Define a session schema with @SessionSchema, @Tool, @Grounding, and @StructuredOutput

Source: https://github.com/swiftedmind/swiftagent/blob/main/README.md

Use @SessionSchema to declare tools, groundings, and structured outputs. Each macro refines a portion of the transcript: @Tool links a tool implementation to its decoded entries, @Grounding registers values injected into prompts, and @StructuredOutput binds a guided generation schema to its decoded result. Pass the schema to OpenAISession to enable typed decoding.

```swift
@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
}

// Pass the schema to your session object
let sessionSchema = SessionSchema()
let session = OpenAISession(
  schema: sessionSchema,
  instructions: "You are a helpful assistant.",
  apiKey: "sk-...",
)
```
Tokens:
Raw