bond

README

Bond

The name's Bond. Agent Bond.

A(nother) Go framework for building agentic applications. Bond provides the streaming loop, tool execution, orchestration primitives, and runtime integrations — you bring the model. License to build.

Features

• Streaming agent loop with parallel tool execution and context cancellation
• Provider-agnostic — implement bond.Agent for any LLM (Bedrock, OpenAI, Ollama included)
• Hooks and plugins for cross-cutting concerns (logging, guardrails, metrics)
• Orchestration patterns — graphs (LangGraph-style) and swarms (OpenAI Swarm-style)
• A2A protocol support — remote agent communication, tool delegation, incremental streaming
• Multiple runtimes — AgentCore (AWS), generic HTTP/A2A/MCP, ACP for code editors
• MCP tool adapter — use MCP server tools in your agent
• MCP handler with SSE observability — real-time lifecycle notifications during execution
• Tool registry — expose large tool collections through a discovery gateway
• Built-in toolbox — shell execution, file I/O, environment access
• Zero external deps in the root — sub-packages isolate SDK dependencies

Install

go get github.com/nisimpson/bond

Quick Start

package main

import (
    "context"
    "fmt"

    "github.com/nisimpson/bond"
    "github.com/nisimpson/bond/provider/bedrock"
    "github.com/aws/aws-sdk-go-v2/config"
    bedrockrt "github.com/aws/aws-sdk-go-v2/service/bedrockruntime"
)

func main() {
    ctx := context.Background()
    cfg, _ := config.LoadDefaultConfig(ctx)
    client := bedrockrt.NewFromConfig(cfg)

    // Every agent needs a mission briefing.
    agent := bedrock.New(client, bedrock.AgentOptions{
        ModelID: "anthropic.claude-sonnet-4-20250514-v1:0",
        System:  "You are a secret agent. Be helpful, be discreet.",
    })

    resp, err := bond.Invoke(ctx, agent, bond.TextPrompt("Brief me on the situation."), bond.AgentOptions{})
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Text)
}

Core Concepts

Agent

The bond.Agent interface is the single abstraction at the center of everything:

type Agent interface {
    Stream(ctx context.Context, messages []Message) iter.Seq2[StreamEvent, error]
}

Anything that implements Agent can participate in bond: model providers, A2A proxies, graphs, swarms, test doubles.

Stream and Invoke

// Streaming — live intel as it arrives
for event, err := range bond.Stream(ctx, agent, messages, opts) { ... }

// Synchronous — debrief in one shot
resp, err := bond.Invoke(ctx, agent, messages, opts)

Tools (Gadgets)

Every good agent needs gadgets. Define them with NewFuncTool:

laserWatch, _ := bond.NewFuncTool(
    func(ctx context.Context, in CutInput) (CutOutput, error) {
        return CutOutput{Result: "lock disabled"}, nil
    },
    bond.FuncToolOptions{
        Name:        "laser_watch",
        Description: "Cuts through locks and barriers",
        InputSchema: tool.SchemaFor[CutInput](),
    },
)

Equip your agent:

bond.Stream(ctx, agent, msgs, bond.AgentOptions{
    Tools:    []bond.Tool{laserWatch, grappleHook, smokeBomb},
    MaxTurns: 10,
})

Plugins (Q Branch)

Plugins bundle gadgets and lifecycle hooks — your personal Q Branch:

bond.Stream(ctx, agent, msgs, bond.AgentOptions{
    Plugins: []bond.Plugin{surveillancePlugin, counterIntelPlugin},
})

Package Structure

