Operator

A lean, un-opinionated Swift library for building tool-using AI agents. Using Operator, you can easily swap providers mid-conversation, even from a hosted API such as Anthropic to an on-device model provided by Apple Foundation Models.

Architecture

Operator sits in the middle of a three-layer stack:

Layer	Role
OperativeKit	Multi-agent composition based on fixed or dynamic graphs
Operator (this repo)	Agent loop — tools, middleware, budgets, streaming events
LLM	Raw model communication — stateless, provider-agnostic

Many chatbot applications would only need Operator. Reach for OperativeKit when you need to coordinate multiple agents or design more complex workflows.

Quick Example

import Operator

// Define a tool by conforming to Operable
struct URLParser: Operable {
    var toolGroup: ToolGroup {
        ToolGroup(
            name: "URL Parser",
            description: "Parse and inspect URLs",
            tools: [
                try Tool(
                    name: "parseURL",
                    description: "Parse a URL into its components",
                    input: ParseURLInput.self
                ) { input in
                    let results = input.components.map { $0.extract(from: input.url) }
                    return ToolOutput(results)
                },
            ]
        )
    }
}

// Create and run an Operative
let operative = try Operative(
    llm: myLLM,
    systemPrompt: "You help users work with URLs.",
    tools: [URLParser()],
    budget: Budget(maxTurns: 10)
)

for await operation in operative.run("What's the host and port of https://example.com:8080/api?active=true") {
    switch operation {
    case .text(let chunk):
        print(chunk, terminator: "")
    case .completed(let result):
        print("\nDone. Tokens used: \(result.usage.totalTokens)")
    default:
        break
    }
}

Documentation

Browse the documentation online, or check out the DocC catalog at Sources/Operator/Documentation.docc/. Key articles:

• Architecture — Data flow and the three-layer model
• Operative — The agent loop, configuration, and lifecycle
• Tools and Operables — Defining tools at three tiers of complexity
• Tool Input — Automatic JSON Schema extraction from Swift types
• Middleware — Intercepting, transforming, and filtering agent behavior
• Budget — Controlling how long and how far an agent can run
• Operations — The real-time event stream
• Apple Intelligence — On-device Foundation Models integration (macOS 26+, iOS 26+)
• Multimodal Content — Sending images, PDFs, and mixed media in conversations and tool results
• MCP Integration — Connect to MCP servers and use their tools with any Operative

Generate HTML docs with:

swift package generate-documentation --target Operator

# Serve the docs:
swift package --disable-sandbox preview-documentation --target Operator

Installation

Add Operator as a Swift Package Manager dependency:

dependencies: [
    .package(url: "https://github.com/bensyverson/Operator", branch: "main"),
]

Then add it to your target:

.target(
    name: "MyApp",
    dependencies: [
        .product(name: "Operator", package: "Operator"),
    ]
)

Requires Swift 6.2+ and macOS 15+ / iOS 18+.

Examples

Chat

Examples/Chat/ is a rich terminal chat UI built with TextUI. It demonstrates streaming, tool calling, multi-turn conversation, and debug mode in a full-screen TUI app.

cd Examples/Chat
swift run

---

License

This project is licensed under the MIT License.

Copyright (c) 2026 Ben Syverson