swift-agent-runtime

LLM エージェントループと A2A/ACP オーケストレーション層を提供する Swift パッケージ。

概要

swift-agent-runtime は 2 つの責務をターゲットで分離して提供します。

• AgentLoopKit — A2A 非依存の汎用エージェントループ。swift-llm-client だけに依存し、LLM 呼び出し・ツール並列実行・input-required 中断・ACP session/update 射影を担う
• AgentRuntime — A2A を前提としたオーケストレーション層。HostAgent（委譲ループ型）・RouterHostAgent（パススルー型）・LLMAgentExecutor（ワーカー）・HostACPAgent（ACP 露出）を提供する

アーキテクチャ

App / CLI
   ↕ ACP（縦境界）
HostACPAgent
   ↕
HostAgent / RouterHostAgent
   ↕ A2A（横境界）
AgentConnectionRegistry  →  Workers (LLMAgentExecutor)
                                  ↕
                            AgentLoop (AgentLoopKit)
                                  ↕
                         LLMClient (swift-llm-client)

AgentLoopKit の主な型

AgentRuntime の主な型

インストール

// Package.swift
dependencies: [
    .package(url: "https://github.com/no-problem-dev/swift-agent-runtime.git", .upToNextMajor(from: "0.10.0"))
]

// ループだけ使う場合（A2A 非依存）
.target(name: "YourTarget", dependencies: [
    .product(name: "AgentLoopKit", package: "swift-agent-runtime"),
])

// A2A オーケストレーションも使う場合
.target(name: "YourTarget", dependencies: [
    .product(name: "AgentRuntime", package: "swift-agent-runtime"),
])

クイックスタート

AgentLoopKit — 単体エージェントループ

import AgentLoopKit

let loop = AgentLoop(
    client: myLLMClient,
    model: myModel,
    tools: ToolSet {
        MySearchTool()
        RequestUserInputTool()
    },
    systemPrompt: SystemPrompt(stringLiteral: "You are a helpful assistant."),
    maxSteps: 12
)

for try await event in loop.events(messages: [.user("今日の東京の天気は？")]) {
    switch event {
    case .thinking(let text):
        print("thinking: \(text)")
    case .toolCall(_, let name, _):
        print("calling tool: \(name)")
    case .toolResult(_, _, let output, let isError):
        print("tool result (error=\(isError)): \(output)")
    case .inputRequired(let question):
        print("needs user input: \(question)")
    case .completed(let text):
        print("completed: \(text)")
    }
}

テレメトリ（コスト計測）を受け取る場合:

let accumulator = UsageAccumulator()

let loop = AgentLoop(
    client: myLLMClient,
    model: myModel,
    telemetry: { telemetry in
        if case let .usage(usage, model) = telemetry {
            await accumulator.add(usage)
            print("[\(model)] input=\(usage.inputTokens) output=\(usage.outputTokens)")
        }
    }
)

AgentRuntime — in-process ワーカーへ委譲する HostAgent

import AgentRuntime

// 1. ワーカーを登録
let registry = AgentConnectionRegistry()

let workerExecutor = LLMAgentExecutor(
    client: myLLMClient,
    model: myModel,
    systemPrompt: SystemPrompt(stringLiteral: "You are a research specialist."),
    maxSteps: 8
)
let workerCard = AgentCard(
    name: "researcher",
    description: "Searches and summarizes information on any topic."
)
await registry.register(card: workerCard, executor: workerExecutor)

// 2. HostAgent を作成してリクエストを投げる
let host = HostAgent(
    client: myLLMClient,
    model: myModel,
    registry: registry
)

let result = try await host.run("量子コンピューティングの最新動向を調べてまとめて")
print(result)

// ストリーミングで受け取る場合
for try await event in await host.stream("Swift Concurrency のベストプラクティスは？") {
    if case .completed(let text) = event { print(text) }
}

バックグラウンド委譲（非ブロッキング）

// delegate_async: 即返し。ワーカーはバックグラウンドで実行継続
let handle = try await registry.delegateAsync(
    to: "researcher",
    text: "宇宙望遠鏡の最新データを分析して",
    delivery: .all   // subscribe + push + poll の3方式を同時使用
)
print("taskId=\(handle.taskId?.rawValue ?? "nil")")

// 後から確認
let status = try await registry.checkTask(handle.taskId!)
print("state=\(status.state), text=\(status.text)")

// 実行中タスク一覧
let running = await registry.listRunningTasks()

RouterHostAgent — パススルー型ルーター

import AgentRuntime

let router = RouterHostAgent(
    client: myLLMClient,
    model: myModel,
    registry: registry,
    hooks: RouterHostAgent.Hooks(
        // LLM を介さない決定的ルーティング（例: userAction の surfaceId に基づく転送）
        preRoute: { parts in
            guard let text = parts.first?.text else { return nil }
            return text.contains("画像") ? "vision-agent" : nil
        }
    )
)

for try await event in await router.send([Part.text("この画像を解析して")]) {
    switch event {
    case .routed(let agent, let deterministic, _):
        print("routed to \(agent) (deterministic=\(deterministic))")
    case .worker(let streamResponse):
        // ワーカーの応答をそのままパススルー
        break
    }
}

HostACPAgent — ACP 境界でのセッション管理

import AgentRuntime

let acpAgent = HostACPAgent(
    client: acpClient,
    telemetry: { telemetry in
        // コスト計測など
    },
    makeHost: {
        HostAgent(client: llmClient, model: model, registry: registry)
    }
)
// acpAgent は ACPAgent プロトコルを実装しており、ACP フレームワークに渡すだけで
// セッション管理・会話永続化（cwd/conversation.json）・マルチモーダル入力を処理する

対応プラットフォーム / 要件

• Swift 6.2+
• 依存: swift-a2a 0.6.2+、swift-llm-client 3.7.0+、swift-structured-data 1.3.0+、swift-acp 0.1.0+

ライセンス

MIT