bond/                        Core interfaces (Agent, Tool, Block, Stream, Invoke)
bond/agent/                  Orchestration: graph, swarm, AsTool
bond/agent/agenta2a/         A2A protocol proxy (bond.Agent over remote A2A agent)
bond/agent/agentacp/         ACP protocol client (bond.Agent over ACP transport)
bond/provider/bedrock/       Amazon Bedrock Converse streaming provider
bond/provider/openai/        OpenAI-compatible streaming provider
bond/provider/ollama/        Ollama local model provider
bond/runtime/                Generic protocol handlers (A2A, HTTP, MCP) for custom deployments
bond/runtime/acp/            ACP handler for code editors (Zed, JetBrains, VS Code)
bond/runtime/agentcore/      AWS Bedrock AgentCore defaults (ports, paths, session headers)
bond/tool/                   Tool infrastructure (schema, MCP adapter, structured output)
bond/extra/delegation/       A2A tool delegation (client + server)
bond/extra/toolbox/          Built-in tools: shell, file I/O, environment
bond/extra/toolregistry/     Tool discovery gateway plugin
bond/bondtest/               Test utilities (deterministic agent, event helpers)

Orchestration

Graph (Mission Planning)

Route between agents with conditional edges and shared state:

g := agent.NewGraph("intake", agent.GraphOptions{})

g.AddNode("intake", &agent.GraphNode{Agent: dispatchAgent})
g.AddNode("fieldwork", &agent.GraphNode{Agent: fieldAgent})
g.AddNode("gather_intel", &agent.GraphNode{
    Action: func(ctx context.Context, state agent.State) error {
        state.Set("dossier", fetchDossier(ctx))
        return nil
    },
})

g.AddConditionalEdge("intake", func(state agent.State) string {
    threat, _ := state.Get("threat_level")
    if threat == "critical" { return "gather_intel" }
    return agent.EndNode
})
g.AddEdge("gather_intel", "fieldwork")

bond.Invoke(ctx, g, bond.TextPrompt("new assignment"), bond.AgentOptions{})

Swarm (Multi-Agent Cell)

Agents transfer control dynamically — a cell of operatives:

s := agent.NewSwarm("handler", agent.SwarmOptions{})

s.AddAgent("handler", &agent.SwarmAgent{
    Agent:       handlerAgent,
    Description: "Coordinates operations and dispatches field agents.",
})
s.AddAgent("infiltrator", &agent.SwarmAgent{
    Agent:       infiltratorAgent,
    Description: "Specializes in social engineering and access.",
})
s.AddAgent("analyst", &agent.SwarmAgent{
    Agent:       analystAgent,
    Description: "Processes intelligence and provides situational analysis.",
})

// The handler decides when to bring in specialists
bond.Invoke(ctx, s, bond.TextPrompt("we need eyes inside"), bond.AgentOptions{})

Sub-Agent Tool (Delegation)

Wrap any agent as a tool — delegate missions to specialists:

tool := agent.AsTool(researchAgent, agent.ToolOptions{
    Name:        "research_operative",
    Description: "Delegates intelligence gathering to a specialist",
    StreamOptions: bond.AgentOptions{Tools: osintTools},
})

Tool Delegation (Double Agent Protocol)

When agents communicate over A2A, a client agent can lend its tools to a server agent. The server uses them as if they were local — never knowing the gadgets belong to someone else.

Client Side (The Quartermaster)

// Your agent connects to a remote specialist and offers its gadgets.
specialist := delegation.NewAgent(delegation.AgentOptions{
    Client: a2aClient,  // connected to remote agent
    Tools:  []bond.Tool{searchTool, databaseTool, satelliteTool},
})

// Use it like any agent — delegation is transparent.
resp, _ := bond.Invoke(ctx, specialist, bond.TextPrompt("find the target"), bond.AgentOptions{})

Server Side (The Field Agent)

// The server negotiates: "tell me what gadgets you have."
// Then it uses them as its own.
executor := delegation.NewExecutor(delegation.ExecutorOptions{
    Factory: func(ctx context.Context, skills []delegation.Skill, requester delegation.Requester) (bond.Agent, bond.AgentOptions) {
        agent := bedrock.New(client, bedrock.AgentOptions{
            ModelID: "anthropic.claude-sonnet-4-20250514-v1:0",
            System:  "You are a field operative. Use your available tools.",
        })
        return agent, bond.AgentOptions{
            Plugins: []bond.Plugin{
                delegation.NewPlugin(delegation.Options{
                    Requester: requester,
                    Skills:    skills,
                }),
            },
        }
    },
})

