overview

Agents are the unit of work in AgentSquad. Each agent owns its LLM call and tool-use loop; the Orchestrator decides which agent handles a given turn and manages chat persistence.

AgentProtocol

Every agent conforms to AgentProtocol:

public protocol AgentProtocol: Sendable {
    var id: String { get }           // storage namespace + classifier key; defaults to slugify(name)
    var name: String { get }
    var description: String { get }
    var saveChat: Bool { get }       // orchestrator persists turns; defaults to true
    var maxToolRounds: Int { get }   // tool-loop cap; defaults to 1

    func process(
        _ input: AgentInput,
        history: [ConversationMessage],
        context: AgentContext
    ) -> AsyncThrowingStream<AgentEvent, any Error>
}

The protocol extension provides default implementations for id, saveChat, and maxToolRounds, so a minimal custom agent only needs to implement name, description, and process.

Property	Default	Notes
id	slugify(name)	Used as the storage namespace and classifier routing key.
saveChat	true	Set to false to opt the agent out of chat persistence.
maxToolRounds	1	Override to allow a tool-use loop. A tool-bearing agent that leaves this at 1 will never iterate past the first model call.

AgentInput

public enum AgentInput: Sendable {
    case text(String)
}

A convenience property surfaces the string without a pattern match:

let text = input.text   // "" when the case is not .text

:::note AgentInput covers turn-based text only. Continuous audio is handled by VoiceAssistant and its RealtimeEvent stream — not by AgentProtocol. :::

AgentContext

Carries per-turn identity, arbitrary params, and the live trace span:

public struct AgentContext: Sendable {
    public let userId: String
    public let sessionId: String
    public let params: [String: JSONValue]
    public let span: (any SpanHandle)?

    public init(
        userId: String,
        sessionId: String,
        params: [String: JSONValue] = [:],
        span: (any SpanHandle)? = nil
    )
}