Agent¶
Agent is an actor. Give it a Model and tools; call it for the answer, or stream every event.
import Loopl
func ask(_ model: any Model) async throws {
let agent = Agent(model: model,
tools: [CurrentTimeTool(), CalculatorTool()],
systemPrompt: "You are a concise assistant.")
let result = try await agent("What is 23 × 47?")
print(result.text) // the answer
print(result.stopReason) // .endTurn
print(result.metrics.cycleCount, // model calls
result.metrics.toolCallCount,
result.metrics.accumulatedUsage.totalTokens)
}
The loop¶
- Stream the model. Text is yielded as it arrives; tool calls are assembled.
- Run tools — every call in the turn, concurrently. Each call is checked against its tool's schema first: a broken call never reaches the tool, it gets an error result that says what was wrong, and the model usually fixes it next cycle.
- Repeat while the model asks for tools. When it stops, you get an
AgentResult.
There is no iteration cap and no loop detector. The bounds are the context window and cancellation. Throttling is retried (ModelRetryStrategy), an overflowing context is trimmed by the conversation manager, and a reply cut off at maxTokens is kept in history while MaxTokensReachedError is thrown — so you can simply continue:
import Loopl
func askResilient(_ agent: Agent, _ prompt: String) async throws -> AgentResult {
do { return try await agent(prompt) }
catch is MaxTokensReachedError { return try await agent() } // the partial turn is already in history
}
Stream¶
import Loopl
func show(_ agent: Agent, _ prompt: String) async throws {
for try await event in agent.stream(prompt) {
switch event {
case .text(let delta): print(delta, terminator: "")
case .toolStarted(let use): print("\n→ \(use.name) \(use.input)")
case .toolResult(let r): print("← \(r.name): \(r.content.prefix(80))")
case .throttle(let s): print("busy, retrying in \(Int(s)) s")
case .result(let r): print("\n\(r.stopReason), \(r.metrics.cycleCount) cycles")
default: break
}
}
}
AgentEvent |
when |
|---|---|
.startEventLoop(cycle:) |
each model call |
.text · .reasoning |
content as it streams |
.toolUseStream → .toolStarted → .toolResult |
one tool call, start to finish |
.modelMessage · .toolResultMessage |
messages appended to history |
.throttle(delay:) · .forceStop |
retry · unrecoverable stop |
.metrics |
tok/s, time to first token, context used |
.result |
last event |
For SwiftUI, Transcript folds events into rows and LooplUI draws them.
Interrupts¶
A hook or a tool can pause the loop to ask a person.
.suspend(default) — only that call waits; the stream stays alive and other tools keep running. Answer withagent.resolve(interrupt:response:). Tool approval is this, with a card..stop— the loop returns withstopReason == .interrupt; resume later. Finished tool results are kept, not re-run.
import Loopl
struct AskingTool: Tool {
let name = "ask_budget"
let description = "ask the human for a budget"
let parameters: JSONValue = ToolSchema.object([:])
func call(_ args: [String: JSONValue]) async throws -> String {
let answer = try InterruptScope.interrupt("budget", reason: .string("how much may I spend?"))
return "budget = \(answer.compact)"
}
}
func runWithStop(_ model: any Model) async throws {
let agent = Agent(model: model, tools: [AskingTool()], interruptMode: .stop)
var result = try await agent("book the cheapest flight")
while result.stopReason == .interrupt {
let answers = result.interrupts.map { InterruptResponse(interruptId: $0.id, response: .number(500)) }
result = try await agent.resume(answers)
}
print(result.text)
}
InterruptScope.interrupt throws the first time and returns the answer when the tool runs again — a tool is written once and resumes where it stopped.
Persist¶
Message is Codable, and the history is the state. For metrics and pending work too, use Checkpoints.
import Loopl
import Foundation
func save(_ agent: Agent, to url: URL) async throws {
try JSONEncoder().encode(await agent.messages).write(to: url)
}
func restore(_ model: any Model, from url: URL) throws -> Agent {
let messages = try JSONDecoder().decode([Message].self, from: Data(contentsOf: url))
return Agent(model: model, messages: messages)
}