handler := agentcore.NewA2AHandlerFromExecutor(executor, agentcore.Options{})
http.ListenAndServe(handler.Port(), handler)

The server's model calls a delegated tool → Bond sends "input required" back to the client → the client executes the tool locally → result returns seamlessly. The model never knows the gadget was remote. Shaken, not stirred.

Runtime: AgentCore (Field Deployment)

Deploy your agent to AWS Bedrock AgentCore:

// A2A protocol (port 9000) — agent-to-agent communication
a2aHandler := agentcore.NewA2AHandler(agent, agentcore.Options{
    Card: &a2a.AgentCard{Name: "007", Description: "Licensed to assist"},
    AgentOptions: bond.AgentOptions{Tools: myTools},
})
http.ListenAndServe(a2aHandler.Port(), a2aHandler)

// HTTP protocol (port 8080) — direct invocations
httpHandler := agentcore.NewHTTPHandler(agent, opts)
http.ListenAndServe(httpHandler.Port(), httpHandler)

// MCP protocol (port 8000) — A2A operations as MCP tools
mcpHandler := agentcore.NewMCPHandler(agent, opts)
http.ListenAndServe(mcpHandler.Port(), mcpHandler)

MCP Handler: SSE Mode and Observability

Enable SSE mode for real-time visibility into long-running send_message calls:

mcpHandler := agentcore.NewMCPHandler(agent, agentcore.MCPOptions{
    SSEMode: true, // text/event-stream responses with observability notifications
})

In SSE mode, the handler emits structured ServerSession.Log notifications during execution:

• state_transition — thinking, executing_tools, generating_response
• tool_invoked / tool_result — tool call lifecycle with names and success indicators
• hook_fired / hook_completed — stream lifecycle boundaries with duration

Clients filter by logger name "bond.agent" to receive these events over the SSE connection. JSON mode (the default) continues to work exactly as before with no notifications.

// Or deploy all at once with graceful shutdown agentcore.Serve(agent, opts)

### Generic Runtime (Custom Deployments)

For non-AgentCore deployments, use the `runtime` package directly with your own ports and paths:

