Open Agent SDK (Swift): Build AI Agent Applications with Native Swift Concurrency

#ai #swift #sdk #opensource

If you're a Swift developer looking to integrate AI Agent capabilities into your macOS apps, the options are slim. Most Agent frameworks are built for Python or TypeScript, leaving the Swift ecosystem with virtually no mature solutions. Open Agent SDK (Swift) was created to fill that gap.

What Is It?

Open Agent SDK is written in Swift 6.1 and requires macOS 13+. It runs the entire Agent Loop in-process: sending prompts, parsing responses, executing tool calls, feeding results back to the LLM, and repeating until a final answer is reached. The whole process is driven by native Swift concurrency (async/await, AsyncStream).

The project is inspired by open-agent-sdk-typescript, bringing the same Agent architecture to the Swift ecosystem. A Go version also exists in the same family.

Quick Start

Add the dependency in your Package.swift:

dependencies: [
    .package(url: "https://github.com/terryso/open-agent-sdk-swift.git", from: "0.1.0")
]

A few lines of code to get an Agent running:

import OpenAgentSDK

let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    systemPrompt: "You are a helpful assistant.",
    maxTurns: 10
))

let result = await agent.prompt("Explain Swift concurrency in one paragraph.")
print(result.text)
print("Used \(result.usage.inputTokens) input + \(result.usage.outputTokens) output tokens")

prompt() is blocking — a single call completes the entire Agent Loop. For streaming output, use stream():

for await message in agent.stream("Read Package.swift and summarize it.") {
    switch message {
    case .partialMessage(let data):
        print(data.text, terminator: "")
    case .toolUse(let data):
        print("Using tool: \(data.toolName)")
    case .result(let data):
        print("\nDone (\(data.numTurns) turns, $\(String(format: "%.4f", data.totalCostUsd)))")
    default:
        break
    }
}

Core Architecture

Your App (import OpenAgentSDK)
  └── Agent (prompt() / stream())
        └── Agentic Loop (API call → tool execution → repeat)
              ├── LLMClient Protocol (AnthropicClient / OpenAIClient)
              ├── 34 Built-in Tools
              ├── MCP Server Integration
              ├── Session Store (JSON Persistence)
              └── Hook Registry (20+ Lifecycle Events)

LLMClient Protocol: Abstracts LLM providers. Currently supports Anthropic (Claude) and OpenAI-compatible APIs (GLM, Ollama, OpenRouter, etc.). Supports runtime model switching with per-model billing.
Agent Loop: Automatically manages multi-turn conversations, tool calls, budget control, and auto-compaction.
Tool System: 34 built-in tools organized in three tiers — Core (10), Advanced (11), and Specialist (13). Supports defineTool() for custom tools with automatic Codable decoding.
MCP Integration: Supports stdio, SSE, HTTP, and in-process transports. MCP tools are automatically discovered and merged into the tool pool.
Multi-Agent Collaboration: Generate sub-agents via AgentTool (built-in Explore and Plan types), track task progress with the Task system, and support inter-agent communication via Team + Mailbox.
Session Persistence: Save, restore, and fork conversation history with three recovery strategies.
Permissions & Security: 6 permission modes + composable policies (allowlist, denylist, read-only) + sandboxing (path and command filtering) + Hook system (24 lifecycle events with interception and input modification).
Skills System: 5 built-in Skills (Commit, Review, Simplify, Debug, Test) with filesystem auto-discovery for custom Skills.
Thinking/Effort Configuration: Control LLM deep thinking capability and token budgets, with runtime dynamic adjustment.

Project Status

The SDK comes with 31 example projects covering basic usage, streaming, custom tools, MCP integration, session management, multi-agent collaboration, permission control, sandboxing, model switching, and more. The codebase is organized into nine modules — API, Core, Hooks, MCP, Skills, Stores, Tools, Types, and Utils — totaling approximately 90 Swift source files, released under the MIT license.

Subsequent articles in this series will dive deep into each subsystem's implementation details.

Deep Dive into Open Agent SDK (Swift) Series: