AgentRunKit

A Swift 6 SDK for building LLM-powered agents with type-safe tool calling.

Zero-dependency core · Full Sendable · Async/await · Cloud + Local · MCP

---

Quick Start

import AgentRunKit

let client = OpenAIClient.openAI(apiKey: "sk-...", model: "gpt-5.4")

let weatherTool = try Tool<WeatherParams, String, EmptyContext>(
    name: "get_weather",
    description: "Get the current weather"
) { params, _ in
    "72°F and sunny in \(params.city)"
}

let agent = Agent(client: client, tools: [weatherTool])
let result = try await agent.run(userMessage: "What's the weather in SF?", context: EmptyContext())
if let content = result.content {
    print(content)
}

result.content is optional. A completed run returns the content of whatever ended it — the built-in finish tool, or a completion tool you supply — while structural terminal reasons such as max iterations or token budget exhaustion surface through result.finishReason with no final content.

To end the loop with your own typed tool instead of the built-in one, pass it as completionTool:. It replaces finish in the definitions sent to the model, executes through the normal tool path, and terminates the run only when it succeeds:

let agent = Agent(client: client, tools: [searchTool], completionTool: publishTool)

---

Documentation

Full documentation including guides and API reference is available on Swift Package Index.

---

Runnable Example

Examples/AgentCode is an interactive terminal coding agent built with AgentRunKit. It demonstrates the full agent loop in a local workspace: streaming events, type-safe tools, approval-gated edits and command execution, bounded file access, transcript export, and deterministic offline mode.

cd Examples/AgentCode
swift run agent-code

By default it opens a bundled broken Swift package so you can ask it to fix failing tests. Set OPENAI_API_KEY for a live OpenAI-compatible provider, or run without a key to exercise the CLI with the offline test client.

---

Installation

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/Tom-Ryder/AgentRunKit.git", from: "5.3.0")
]

.target(name: "YourApp", dependencies: ["AgentRunKit"])

For on-device inference, additional targets are available:

• AgentRunKitMLX for MLX on Apple Silicon (links mlx-swift-lm)
• AgentRunKitFoundationModels for Apple Foundation Models (iOS 26+ and macOS 26+, no external dependencies)

---

Upgrading to 5.5

Custom completion tools ship in 5.5 with three deliberate changes for existing code:

• AgentCheckpointError gained completionToolMismatch(checkpointed:live:), thrown when a terminal checkpoint is resumed by an agent that completes through a different tool. A switch over AgentCheckpointError without a default must handle the new case.
• TestLLMClient in AgentRunKitTesting gained a defaulted completionToolName: initializer parameter. Existing call sites compile unchanged.
• A sub-agent's nested .finished, .iterationCompleted, and .budgetUpdated events no longer write to the parent AgentStream's tokenUsage, finishReason, history, content, iterationUsages, iterationsReplayed, or contextBudget. A parent that emitted no content deltas previously displayed the last child's finish content and now displays its own. Nested events remain fully observable, and toolCalls still flattens them.

---

Features

• Agent loop with configurable iteration limits and token budgets
• Streaming with AsyncThrowingStream and @Observable SwiftUI wrapper
• Type-safe tools with compile-time JSON schema validation
• Sub-agent composition with depth control and streaming propagation
• Context management: automatic compaction, pruning, token budgets
• Checkpoint and resume: per-iteration snapshots, file or in-memory backends
• Tool approval: human-in-the-loop policies with session allowlists
• Structured output with JSON schema constraints
• Multimodal input: images, audio, video, PDF
• Text-to-speech with concurrent chunking and MP3 concatenation
• MCP client: stdio transport, tool discovery, JSON-RPC
• Extended thinking / reasoning model support

---

Providers

Provider	Description
OpenAIClient	OpenAI and compatible APIs (OpenRouter with reasoning replay, Groq, Together, Ollama)
AnthropicClient	Anthropic Messages API with same-substrate continuity replay
GeminiClient	Google Gemini API
VertexAnthropicClient	Anthropic models on Google Vertex AI with same-substrate continuity replay
VertexGoogleClient	Google models on Vertex AI
ResponsesAPIClient	OpenAI Responses API with same-substrate continuity replay and OpenRouter factory
FoundationModelsClient	Apple on-device (macOS 26+ / iOS 26+)
MLXClient	On-device via MLX on Apple Silicon

---

Requirements

Platform	Version
iOS	18.0+
macOS	15.0+
Swift	6.1+
Xcode	26+ for local development and CI

---

License

MIT License. See LICENSE for details.