```go
import "github.com/nisimpson/bond/runtime"

handler := runtime.NewMCPHandler(agent, runtime.MCPOptions{
    Port:    ":3000",
    MCPPath: "/api/mcp",
    SSEMode: true,
})
http.ListenAndServe(handler.Port(), handler)

ACP Runtime (Editor Integration)

Serve agents as coding assistants over stdio for editors like Zed, JetBrains, and VS Code:

import "github.com/nisimpson/bond/runtime/acp"

handler := acp.NewHandler(agent, acp.Options{
    AgentName:    "bond-assist",
    AgentVersion: "1.0.0",
    Transport:    acp.DefaultTransport(),
})
handler.Serve(ctx)

MCP Integration

Equip your agent with tools from any MCP server:

session, _ := client.Connect(ctx, transport, nil)
tools, _ := tool.FromMCP(ctx, session)

bond.Stream(ctx, agent, msgs, bond.AgentOptions{Tools: tools})

Tool Registry (The Armory)

When you have more gadgets than an agent can carry, use the registry:

registry := toolregistry.New(toolregistry.Options{
    Tools: fiftyGadgets,
})

// Agent sees 3 tools: list_tools, describe_tool, use_tool
// It discovers what it needs on demand.
bond.Stream(ctx, agent, msgs, bond.AgentOptions{
    Plugins: []bond.Plugin{registry},
})

Testing (Training Exercise)

double := &bondtest.Agent{Events: bondtest.TextEvents("Mission accomplished.")}
resp, _ := bond.Invoke(ctx, double, bond.TextPrompt("status report"), bond.AgentOptions{})
// resp.Text == "Mission accomplished."

License

MIT

Documentation

Index

• Variables
• func OnAfter[T AfterHookEvent](r *HookRegistry, hook AfterHookFunc[T])
• func OnBefore[T BeforeHookEvent](r *HookRegistry, hook BeforeHookFunc[T])
• func Stream(ctx context.Context, agent Agent, messages []Message, opts AgentOptions) iter.Seq2[StreamEvent, error]
• type AfterHookEvent
• type AfterHookFunc
  • func (fn AfterHookFunc[T]) NotifyHookEvent(ctx context.Context, event HookEvent) error
• type AfterMessageAppendedHook
• type AfterModelInvokeHook
• type AfterStreamHook
• type AfterToolCallHook
• type AfterToolCycleHook
• type Agent
• type AgentOptions
• type BeforeHookEvent
• type BeforeHookFunc
  • func (fn BeforeHookFunc[T]) NotifyHookEvent(ctx context.Context, event HookEvent) error
• type BeforeModelInvokeHook
• type BeforeStreamEventHook
• type BeforeStreamHook
• type BeforeToolCallHook
• type BeforeToolCycleHook
• type Block
• type BlockType
• type FuncTool
  • func (ft FuncTool) Description() string
  • func (ft FuncTool) InputSchema() json.Marshaler
  • func (ft FuncTool) Name() string
  • func (ft FuncTool) OutputSchema() json.Marshaler
  • func (ft FuncTool) Run(ctx context.Context, input json.RawMessage) ([]Block, error)
• type FuncToolOptions
• type Hook
• type HookEvent
• type HookRegistry
  • func (r *HookRegistry) Notify(ctx context.Context, event HookEvent) error
• type InvokeResponse
  • func Invoke(ctx context.Context, agent Agent, messages []Message, opts AgentOptions) (*InvokeResponse, error)
• type JSONMarshaler
• type LoggingPlugin
  • func (p *LoggingPlugin) Init(registry *HookRegistry)
  • func (p *LoggingPlugin) Name() string
  • func (p *LoggingPlugin) Tools() []Tool
• type Media
• type MediaBlock
• type MediaDelta
• type MediaType
• type Message
  • func Conversation(turns ...string) []Message
  • func ImagePrompt(text, imageURI, mimeType string) []Message
  • func MultiBlockPrompt(blocks ...Block) []Message
  • func TextPrompt(text string) []Message
• type Plugin
  • func NewHooksPlugin(name string, onInit func(*HookRegistry)) Plugin
  • func NewToolConfirmationPlugin(provider ToolConfirmationProvider) Plugin
  • func NewToolsPlugin(name string, tools ...Tool) Plugin
• type Role
• type StopReason
• type StreamEvent
• type StreamEventType
• type TextBlock
• type Tool
  • func NewFuncTool[In, Out any](fn func(context.Context, In) (Out, error), options FuncToolOptions) (Tool, error)
  • func ToolsFromContext(ctx context.Context) []Tool
• type ToolConfirmationFunc
  • func (f ToolConfirmationFunc) ConfirmToolUse(ctx context.Context, toolUse *ToolUseBlock) (bool, error)
• type ToolConfirmationProvider
• type ToolResultBlock
• type ToolUseBlock

Variables

var ErrAbort = errors.New("bond: operation aborted by hook")

ErrAbort is returned by a before-hook to signal that the current operation should be cancelled. Use with Before* hooks to prevent execution.

Functions

func OnAfter

func OnAfter[T AfterHookEvent](r *HookRegistry, hook AfterHookFunc[T])

OnAfter registers an observer hook for the after-event type T. Observer hooks fire in registration order (FIFO). They cannot return errors and cannot interrupt the agent loop.

func OnBefore

func OnBefore[T BeforeHookEvent](r *HookRegistry, hook BeforeHookFunc[T])

OnBefore registers a gate hook for the before-event type T. Gate hooks fire in registration order (FIFO). Return ErrAbort or any error to prevent the guarded operation.

func Stream

func Stream(ctx context.Context, agent Agent, messages []Message, opts AgentOptions) iter.Seq2[StreamEvent, error]

Stream runs the full agent loop: it streams from the provider, and when the model requests tool use, it executes the tools, appends results to the conversation, and re-invokes the provider. Events are yielded to the caller transparently across turns.

Types

type AfterHookEvent

type AfterHookEvent interface {
	HookEvent
	// contains filtered or unexported methods
}

AfterHookEvent is implemented by observer hooks that fire after an operation. Observer hooks are informational — their handlers cannot return errors and cannot interrupt the agent loop.

type AfterHookFunc

type AfterHookFunc[T AfterHookEvent] func(context.Context, T)

AfterHookFunc is a handler for after (observer) events. It receives the concrete event type and cannot return an error — observer hooks are fire-and-forget.

func (AfterHookFunc[T]) NotifyHookEvent

func (fn AfterHookFunc[T]) NotifyHookEvent(ctx context.Context, event HookEvent) error

NotifyHookEvent implements Hook. Always returns nil since after-hooks cannot produce errors.

type AfterMessageAppendedHook

type AfterMessageAppendedHook struct {
	Message Message
}

AfterMessageAppendedHook fires when a message is appended to conversation history.

type AfterModelInvokeHook

type AfterModelInvokeHook struct {
	Blocks     []Block    // assembled assistant content blocks
	StopReason StopReason // why the model stopped
}

AfterModelInvokeHook fires after a provider Stream call has fully drained.

type AfterStreamHook

type AfterStreamHook struct {
	Messages []Message // full conversation history at completion
}

AfterStreamHook fires when the agent loop completes.

type AfterToolCallHook

type AfterToolCallHook struct {
	ToolUse *ToolUseBlock
	Result  *ToolResultBlock
}

AfterToolCallHook fires after a single tool execution completes.

type AfterToolCycleHook

type AfterToolCycleHook struct {
	Results []*ToolResultBlock
}

AfterToolCycleHook fires after all tool calls in a cycle complete.

type Agent

type Agent interface {
	// Stream sends the conversation messages to the model and returns
	// an iterator of streaming events. The last message in the slice
	// is treated as the current prompt; preceding messages are context.
	Stream(ctx context.Context, messages []Message) iter.Seq2[StreamEvent, error]
}

Agent is the core interface for streaming LLM interactions.

type AgentOptions

type AgentOptions struct {
	Tools    []Tool
	Plugins  []Plugin
	MaxTurns int // max tool-use round-trips; 0 means unlimited
}

AgentOptions configures the agent loop.

type BeforeHookEvent

type BeforeHookEvent interface {
	HookEvent
	// contains filtered or unexported methods
}

BeforeHookEvent is implemented by gate hooks that fire before an operation. Gate hooks can return errors to prevent execution. Return ErrAbort to gracefully skip the operation, or any other error to halt with that error.

type BeforeHookFunc

type BeforeHookFunc[T BeforeHookEvent] func(context.Context, T) error

BeforeHookFunc is a handler for before (gate) events. It receives the concrete event type and may return an error to prevent the operation.

func (BeforeHookFunc[T]) NotifyHookEvent

func (fn BeforeHookFunc[T]) NotifyHookEvent(ctx context.Context, event HookEvent) error

NotifyHookEvent implements Hook.

type BeforeModelInvokeHook

type BeforeModelInvokeHook struct {
	Messages []Message // conversation state being sent to the model
}

BeforeModelInvokeHook fires before calling the provider's Stream method. Return ErrAbort to skip the invocation, or any error to stop the loop.

type BeforeStreamEventHook

type BeforeStreamEventHook struct {
	Event StreamEvent
}

BeforeStreamEventHook fires before each raw StreamEvent is processed. Return ErrAbort to stop consuming the stream.

type BeforeStreamHook

type BeforeStreamHook struct {
	Messages []Message
}

BeforeStreamHook fires before the agent loop begins. Return ErrAbort to cancel the stream, or any error to stop with that error.

type BeforeToolCallHook

type BeforeToolCallHook struct {
	ToolUse *ToolUseBlock
}

BeforeToolCallHook fires before a single tool is executed. Return ErrAbort or any error to skip this tool call and surface the error as a tool result to the model.

type BeforeToolCycleHook

type BeforeToolCycleHook struct {
	ToolCalls []*ToolUseBlock
}

BeforeToolCycleHook fires before the batch of tool calls begins. Return ErrAbort to skip the entire tool cycle, or any error to abort all tool calls with error results.

type Block

type Block interface {
	// contains filtered or unexported methods
}

Block is the interface satisfied by all content blocks.

type BlockType

type BlockType string

const (
	BlockTypeText       BlockType = "text"
	BlockTypeMedia      BlockType = "media"
	BlockTypeToolUse    BlockType = "tool_use"
	BlockTypeToolResult BlockType = "tool_result"
)

type FuncTool

type FuncTool struct {
	// contains filtered or unexported fields
}

FuncTool is a Tool implementation backed by a function. The zero value is not usable; create instances with NewFuncTool.

func (FuncTool) Description

func (ft FuncTool) Description() string

func (FuncTool) InputSchema

func (ft FuncTool) InputSchema() json.Marshaler

func (FuncTool) Name

func (ft FuncTool) Name() string

func (FuncTool) OutputSchema

func (ft FuncTool) OutputSchema() json.Marshaler

func (FuncTool) Run

func (ft FuncTool) Run(ctx context.Context, input json.RawMessage) ([]Block, error)

type FuncToolOptions

type FuncToolOptions struct {
	Name         string
	Description  string
	InputSchema  json.Marshaler
	OutputSchema json.Marshaler
}

type Hook

type Hook interface {
	NotifyHookEvent(ctx context.Context, event HookEvent) error
}

Hook handles a specific hook event. This is the internal storage type.

type HookEvent

type HookEvent interface {
	// contains filtered or unexported methods
}

HookEvent is the sealed interface for all hook event types. Every hook event is either a BeforeHookEvent (gate) or AfterHookEvent (observer).

type HookRegistry

type HookRegistry struct {
	// contains filtered or unexported fields
}

HookRegistry manages hooks keyed by event type.

func (*HookRegistry) Notify

func (r *HookRegistry) Notify(ctx context.Context, event HookEvent) error

Notify dispatches an event to all registered hooks for that event type. For before-events, all hooks are called and errors are joined. If any hook returns ErrAbort, the joined error will contain it. For after-events, hooks are called but errors are always nil (since AfterHookFunc cannot produce errors).

type InvokeResponse

type InvokeResponse struct {
	// Text is the concatenated text output from the agent.
	Text string
	// Media contains any media content produced by the agent.
	Media []Media
	// StopReason indicates why the agent stopped.
	StopReason StopReason
}

InvokeResponse holds the collected result of a synchronous agent invocation.

func Invoke

func Invoke(ctx context.Context, agent Agent, messages []Message, opts AgentOptions) (*InvokeResponse, error)

Invoke runs the full agent loop synchronously, collecting all streamed events into a single InvokeResponse. This is a convenience wrapper over Stream for cases where streaming is not needed.

type JSONMarshaler

type JSONMarshaler = func(any) ([]byte, error)

type LoggingPlugin

type LoggingPlugin struct {
	Logger *slog.Logger
	Level  slog.Level
}

func (*LoggingPlugin) Init

func (p *LoggingPlugin) Init(registry *HookRegistry)

func (*LoggingPlugin) Name

func (p *LoggingPlugin) Name() string

func (*LoggingPlugin) Tools

func (p *LoggingPlugin) Tools() []Tool

type Media

type Media struct {
	// MIMEType is the media type (e.g. "image/png", "audio/wav").
	MIMEType string
	// Data is the raw bytes.
	Data []byte
}

Media represents a complete piece of media content in a response.

type MediaBlock

type MediaBlock struct {
	Type      MediaType
	MIMEType  string
	Source    io.Reader // content payload; wrap bytes with bytes.NewReader
	SourceURI string    // optional URI reference (e.g. S3 key, URL)
}

MediaBlock holds binary content (images, audio, video, documents).

type MediaDelta

type MediaDelta struct {
	// MIMEType is the media type (e.g. "image/png", "audio/wav").
	MIMEType string
	// Data is the raw bytes for this chunk.
	Data []byte
}

MediaDelta represents a chunk of binary/media content in a stream.

type MediaType

type MediaType string

MediaType describes the kind of binary content in a MediaBlock.

const (
	MediaTypeImage    MediaType = "image"
	MediaTypeAudio    MediaType = "audio"
	MediaTypeVideo    MediaType = "video"
	MediaTypeDocument MediaType = "document"
)

type Message

type Message struct {
	Role    Role
	Content []Block
	// Metadata holds provider-specific annotations (reasoning traces,
	// citations, guard content, cache points, etc.) that don't map
	// universally across providers.
	Metadata map[string]any
}

Message represents a single turn in a conversation.

func Conversation

func Conversation(turns ...string) []Message

Conversation builds a message list from alternating user/assistant strings. The first string is user, second is assistant, third is user, etc. Useful for constructing few-shot examples or test fixtures.

func ImagePrompt

func ImagePrompt(text, imageURI, mimeType string) []Message

ImagePrompt creates a user message with text and an image from a URI.

func MultiBlockPrompt

func MultiBlockPrompt(blocks ...Block) []Message

MultiBlockPrompt creates a user message from arbitrary blocks.

func TextPrompt

func TextPrompt(text string) []Message

TextPrompt is a convenience helper that wraps a plain string into the []Message format expected by Agent.Stream.

type Plugin

type Plugin interface {
	// Name identifies the plugin (used for logging/debugging).
	Name() string
	// Tools returns the tools this plugin contributes to the agent loop.
	Tools() []Tool
	// Init registers hooks on the provided registry. Called once during
	// stream setup before the loop begins.
	Init(registry *HookRegistry)
}

Plugin bundles tools and hook registrations into a reusable unit.

func NewHooksPlugin

func NewHooksPlugin(name string, onInit func(*HookRegistry)) Plugin

NewHooksPlugin creates a Plugin that registers hooks via the provided callback but does not contribute any tools. This is useful for cross-cutting concerns like logging, metrics, or guardrails that only need to observe or modify the agent loop through hooks.

func NewToolConfirmationPlugin

func NewToolConfirmationPlugin(provider ToolConfirmationProvider) Plugin

NewToolConfirmationPlugin returns a Plugin that intercepts BeforeToolCallHook and invokes the given provider before each tool execution. If the provider denies the call, the hook returns ErrAbort which causes the agent loop to skip the tool and return an error result to the model.

The provider is responsible for deciding which tools require confirmation. For example, it may allow all read-only tools unconditionally and only prompt for write operations.

func NewToolsPlugin

func NewToolsPlugin(name string, tools ...Tool) Plugin

NewToolsPlugin creates a Plugin that contributes the given tools to the agent loop without registering any hooks. This is useful when you only need to expose tools and don't require lifecycle callbacks.

type Role

type Role string

Role represents the sender of a message in a conversation.

const (
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
)

type StopReason

type StopReason string

StopReason indicates why the model stopped generating.

const (
	StopReasonEnd     StopReason = "end"      // natural end of response
	StopReasonToolUse StopReason = "tool_use" // paused to call a tool
	StopReasonLength  StopReason = "length"   // hit max token limit
)

type StreamEvent

type StreamEvent struct {
	Type StreamEventType

	// TextDelta is populated when Type == StreamEventTextDelta.
	TextDelta string

	// MediaDelta is populated when Type == StreamEventMediaDelta.
	MediaDelta *MediaDelta

	// ToolUse is populated when Type == StreamEventToolUse.
	ToolUse *ToolUseBlock

	// StopReason is populated when Type == StreamEventStop.
	StopReason StopReason

	// Metadata carries provider-specific event data (usage stats, trace IDs, etc.)
	Metadata map[string]any
}

StreamEvent represents a single event in a streaming response.

type StreamEventType

type StreamEventType string

StreamEventType identifies what kind of event was emitted during streaming.

const (
	// StreamEventStart signals the beginning of the response stream.
	StreamEventStart StreamEventType = "start"
	// StreamEventTextDelta delivers an incremental chunk of text.
	StreamEventTextDelta StreamEventType = "text_delta"
	// StreamEventMediaDelta delivers a chunk of binary/media content.
	StreamEventMediaDelta StreamEventType = "media_delta"
	// StreamEventToolUse signals the model wants to invoke a tool.
	StreamEventToolUse StreamEventType = "tool_use"
	// StreamEventStop signals the response is complete.
	StreamEventStop StreamEventType = "stop"
)

type TextBlock

type TextBlock struct {
	Text string
}

TextBlock holds plain text content.

type Tool

type Tool interface {
	// Name is the tool identifier the model will reference.
	Name() string
	// Description helps the model decide when to use this tool.
	Description() string
	// InputSchema is the JSON schema describing expected input parameters.
	InputSchema() json.Marshaler
	// Run executes the tool and returns result blocks.
	Run(ctx context.Context, input json.RawMessage) ([]Block, error)
}

Tool represents a tool the agent can invoke during streaming.

func NewFuncTool

func NewFuncTool[In, Out any](fn func(context.Context, In) (Out, error), options FuncToolOptions) (Tool, error)

NewFuncTool creates a Tool backed by a typed function. The function's input is unmarshaled from JSON, and its output is marshaled back into a TextBlock. Returns an error if required options (Name, Description) or the handler are missing.

func ToolsFromContext

func ToolsFromContext(ctx context.Context) []Tool

ToolsFromContext retrieves the tools available for the current invocation. Providers use this to include tool definitions in API requests. Returns nil if no tools are configured.

type ToolConfirmationFunc

type ToolConfirmationFunc func(ctx context.Context, toolUse *ToolUseBlock) (bool, error)

ToolConfirmationFunc adapts a plain function into a ToolConfirmationProvider.

func (ToolConfirmationFunc) ConfirmToolUse

func (f ToolConfirmationFunc) ConfirmToolUse(ctx context.Context, toolUse *ToolUseBlock) (bool, error)

ConfirmToolUse implements ToolConfirmationProvider.

type ToolConfirmationProvider

type ToolConfirmationProvider interface {
	// ConfirmToolUse is called before each tool invocation. Return true to
	// allow the call, or false to deny it. A denied call aborts with
	// [ErrAbort] and surfaces an error result to the model.
	ConfirmToolUse(ctx context.Context, toolUse *ToolUseBlock) (bool, error)
}

ToolConfirmationProvider decides whether a tool call should proceed. Implementations may prompt a user, check a policy, or consult an external service. The provider receives the full ToolUseBlock (tool name and input) and returns whether to allow or deny execution.

type ToolResultBlock

type ToolResultBlock struct {
	ToolUseID string
	Content   []Block // typically TextBlock or MediaBlock
	IsError   bool
}

ToolResultBlock holds the response from a tool invocation.

type ToolUseBlock

type ToolUseBlock struct {
	ID    string
	Name  string
	Input json.RawMessage
}

ToolUseBlock represents the model requesting a tool invocation.