custom

Any type that conforms to AgentProtocol is a first-class agent — the Orchestrator does not distinguish between custom and built-in agents. The protocol extension provides defaults for id, saveChat, and maxToolRounds, so a minimal implementation only needs name, description, and process.

For the full protocol definition and supporting types (AgentInput, AgentContext, AgentEvent) see the Agents overview.

Minimal example: EchoAgent

struct EchoAgent: AgentProtocol {
    let name = "Echo"
    let description = "Repeats the input back."

    func process(
        _ input: AgentInput,
        history: [ConversationMessage],
        context: AgentContext
    ) -> AsyncThrowingStream<AgentEvent, any Error> {
        AsyncThrowingStream { continuation in
            let text = input.text
            continuation.yield(.textDelta(text))
            continuation.yield(.final(ConversationMessage(role: .assistant, text: text)))
            continuation.finish()
        }
    }
}

Register it with the orchestrator exactly like a built-in Agent:

let orchestrator = Orchestrator(
    agents: [EchoAgent()],
    store: myChatStorage
)

Overriding defaults

The protocol extension defaults are:

Property	Default
id	slugify(name)
saveChat	true
maxToolRounds	1

Override any of them by declaring the property on your type:

struct MyAgent: AgentProtocol {
    let name = "My Agent"
    let description = "Does something useful."
    let maxToolRounds = 10   // allow up to 10 tool-call iterations per turn
    let saveChat = false     // do not persist turns

    func process(/* … */) -> AsyncThrowingStream<AgentEvent, any Error> { /* … */ }
}

:::caution A custom agent that uses tools must override maxToolRounds to a value greater than 1; the default of 1 means the loop never iterates past the first model call. The built-in Agent already handles this — the caution applies only when you implement AgentProtocol directly. :::