agentcore

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 30, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const CurrentStateSnapshotVersion = 1

Variables

View Source 
var ErrExceedMaxSteps = fmt.Errorf("exceeded maximum execution steps")

ErrExceedMaxSteps is returned when a graph/workflow exceeds the maximum step count.

View Source 
var ErrInterrupt = errors.New("interrupt")

ErrInterrupt is returned by a tool to request the agent loop to pause. The agent saves its state and returns control so the caller can inspect the interrupt reason and call Resume() to continue.

Usage in a tool: 

func myTool(ctx context.Context, args json.RawMessage) (any, error) {
    return "User requested pause", NewInterruptError("user requested pause")
}
View Source 
var ErrRepetitionLoop = errors.New("stream repetition loop detected")

ErrRepetitionLoop is returned (wrapped) when a provider middleware detects the model has degenerated into repeating the same text/tokens verbatim mid-stream. Unlike transport errors, this is never retried with the same request via callProviderWithRetry — the caller (runLoop) is expected to catch it with IsRepetitionLoopError and drive its own recovery ladder (inject a corrective steering message and try again, up to a limit) rather than blindly resending the identical request.

Functions

func CloneStringSlice 

func CloneStringSlice(values []string) []string

func CoerceToolArguments added in v1.0.3 

func CoerceToolArguments(tool *Tool, arguments string) string

CoerceToolArguments coerces argument values to match the tool's parameter schema types. This handles the common LLM mistake of emitting numbers and booleans as JSON strings (e.g. {"count": "5"} instead of {"count": 5}). It returns the coerced arguments string, or the original if no coercion was needed or if the arguments are not valid JSON / the tool has no schema.

func CollectString added in v1.0.1 

func CollectString(s *StreamReader[string]) (string, error)

CollectString drains a string stream and joins all chunks.

func ContinueStructured 

func ContinueStructured[T any](ctx context.Context, agent *Agent) (T, error)

ContinueStructured resumes the agent and decodes the final output into T.

func ContinueStructuredInto 

func ContinueStructuredInto[T any](ctx context.Context, agent *Agent, dst *T) (string, error)

ContinueStructuredInto resumes the agent and decodes the final output into dst.

func DecodeStructured 

func DecodeStructured[T any](raw string) (T, error)

DecodeStructured unmarshals a structured JSON string into T.

func DecodeStructuredInto 

func DecodeStructuredInto(raw string, dst any) error

DecodeStructuredInto unmarshals a structured JSON string into dst.

func EstimateMessageTokens 

func EstimateMessageTokens(msg Message) int64

EstimateMessageTokens estimates token count for a single message, including role overhead, content, and tool call payloads.

func EstimateMessagesTokens 

func EstimateMessagesTokens(msgs []Message) int64

EstimateMessagesTokens estimates total token count for a slice of messages.

func EstimateTokens 

func EstimateTokens(text string) int64

EstimateTokens returns a rough token count using the chars/4 heuristic.

func EstimateToolDefinitionsTokens 

func EstimateToolDefinitionsTokens(defs []ToolDefinition) int64

EstimateToolDefinitionsTokens estimates token overhead of tool definitions in the request (they count against the context window).

func ExtractStructuredContent 

func ExtractStructuredContent(content string, format *ResponseFormat) json.RawMessage

ExtractStructuredContent returns the raw JSON payload when a structured output request was made and the provider returned valid JSON content.

func InterruptData added in v1.0.1 

func InterruptData(err error) map[string]any

InterruptData returns the structured data carried by an interrupt error.

func InterruptMessage added in v1.0.1 

func InterruptMessage(err error) string

InterruptMessage extracts the human-readable reason from an interrupt error. Returns the error text if the error is not an interrupt.

func IsContextOverflowError 

func IsContextOverflowError(err error) bool

IsContextOverflowError returns true if the error indicates the context window has been exceeded. These errors should trigger compaction, not retry.

func IsInterrupt added in v1.0.1 

func IsInterrupt(err error) bool

IsInterrupt reports whether err indicates an agent interrupt.

func IsRepetitionLoopError added in v1.0.2 

func IsRepetitionLoopError(err error) bool

IsRepetitionLoopError returns true if err is (or wraps) ErrRepetitionLoop.

func IsRetryableError 

func IsRetryableError(err error) bool

IsRetryableError returns true if the error is transient and worth retrying. Context overflow errors are explicitly excluded (they should trigger compaction instead).

func MessageStringForSummary 

func MessageStringForSummary(m Message) string

MessageStringForSummary formats a message for compaction / logging (includes thinking, tool calls, and tool-call payloads in plain text).

func MessageTextBody 

func MessageTextBody(m Message) string

MessageTextBody returns legacy Content plus all text/thinking blocks in order. Thinking segments are wrapped in <thinking>...</thinking> for traceability; callers that feed the LLM should use MessageCollapseForLLM instead.

func NewInterruptError added in v1.0.1 

func NewInterruptError(reason string) error

NewInterruptError wraps ErrInterrupt with a human-readable reason. The reason is persisted as a friendly tool result, not an error message.

func NewInterruptErrorWithData added in v1.0.1 

func NewInterruptErrorWithData(reason string, data map[string]any) error

NewInterruptErrorWithData is like NewInterruptError but also carries structured data that the caller can inspect via Interrupted().Data.

func NewModelMetricsMiddleware added in v1.0.5 

func NewModelMetricsMiddleware(metrics Metrics) func(Provider) Provider

ModelMetricsMiddleware wraps every provider call to record token usage, duration, and model errors. Unlike NewModelSpanMiddleware it does not skip when a model span already exists — every invocation counts, including the agent's own turns. Returns a pass-through when metrics are nil.

func NewModelSpanMiddleware added in v1.0.5 

func NewModelSpanMiddleware(tracer Tracer) func(Provider) Provider

NewModelSpanMiddleware wraps every provider call in a "model" component span carrying GenAI semantic-convention attributes (gen_ai.*), so observability backends (Langfuse, Jaeger, ...) can render per-call generations with token usage. It complements the span created by callProvider for the agent's own turns and covers direct/auxiliary provider calls that bypass callProvider (context compression, title generation, review, guardrails, etc.).

The middleware is safe to apply to an already-instrumented chain: it skips when the context already carries a model RunInfo — created by callProvider or by a nested middleware instance — so a single LLM call is never traced twice. Passing a nil tracer yields a pass-through middleware (tracing off).

func RegisterProfile added in v1.0.2 

func RegisterProfile(p ModelProfile)

RegisterProfile registers a model profile globally. A profile with the same Name replaces any previously registered one. Registration affects all subsequent New() calls — call from init() or program startup. It is safe for concurrent use.

func ResetProfilesForTest added in v1.0.2 

func ResetProfilesForTest()

ResetProfilesForTest clears all registered profiles. Intended for test isolation; do not call in production code.

func RunSequentialAgents 

func RunSequentialAgents(ctx context.Context, agents []*Agent, user string) (string, error)

SequentialAgentStep runs one agent after another, passing the previous agent's final output as the next agent's user message (unless empty).

func RunStructured 

func RunStructured[T any](ctx context.Context, agent *Agent, input string) (T, error)

RunStructured runs the agent and decodes the final output into T.

func RunStructuredInto 

func RunStructuredInto[T any](ctx context.Context, agent *Agent, input string, dst *T) (string, error)

RunStructuredInto runs the agent and decodes the final output into dst. It returns the raw output string for callers that also want the original JSON.

func StartComponentRun added in v1.0.3 

func StartComponentRun(ctx context.Context, tracer Tracer, component, name string, attrs ...SpanAttribute) (context.Context, Span, RunInfo)

StartComponentRun creates correlated metadata and a span for a component.

func ValidateToolArguments 

func ValidateToolArguments(tool *Tool, arguments string) error

ValidateToolArguments validates tool call arguments against the tool's parameter schema. Returns nil if valid, or a descriptive error.

func WithRunInfo added in v1.0.3 

func WithRunInfo(ctx context.Context, info RunInfo) context.Context

func WrapNodeError 

func WrapNodeError(err error, pathSegment string) error

WrapNodeError appends a path segment to an existing NodeError, or wraps a plain error into a new NodeError.

Types

type AfterHook 

type AfterHook func(ctx context.Context, hc *HookContext, result string, err error)

AfterHook runs after tool execution with the result string and any error.

func LoggingAfterHook 

func LoggingAfterHook(logger *slog.Logger) AfterHook

LoggingAfterHook logs tool call completion via slog.

type Agent 

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

Agent is the core runtime that orchestrates LLM calls and tool execution.

func LoadAgent 

func LoadAgent(ctx context.Context, cfg Config, opts LoadAgentOptions) (*Agent, error)

func New 

func New(cfg Config) *Agent

func NewWithError added in v1.0.3 

func NewWithError(cfg Config) (*Agent, error)

NewWithError constructs an Agent and reports extension initialization errors. New remains available for compatibility; agents returned by New surface the same error from Run, Continue, Resume, and InvokeTool.

func (*Agent) ApplyCallConfig 

func (a *Agent) ApplyCallConfig(cc *CallConfig)

ApplyCallConfig updates the agent's Model, Thinking, ResponseFormat, and SelectedSkills from the given CallConfig. This is used by the server pool to apply thread-level or request-level overrides before reusing a cached agent.

func (*Agent) Close 

func (a *Agent) Close()

Close releases all resources held by the agent, including extensions and the event bus. Call this when the agent is no longer needed. It is safe to call multiple times. After Close, the agent should not be used for further Run calls — create a new Agent instead.

func (*Agent) Config 

func (a *Agent) Config() Config

func (*Agent) ContextEngine 

func (a *Agent) ContextEngine() ContextEngine

ContextEngine returns the active context engine (nil if compaction is disabled).

func (*Agent) ContextEngineStats 

func (a *Agent) ContextEngineStats() map[string]any

ContextEngineStats returns diagnostics from the active engine.

func (*Agent) Continue 

func (a *Agent) Continue(ctx context.Context) (string, error)

Continue resumes the agent loop from the current state without adding new input.

func (*Agent) EmitEvent 

func (a *Agent) EmitEvent(e Event)

func (*Agent) EmitExtensionSnapshots 

func (a *Agent) EmitExtensionSnapshots()

func (*Agent) ExtensionNames 

func (a *Agent) ExtensionNames() []string

func (*Agent) FollowUp 

func (a *Agent) FollowUp(msg Message)

FollowUp queues a message that will be processed after the current conversation finishes (no more tool calls). The agent loop restarts with the follow-up as new input.

func (*Agent) ForceCompact 

func (a *Agent) ForceCompact(ctx context.Context) error

func (*Agent) ForceCompactWithTopic 

func (a *Agent) ForceCompactWithTopic(ctx context.Context, focusTopic string) error

func (*Agent) GetTool 

func (a *Agent) GetTool(name string) (*Tool, bool)

func (*Agent) Interrupted added in v1.0.1 

func (a *Agent) Interrupted() *InterruptReason

Interrupted returns the interrupt reason if the agent was interrupted, or nil if it completed normally or hasn't run yet.

func (*Agent) InvokeTool added in v1.0.2 

func (a *Agent) InvokeTool(ctx context.Context, name string, args json.RawMessage) (string, error)

InvokeTool runs a single named tool through the exact same hook pipeline as a normal model-issued tool call (tool-before -> global-before -> middleware chain -> global-after -> tool-after), rather than calling its Func directly. Use this instead of GetTool+Func when a caller needs to invoke a tool programmatically -- e.g. from a sandboxed script via Programmatic Tool Calling -- while still getting audit logging, guardrails, and any other configured hooks applied exactly as they would be for the model's own tool calls.

func (*Agent) LoadState 

func (a *Agent) LoadState(ctx context.Context, key string) error

func (*Agent) On 

func (a *Agent) On(t EventType, h EventHandler) func()

func (*Agent) OnAll 

func (a *Agent) OnAll(h EventHandler) func()

func (*Agent) RegisterContextEngine 

func (a *Agent) RegisterContextEngine(name string, factory ContextEngineFactory)

RegisterContextEngine registers a custom context engine factory.

func (*Agent) RegisterTools 

func (a *Agent) RegisterTools(tools ...*Tool)

func (*Agent) ResetContextEngine 

func (a *Agent) ResetContextEngine()

ResetContextEngine clears per-session state for the active engine.

func (*Agent) RestoreLatestCheckpoint 

func (a *Agent) RestoreLatestCheckpoint(ctx context.Context, threadID string) error

RestoreLatestCheckpoint loads the latest snapshot for threadID into this agent. If threadID is empty, Config.Checkpoint.ThreadID (or "default") is used. The restored Status is whatever was saved (e.g. StatusFinished after a completed reply, StatusInterrupted after an interrupt); call Resume() to continue from an interrupt, or SetStatus(StatusRunning) before Continue for a normal follow-up.

func (*Agent) Resume added in v1.0.1 

func (a *Agent) Resume(ctx context.Context) (string, error)

Resume continues execution after an interrupt. The agent must have StatusInterrupted (check Interrupted() != nil). It replays the conversation from the tool result that triggered the interrupt, allowing the LLM to continue naturally.

func (*Agent) Run 

func (a *Agent) Run(ctx context.Context, input string) (string, error)

Run starts the agent loop with a new user input. The Agent can be reused across multiple Run calls — conversation state is preserved between calls and system prompt is only persisted once.

func (*Agent) SaveCheckpoint 

func (a *Agent) SaveCheckpoint(ctx context.Context) (int64, error)

SaveCheckpoint persists the current StateSnapshot to the configured CheckpointSaver.

func (*Agent) SaveState 

func (a *Agent) SaveState(ctx context.Context, key string) error

func (*Agent) SetContextEngine 

func (a *Agent) SetContextEngine(engine ContextEngine)

SetContextEngine replaces the active context engine at runtime.

func (*Agent) SetEventBus 

func (a *Agent) SetEventBus(bus *EventBus)

SetEventBus replaces the agent's event bus (used by sub-agents to forward events to a parent's bus). The agent will not close a bus it did not create.

func (*Agent) SetFastMode 

func (a *Agent) SetFastMode(enabled bool)

SetFastMode enables or disables priority/low-latency API processing.

func (*Agent) SetThinkingConfig 

func (a *Agent) SetThinkingConfig(tc *ThinkingConfig)

SetThinkingConfig updates thinking/reasoning configuration at runtime.

func (*Agent) State 

func (a *Agent) State() *AgentState

func (*Agent) Steer 

func (a *Agent) Steer(msg Message)

Steer injects a message that will be picked up before the next LLM call. Use this to redirect or interrupt the agent mid-conversation.

func (*Agent) ToolNames 

func (a *Agent) ToolNames() []string

func (*Agent) UnregisterTools 

func (a *Agent) UnregisterTools(names ...string)

type AgentEndEvent 

type AgentEndEvent struct {
	AgentName string `json:"agent_name,omitempty"`
	Output    string `json:"output"`
	// contains filtered or unexported fields
}

func (AgentEndEvent) EventKind 

func (e AgentEndEvent) EventKind() EventType

func (AgentEndEvent) EventTime 

func (e AgentEndEvent) EventTime() time.Time

type AgentErrorEvent 

type AgentErrorEvent struct {
	Err error `json:"error"`
	// contains filtered or unexported fields
}

func (AgentErrorEvent) EventKind 

func (e AgentErrorEvent) EventKind() EventType

func (AgentErrorEvent) EventTime 

func (e AgentErrorEvent) EventTime() time.Time

func (AgentErrorEvent) MarshalJSON 

func (e AgentErrorEvent) MarshalJSON() ([]byte, error)

func (*AgentErrorEvent) UnmarshalJSON 

func (e *AgentErrorEvent) UnmarshalJSON(data []byte) error

type AgentInterruptEvent added in v1.0.1 

type AgentInterruptEvent struct {
	AgentName string           `json:"agent_name,omitempty"`
	Reason    *InterruptReason `json:"reason,omitempty"`
	// contains filtered or unexported fields
}

func (AgentInterruptEvent) EventKind added in v1.0.1 

func (e AgentInterruptEvent) EventKind() EventType

func (AgentInterruptEvent) EventTime added in v1.0.1 

func (e AgentInterruptEvent) EventTime() time.Time

type AgentRunContext 

type AgentRunContext struct {
	Agent    *Agent
	Input    string
	Messages []Message
	Turn     int64
}

AgentRunContext carries context through the agent lifecycle.

type AgentStartEvent 

type AgentStartEvent struct {
	AgentName string `json:"agent_name,omitempty"`
	Input     string `json:"input,omitempty"`
	// contains filtered or unexported fields
}

func (AgentStartEvent) EventKind 

func (e AgentStartEvent) EventKind() EventType

func (AgentStartEvent) EventTime 

func (e AgentStartEvent) EventTime() time.Time

type AgentState 

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

AgentState holds the mutable conversation state across turns.

func NewState 

func NewState() *AgentState

func (*AgentState) AddMessage 

func (s *AgentState) AddMessage(m Message)

func (*AgentState) AddUsage 

func (s *AgentState) AddUsage(usage TokenUsage)

AddUsage accumulates token usage across turns.

func (*AgentState) ClearInterruptReason added in v1.0.1 

func (s *AgentState) ClearInterruptReason()

ClearInterruptReason removes the interrupt reason.

func (*AgentState) ClearPendingHandoff 

func (s *AgentState) ClearPendingHandoff()

func (*AgentState) GetInterruptReason added in v1.0.1 

func (s *AgentState) GetInterruptReason() *InterruptReason

GetInterruptReason returns the interrupt reason, if any.

func (*AgentState) HasSystemPrompt 

func (s *AgentState) HasSystemPrompt() bool

HasSystemPrompt returns true if the conversation history already contains a system prompt message. Used by Agent.Run to avoid appending duplicate system prompts when reusing an agent across multiple calls.

func (*AgentState) MarshalJSON 

func (s *AgentState) MarshalJSON() ([]byte, error)

func (*AgentState) Messages 

func (s *AgentState) Messages() []Message

func (*AgentState) NextTurn 

func (s *AgentState) NextTurn() int64

func (*AgentState) PendingHandoff 

func (s *AgentState) PendingHandoff() *PendingHandoff

func (*AgentState) ReplaceMessages 

func (s *AgentState) ReplaceMessages(msgs []Message)

ReplaceMessages atomically replaces the entire message history. Used by compaction to swap old messages with a summary.

func (*AgentState) Restore 

func (s *AgentState) Restore(snap StateSnapshot)

func (*AgentState) SetInterruptReason added in v1.0.1 

func (s *AgentState) SetInterruptReason(r *InterruptReason)

SetInterruptReason records why the agent was interrupted.

func (*AgentState) SetPendingHandoff 

func (s *AgentState) SetPendingHandoff(h *PendingHandoff)

func (*AgentState) SetStatus 

func (s *AgentState) SetStatus(st Status)

func (*AgentState) Snapshot 

func (s *AgentState) Snapshot() StateSnapshot

func (*AgentState) Status 

func (s *AgentState) Status() Status

func (*AgentState) TotalUsage 

func (s *AgentState) TotalUsage() TokenUsage

TotalUsage returns the accumulated token usage across all turns.

func (*AgentState) Turn 

func (s *AgentState) Turn() int64

func (*AgentState) UnmarshalJSON 

func (s *AgentState) UnmarshalJSON(data []byte) error

type Artifact added in v1.0.3 

type Artifact struct {
	ID        string            `json:"id"`
	Content   []byte            `json:"content"`
	Metadata  map[string]string `json:"metadata,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
}

type ArtifactOffloadConfig added in v1.0.3 

type ArtifactOffloadConfig struct {
	Store        ArtifactStore
	MinBytes     int
	ExcludeTools []string
}

type ArtifactStore added in v1.0.3 

type ArtifactStore interface {
	Put(ctx context.Context, artifact Artifact) (Artifact, error)
	Get(ctx context.Context, id string) (Artifact, error)
}

type AuditHook 

type AuditHook struct {
	BaseLifecycleHook
	OnEvent func(phase string, detail map[string]any)
}

AuditHook logs every phase transition for compliance/debugging.

func (*AuditHook) AfterAgentRun 

func (a *AuditHook) AfterAgentRun(_ context.Context, _ *AgentRunContext, output string, err error)

func (*AuditHook) AfterMessagePersist 

func (a *AuditHook) AfterMessagePersist(_ context.Context, _ *AgentRunContext, msg Message)

func (*AuditHook) AfterModelCall 

func (a *AuditHook) AfterModelCall(_ context.Context, _ *AgentRunContext, mcc *ModelCallContext)

func (*AuditHook) AfterToolExecution 

func (a *AuditHook) AfterToolExecution(_ context.Context, _ *AgentRunContext, tec *ToolExecutionContext)

func (*AuditHook) AfterTurn 

func (a *AuditHook) AfterTurn(_ context.Context, arc *AgentRunContext, info TurnInfo)

func (*AuditHook) BeforeAgentRun 

func (a *AuditHook) BeforeAgentRun(_ context.Context, arc *AgentRunContext) error

func (*AuditHook) BeforeMessagePersist 

func (a *AuditHook) BeforeMessagePersist(_ context.Context, _ *AgentRunContext, msg *Message) error

func (*AuditHook) BeforeModelCall 

func (a *AuditHook) BeforeModelCall(_ context.Context, arc *AgentRunContext, _ *ModelCallContext) error

func (*AuditHook) BeforeToolExecution 

func (a *AuditHook) BeforeToolExecution(_ context.Context, _ *AgentRunContext, tec *ToolExecutionContext) error

func (*AuditHook) BeforeTurn 

func (a *AuditHook) BeforeTurn(_ context.Context, arc *AgentRunContext) error

type AutoRetryEvent 

type AutoRetryEvent struct {
	Attempt    int64         `json:"attempt"`
	MaxRetries int64         `json:"max_retries"`
	Delay      time.Duration `json:"delay"`
	Err        error         `json:"error"`
	// contains filtered or unexported fields
}

func (AutoRetryEvent) EventKind 

func (e AutoRetryEvent) EventKind() EventType

func (AutoRetryEvent) EventTime 

func (e AutoRetryEvent) EventTime() time.Time

func (AutoRetryEvent) MarshalJSON 

func (e AutoRetryEvent) MarshalJSON() ([]byte, error)

func (*AutoRetryEvent) UnmarshalJSON 

func (e *AutoRetryEvent) UnmarshalJSON(data []byte) error

type BaseLifecycleHook 

type BaseLifecycleHook struct{}

BaseLifecycleHook provides no-op defaults so implementations can override only the hooks they care about.

func (BaseLifecycleHook) AfterAgentRun 

func (BaseLifecycleHook) AfterAgentRun(_ context.Context, _ *AgentRunContext, _ string, _ error)

func (BaseLifecycleHook) AfterMessagePersist 

func (BaseLifecycleHook) AfterMessagePersist(_ context.Context, _ *AgentRunContext, _ Message)

func (BaseLifecycleHook) AfterModelCall 

func (BaseLifecycleHook) AfterModelCall(_ context.Context, _ *AgentRunContext, _ *ModelCallContext)

func (BaseLifecycleHook) AfterToolExecution 

func (BaseLifecycleHook) AfterToolExecution(_ context.Context, _ *AgentRunContext, _ *ToolExecutionContext)

func (BaseLifecycleHook) AfterTurn 

func (BaseLifecycleHook) AfterTurn(_ context.Context, _ *AgentRunContext, _ TurnInfo)

func (BaseLifecycleHook) BeforeAgentRun 

func (BaseLifecycleHook) BeforeAgentRun(_ context.Context, _ *AgentRunContext) error

func (BaseLifecycleHook) BeforeMessagePersist 

func (BaseLifecycleHook) BeforeMessagePersist(_ context.Context, _ *AgentRunContext, _ *Message) error

func (BaseLifecycleHook) BeforeModelCall 

func (BaseLifecycleHook) BeforeModelCall(_ context.Context, _ *AgentRunContext, _ *ModelCallContext) error

func (BaseLifecycleHook) BeforeToolExecution 

func (BaseLifecycleHook) BeforeToolExecution(_ context.Context, _ *AgentRunContext, _ *ToolExecutionContext) error

func (BaseLifecycleHook) BeforeTurn 

func (BaseLifecycleHook) BeforeTurn(_ context.Context, _ *AgentRunContext) error

type BeforeHook 

type BeforeHook func(ctx context.Context, hc *HookContext) error

BeforeHook runs before tool execution. Return a non-nil error to reject the call.

func LoggingBeforeHook 

func LoggingBeforeHook(logger *slog.Logger) BeforeHook

LoggingBeforeHook logs tool call start via slog.

func RateLimitBeforeHook 

func RateLimitBeforeHook(maxCalls int64, interval time.Duration) BeforeHook

RateLimitBeforeHook rejects tool calls that exceed maxCalls within the given interval.

type BlockKind 

type BlockKind string

BlockKind classifies a segment of assistant (or user) content. 

const (
	// BlockKindText is ordinary visible text.
	BlockKindText BlockKind = "text"
	// BlockKindThinking is model reasoning / chain-of-thought (often hidden from tools).
	BlockKindThinking BlockKind = "thinking"
	// BlockKindImage is an image input such as an HTTPS URL or data URL.
	BlockKindImage BlockKind = "image"
	// BlockKindToolCall is a structured tool call emitted by the assistant.
	BlockKindToolCall BlockKind = "tool_call"
)

type CacheControlMarker 

type CacheControlMarker struct {
	Type string `json:"type"`
	TTL  string `json:"ttl,omitempty"`
}

CacheControlMarker represents an Anthropic cache_control breakpoint for prompt caching. It is placed on messages to mark them as cacheable, which can reduce token costs by ~75%.

type CallConfig 

type CallConfig struct {
	Model          string          `json:"model,omitempty"`
	ResponseFormat *ResponseFormat `json:"response_format,omitempty"`
	Thinking       *ThinkingConfig `json:"thinking,omitempty"`
	Skills         []string        `json:"skills,omitempty"`
}

CallConfig is a reusable subset of per-call agent/provider options that can be applied as defaults, persisted per-thread, or overridden per request.

func CloneCallConfig 

func CloneCallConfig(c *CallConfig) *CallConfig

func MergeCallConfig 

func MergeCallConfig(base, override *CallConfig) *CallConfig

MergeCallConfig overlays non-zero fields from override onto base.

type CheckpointSaver 

type CheckpointSaver interface {
	// Append stores a snapshot for threadID and returns a monotonically increasing
	// sequence number for that thread.
	Append(ctx context.Context, threadID string, snap StateSnapshot) (seq int64, err error)
	// Latest returns the most recent snapshot and its sequence number.
	Latest(ctx context.Context, threadID string) (snap StateSnapshot, seq int64, err error)
}

CheckpointSaver persists StateSnapshot sequences for a logical thread (conversation). Implementations must be safe for concurrent use if agents share a saver.

type CheckpointSettings 

type CheckpointSettings struct {
	Saver CheckpointSaver
	// ThreadID logical conversation key; empty defaults to "default" at save time.
	ThreadID string
	// SkipSaveOnTurnEnd disables automatic append after each turn end.
	SkipSaveOnTurnEnd bool
	// SaveOnTurnStart appends a snapshot before each LLM call (after steering/compaction).
	SaveOnTurnStart bool
	// Migrators upgrades older snapshots during RestoreLatestCheckpoint. Keys
	// are source versions and each migrator advances one schema version.
	Migrators map[int]StateSnapshotMigrator
}

CheckpointSettings configures automatic checkpointing during Run/Continue. When Saver is non-nil, by default a checkpoint is written after each completed turn (after model + optional tool persistence). Set SkipSaveOnTurnEnd to rely only on SaveOnTurnStart and/or Agent.SaveCheckpoint.

type CollectRunnable 

type CollectRunnable[I, O any] struct {
	CollectFn func(ctx context.Context, input *StreamReader[I]) (O, error)
}

func (*CollectRunnable[I, O]) Collect 

func (r *CollectRunnable[I, O]) Collect(ctx context.Context, input *StreamReader[I]) (O, error)

func (*CollectRunnable[I, O]) Invoke 

func (r *CollectRunnable[I, O]) Invoke(ctx context.Context, input I) (O, error)

func (*CollectRunnable[I, O]) Stream 

func (r *CollectRunnable[I, O]) Stream(ctx context.Context, input I) (*StreamReader[O], error)

func (*CollectRunnable[I, O]) Transform 

func (r *CollectRunnable[I, O]) Transform(ctx context.Context, input *StreamReader[I]) (*StreamReader[O], error)

type CompactionConfig 

type CompactionConfig struct {
	ContextWindow         int64         // model context window size in tokens (e.g. 128000); 0 = no compaction
	ReserveTokens         int64         // tokens reserved for response generation; default = ContextWindow/4
	KeepRecentTokens      int64         // min recent tokens preserved during compaction; default = 2000
	StructuredCompaction  bool          // emit JSON summaries instead of free-form paragraphs
	ProtectFirstN         int           // number of non-system head messages to preserve verbatim; default = 3
	CompressionThreshold  float64       // compress when usage exceeds this fraction of contextWindow; default = 0.75
	AutoCompactTokenLimit int64         // absolute token threshold (overrides CompressionThreshold when > 0); default = 0
	AntiThrashEnabled     bool          // skip compaction if recent savings < 10%; default = true
	CompressionModel      string        // optional: separate model for summarization (cheaper/faster)
	CompressionProvider   Provider      // optional: provider for compression model
	CompressionBaseURL    string        // optional: base URL for compression model
	CompressionAPIKey     string        // optional: API key for compression model
	Engine                string        // context engine name; default = "compressor"
	CustomEngine          ContextEngine // pre-built custom engine (overrides Engine name)
}

CompactionConfig groups context window management and compaction behavior.

type CompactionEndEvent 

type CompactionEndEvent struct {
	TokensBefore int64         `json:"tokens_before"`
	TokensAfter  int64         `json:"tokens_after"`
	MessagesCut  int64         `json:"messages_cut"`
	Duration     time.Duration `json:"duration"`
	// contains filtered or unexported fields
}

func (CompactionEndEvent) EventKind 

func (e CompactionEndEvent) EventKind() EventType

func (CompactionEndEvent) EventTime 

func (e CompactionEndEvent) EventTime() time.Time

type CompactionStartEvent 

type CompactionStartEvent struct {
	TokensBefore  int64 `json:"tokens_before"`
	ContextWindow int64 `json:"context_window"`
	// contains filtered or unexported fields
}

func (CompactionStartEvent) EventKind 

func (e CompactionStartEvent) EventKind() EventType

func (CompactionStartEvent) EventTime 

func (e CompactionStartEvent) EventTime() time.Time

type CompressorEngine 

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

CompressorEngine is the built-in context engine — compresses conversation context via lossy LLM summarization.

func (*CompressorEngine) CheckFeasibility 

func (e *CompressorEngine) CheckFeasibility(mainModelContextLength int64) string

CheckFeasibility validates that the compression model's context window is sufficient for summarization. Returns a warning message if issues found.

func (*CompressorEngine) Compress 

func (e *CompressorEngine) Compress(ctx context.Context, msgs []Message, focusTopic string) ([]Message, int64, error)

func (*CompressorEngine) CompressionCount 

func (e *CompressorEngine) CompressionCount() int64

func (*CompressorEngine) ContextLength 

func (e *CompressorEngine) ContextLength() int64

func (*CompressorEngine) GetToolSchemas 

func (e *CompressorEngine) GetToolSchemas() []ToolDefinition

func (*CompressorEngine) LastSavingsPct 

func (e *CompressorEngine) LastSavingsPct() float64

func (*CompressorEngine) Name 

func (e *CompressorEngine) Name() string

func (*CompressorEngine) OnSessionEnd 

func (e *CompressorEngine) OnSessionEnd()

func (*CompressorEngine) OnSessionReset 

func (e *CompressorEngine) OnSessionReset()

func (*CompressorEngine) OnSessionStart 

func (e *CompressorEngine) OnSessionStart(ctx context.Context, model string, contextLength int64)

func (*CompressorEngine) ShouldCompact 

func (e *CompressorEngine) ShouldCompact(msgs []Message, toolDefs []ToolDefinition, contextWindow int64) bool

func (*CompressorEngine) SummaryStats 

func (e *CompressorEngine) SummaryStats() map[string]any

SummaryStats returns detailed compression statistics for diagnostics.

func (*CompressorEngine) ThresholdTokens 

func (e *CompressorEngine) ThresholdTokens() int64

func (*CompressorEngine) UpdateFromResponse 

func (e *CompressorEngine) UpdateFromResponse(usage TokenUsage)

type Config 

type Config struct {
	ModelConfig
	SkillConfig
	ExecutionConfig
	CompactionConfig

	// Top-level agent configuration not belonging to a specific sub-config.
	Tools        []*Tool
	SystemPrompt string

	Store Store // optional: enables SaveState / LoadState
	// StateMigrators upgrades versioned snapshots loaded from Store or checkpoints.
	StateMigrators map[int]StateSnapshotMigrator
	// Checkpoint optional durable snapshots per thread (see CheckpointSettings).
	Checkpoint *CheckpointSettings

	Handoffs []HandoffConfig // optional: sub-agents reachable via handoff
	Tracer   Tracer          // optional: distributed tracing
	Metrics  Metrics         // optional: runtime metrics (token usage, errors)

	// LLM-level retry with exponential backoff.
	// Context overflow errors trigger compaction instead of retry.
	RetryConfig *RetryConfig

	// TransformContext is called before ConvertToLLM to filter/modify/inject messages.
	TransformContext func(ctx context.Context, msgs []Message) []Message

	// ConvertToLLM converts internal message types to standard LLM messages.
	// If nil, DefaultConvertToLLM is used which strips custom types.
	ConvertToLLM ConvertToLLMFunc

	// BeforeToolCall is invoked before each tool at the agent loop level.
	// Return non-nil ToolCallOverride with Block=true to skip the tool.
	BeforeToolCall func(ctx context.Context, tc ToolCall) *ToolCallOverride

	// AfterToolCall is invoked after each tool at the agent loop level.
	// It can modify the ToolResult before it's added to conversation messages.
	AfterToolCall func(ctx context.Context, tc ToolCall, result *ToolResult) *ToolResult

	// PostProcessResults is invoked after all tools in a turn have executed,
	// before results are persisted to conversation messages. It receives the
	// full batch of calls and results and can modify results in-place.
	// Use this for turn-level processing (e.g., output budget enforcement).
	PostProcessResults func(ctx context.Context, calls []ToolCall, results []ToolResult) []ToolResult

	// Extensions are registered during New() and contribute tools, hooks, etc.
	Extensions []Extension

	// Lifecycle hooks intercept every stage of agent execution.
	// Multiple hooks are composed via LifecycleChain.
	Lifecycle LifecycleHook

	// ArtifactOffload stores large tool results outside model history.
	ArtifactOffload *ArtifactOffloadConfig
}

Config defines the parameters for constructing an Agent.

Config is composed of embedded sub-configs that group related fields:

  • ModelConfig: LLM model selection and generation parameters
  • SkillConfig: skill loading, selection, and API control
  • ExecutionConfig: execution mode, concurrency, middleware, and hooks
  • CompactionConfig: context window management and compaction behavior

Because sub-configs are embedded, fields are promoted to the top level: you can access c.Model or c.ModelConfig.Model interchangeably. Both struct literal construction and functional options (NewConfig) are supported.

func ApplyModelProfile added in v1.0.2 

func ApplyModelProfile(cfg Config) Config

ApplyModelProfile applies any registered profile for cfg.Model to cfg and returns the resulting Config. Called automatically by New(); exposed publicly so callers can preview the effective configuration.

Precedence rules:

  • SystemPromptSuffix: always appended (additive, never overwrites).
  • ExcludedTools: always removed from cfg.Tools.
  • Temperature: applied only when cfg.Temperature == 0.
  • MaxTurns: applied only when cfg.MaxTurns <= 0.

Limitation: profiles are applied once during New(). Changing Config.Model later (e.g. via Agent.ApplyCallConfig for a thread-level model override) does NOT re-apply the new model's profile. Callers that switch models at runtime and need profile adjustments should construct a fresh Agent, or call ApplyModelProfile manually and apply the resulting field changes.

func NewConfig 

func NewConfig(opts ...ConfigOption) Config

NewConfig creates a Config with the given options applied. Zero-value defaults are used for any unset fields; MaxTurns defaults to 20 when the Config is passed to New().

func StubConfig 

func StubConfig(p Provider, opts ...ConfigOption) Config

StubConfig returns a minimal Config suitable for tests. It sets Model="stub" and Provider=p, which are the most common test setup.

type ConfigOption 

type ConfigOption func(*Config)

ConfigOption is a functional option for constructing a Config.

func WithAfterToolCall 

func WithAfterToolCall(fn func(ctx context.Context, tc ToolCall, result *ToolResult) *ToolResult) ConfigOption

WithAfterToolCall sets the after-tool-call hook.

func WithAntiThrash 

func WithAntiThrash(enabled bool) ConfigOption

WithAntiThrash enables/disables anti-thrashing protection.

func WithArtifactOffload added in v1.0.3 

func WithArtifactOffload(cfg *ArtifactOffloadConfig) ConfigOption

WithArtifactOffload enables automatic offloading of large tool results.

func WithAvailableSkills 

func WithAvailableSkills(skills []skill.Skill) ConfigOption

WithAvailableSkills sets the available skills.

func WithBeforeToolCall 

func WithBeforeToolCall(fn func(ctx context.Context, tc ToolCall) *ToolCallOverride) ConfigOption

WithBeforeToolCall sets the before-tool-call hook.

func WithCheckpoint 

func WithCheckpoint(cs *CheckpointSettings) ConfigOption

WithCheckpoint sets the checkpoint settings.

func WithCompactionConfig 

func WithCompactionConfig(cc CompactionConfig) ConfigOption

WithCompactionConfig applies a full CompactionConfig.

func WithCompressionModel 

func WithCompressionModel(model string, provider Provider, baseURL string, apiKey string) ConfigOption

WithCompressionModel sets a separate model for context compression.

func WithCompressionThreshold 

func WithCompressionThreshold(ratio float64) ConfigOption

WithCompressionThreshold sets the compression trigger threshold.

func WithConcurrency 

func WithConcurrency(n int64) ConfigOption

WithConcurrency sets the max concurrent tool calls.

func WithContextEngine 

func WithContextEngine(name string) ConfigOption

WithContextEngine sets the context engine name.

func WithContextWindow 

func WithContextWindow(tokens int64) ConfigOption

WithContextWindow sets the context window size for auto-compaction.

func WithConvertToLLM 

func WithConvertToLLM(fn ConvertToLLMFunc) ConfigOption

WithConvertToLLM sets the message converter.

func WithCustomContextEngine 

func WithCustomContextEngine(engine ContextEngine) ConfigOption

WithCustomContextEngine sets a pre-built custom context engine.

func WithDisableSkillRegistryAPI 

func WithDisableSkillRegistryAPI(disabled bool) ConfigOption

WithDisableSkillRegistryAPI disables the skill registry HTTP API.

func WithDisableSkillReloadAPI 

func WithDisableSkillReloadAPI(disabled bool) ConfigOption

WithDisableSkillReloadAPI disables the skill reload HTTP API.

func WithExecutionConfig 

func WithExecutionConfig(ec ExecutionConfig) ConfigOption

WithExecutionConfig applies a full ExecutionConfig.

func WithExecutionMode 

func WithExecutionMode(m ExecutionMode) ConfigOption

WithExecutionMode sets the execution mode (serial or parallel).

func WithExtensions 

func WithExtensions(exts ...Extension) ConfigOption

WithExtensions sets the extensions.

func WithFastMode 

func WithFastMode(enabled bool) ConfigOption

WithFastMode enables/disables priority/low-latency API processing.

func WithFollowUpMode 

func WithFollowUpMode(m SteeringMode) ConfigOption

WithFollowUpMode sets the follow-up message mode.

func WithFrequencyPenalty added in v1.0.2 

func WithFrequencyPenalty(p float64) ConfigOption

WithFrequencyPenalty sets the frequency penalty (reduces likelihood of repeating tokens that already appeared; helps mitigate degenerate repetition loops on providers that support it, e.g. OpenAI-compatible).

func WithGlobalAfter 

func WithGlobalAfter(hooks ...AfterHook) ConfigOption

WithGlobalAfter appends after-hooks.

func WithGlobalBefore 

func WithGlobalBefore(hooks ...BeforeHook) ConfigOption

WithGlobalBefore appends before-hooks.

func WithHandoffs 

func WithHandoffs(handoffs ...HandoffConfig) ConfigOption

WithHandoffs sets the handoff targets.

func WithKeepRecentTokens 

func WithKeepRecentTokens(tokens int64) ConfigOption

WithKeepRecentTokens sets the minimum recent tokens to preserve.

func WithLifecycle 

func WithLifecycle(hook LifecycleHook) ConfigOption

WithLifecycle sets the lifecycle hook.

func WithMaxTokens 

func WithMaxTokens(n int64) ConfigOption

WithMaxTokens sets the maximum response tokens.

func WithMaxTurns 

func WithMaxTurns(n int64) ConfigOption

WithMaxTurns sets the maximum agent loop turns.

func WithMiddleware 

func WithMiddleware(mw ...Middleware) ConfigOption

WithMiddleware appends middleware to the execution chain.

func WithModel 

func WithModel(model string) ConfigOption

WithModel sets the model identifier.

func WithModelConfig 

func WithModelConfig(mc ModelConfig) ConfigOption

WithModelConfig applies a full ModelConfig.

func WithModelFailover added in v1.0.3 

func WithModelFailover(cfg *ModelFailoverConfig) ConfigOption

WithModelFailover configures provider/model fallback behavior.

func WithName 

func WithName(name string) ConfigOption

WithName sets the agent name.

func WithPresencePenalty added in v1.0.2 

func WithPresencePenalty(p float64) ConfigOption

WithPresencePenalty sets the presence penalty (discourages reusing any token that has appeared at all, regardless of frequency).

func WithProtectFirstN 

func WithProtectFirstN(n int) ConfigOption

WithProtectFirstN sets the number of head messages to preserve.

func WithProvider 

func WithProvider(p Provider) ConfigOption

WithProvider sets the LLM provider.

func WithReserveTokens 

func WithReserveTokens(tokens int64) ConfigOption

WithReserveTokens sets the tokens reserved for response generation.

func WithResponseFormat 

func WithResponseFormat(rf *ResponseFormat) ConfigOption

WithResponseFormat sets the response format.

func WithRetryConfig 

func WithRetryConfig(rc *RetryConfig) ConfigOption

WithRetryConfig sets the retry configuration.

func WithSelectedSkills 

func WithSelectedSkills(names []string) ConfigOption

WithSelectedSkills sets the selected skill names.

func WithSkillAPIAuthToken 

func WithSkillAPIAuthToken(token string) ConfigOption

WithSkillAPIAuthToken sets the API auth token for skill endpoints.

func WithSkillConfig 

func WithSkillConfig(sc SkillConfig) ConfigOption

WithSkillConfig applies a full SkillConfig.

func WithSkillDiagnostics 

func WithSkillDiagnostics(diags []skill.Diagnostic) ConfigOption

WithSkillDiagnostics sets pre-loaded skill diagnostics.

func WithSkillPaths 

func WithSkillPaths(paths []string) ConfigOption

WithSkillPaths sets the skill directory paths for hot-reload.

func WithStateMigrators added in v1.0.3 

func WithStateMigrators(migrators map[int]StateSnapshotMigrator) ConfigOption

WithStateMigrators configures schema migrations for snapshots loaded from either Store or CheckpointSaver.

func WithSteeringMode 

func WithSteeringMode(m SteeringMode) ConfigOption

WithSteeringMode sets the steering message mode.

func WithStore 

func WithStore(s Store) ConfigOption

WithStore sets the persistence store.

func WithStreaming 

func WithStreaming(enabled bool) ConfigOption

WithStreaming enables or disables streaming.

func WithStructuredCompaction 

func WithStructuredCompaction(enabled bool) ConfigOption

WithStructuredCompaction enables structured JSON compaction summaries.

func WithSystemPrompt 

func WithSystemPrompt(prompt string) ConfigOption

WithSystemPrompt sets the system prompt.

func WithTemperature 

func WithTemperature(temp float64) ConfigOption

WithTemperature sets the sampling temperature.

func WithThinking 

func WithThinking(tc *ThinkingConfig) ConfigOption

WithThinking sets the thinking/reasoning config.

func WithToolSelection added in v1.0.3 

func WithToolSelection(cfg *ToolSelectionConfig) ConfigOption

WithToolSelection enables dynamic per-request tool visibility.

func WithTools 

func WithTools(tools ...*Tool) ConfigOption

WithTools sets the agent's tools.

func WithTracer 

func WithTracer(t Tracer) ConfigOption

WithTracer sets the distributed tracer.

func WithTransformContext 

func WithTransformContext(fn func(ctx context.Context, msgs []Message) []Message) ConfigOption

WithTransformContext sets the context transform function.

func WithValidateArguments 

func WithValidateArguments(enabled bool) ConfigOption

WithValidateArguments enables JSON Schema validation of tool arguments.

type ContentBlock 

type ContentBlock struct {
	Kind       BlockKind `json:"kind"`
	Text       string    `json:"text,omitempty"`
	URL        string    `json:"url,omitempty"`
	MediaType  string    `json:"media_type,omitempty"`
	Detail     string    `json:"detail,omitempty"`
	Signature  string    `json:"signature,omitempty"`
	ToolCallID string    `json:"tool_call_id,omitempty"`
	Name       string    `json:"name,omitempty"`
	Arguments  string    `json:"arguments,omitempty"`
}

ContentBlock is one segment inside a message body (multi-block messages). DefaultConvertToLLM collapses text/thinking blocks into Content for providers that only support strings, while preserving richer blocks like images for providers that can send native multipart content.

func MergeContentBlocks 

func MergeContentBlocks(dst []ContentBlock, src ...ContentBlock) []ContentBlock

MergeContentBlocks appends blocks while coalescing adjacent text/thinking segments so streaming providers do not produce one block per token chunk.

type ContextEngine 

type ContextEngine interface {
	// Name returns the engine identifier (e.g. "compressor", "lcm").
	Name() string

	// OnSessionStart initializes per-session state.
	OnSessionStart(ctx context.Context, model string, contextLength int64)

	// OnSessionReset clears all per-session state for /new or /reset.
	OnSessionReset()

	// OnSessionEnd is called at session termination.
	OnSessionEnd()

	// UpdateFromResponse updates tracked token usage from an API response.
	UpdateFromResponse(usage TokenUsage)

	// ShouldCompact returns true if compaction should fire this turn.
	ShouldCompact(msgs []Message, toolDefs []ToolDefinition, contextWindow int64) bool

	// Compress compacts the message list and returns the new message list.
	// focusTopic is optional for guided topic-focused compression.
	Compress(ctx context.Context, msgs []Message, focusTopic string) ([]Message, int64, error)

	// GetToolSchemas returns optional tool definitions the engine exposes
	// (e.g. lcm_grep for LCM engines). Most engines return nil.
	GetToolSchemas() []ToolDefinition

	// ContextLength returns the model's context window size.
	ContextLength() int64

	// ThresholdTokens returns the token count at which compression triggers.
	ThresholdTokens() int64

	// CompressionCount returns the number of successful compressions.
	CompressionCount() int64

	// LastSavingsPct returns the savings percentage of the last compression.
	LastSavingsPct() float64

	// CheckFeasibility validates that the compression model can handle
	// summarization. Returns a warning message if issues found, empty string otherwise.
	CheckFeasibility(mainModelContextLength int64) string
}

ContextEngine controls how conversation context is managed when approaching the model's token limit. The built-in CompressorEngine is the default implementation. Third-party engines can replace it via the plugin registry.

Lifecycle:

  1. Engine is registered (plugin or default)
  2. OnSessionStart called when a conversation begins
  3. UpdateFromResponse called after each API response with usage data
  4. ShouldCompact checked after each turn
  5. Compress called when ShouldCompact returns true
  6. OnSessionEnd called at real session boundaries (CLI exit, /reset, gateway session expiry) — NOT per-turn

func NewCompressorEngine 

func NewCompressorEngine(cfg ContextEngineConfig) ContextEngine

NewCompressorEngine creates the built-in compressor engine.

func NewTruncateEngine 

func NewTruncateEngine(cfg ContextEngineConfig) ContextEngine

NewTruncateEngine creates a truncate-only context engine.

type ContextEngineConfig 

type ContextEngineConfig struct {
	Model                string
	BaseURL              string
	APIKey               string
	Provider             Provider
	ContextWindow        int64
	ReserveTokens        int64
	KeepRecentTokens     int64
	ProtectFirstN        int
	CompressionThreshold float64
	AutoCompactLimit     int64
	StructuredCompaction bool
	CompressionModel     string
	CompressionProvider  Provider
	CompressionBaseURL   string
	CompressionAPIKey    string
}

ContextEngineConfig holds configuration for context engine initialization.

type ContextEngineFactory 

type ContextEngineFactory func(cfg ContextEngineConfig) ContextEngine

ContextEngineFactory creates a ContextEngine from configuration.

type ConvertToLLMFunc 

type ConvertToLLMFunc func(msgs []Message) []Message

ConvertToLLMFunc transforms internal messages into the format expected by the provider. It should filter out UI-only messages, convert custom types to standard roles, etc.

type DualToolOutput 

type DualToolOutput struct {
	ForLLM  string `json:"for_llm"`
	ForUser string `json:"for_user"`
	Silent  bool   `json:"silent,omitempty"`
}

DualToolOutput wraps a tool result with separate output for LLM and user.

func NewToolResult 

func NewToolResult(forLLM string) *DualToolOutput

NewToolResult creates a result visible to both LLM and user.

func SilentResult 

func SilentResult(forLLM string) *DualToolOutput

SilentResult creates a result visible only to the LLM (not shown to user).

func UserResult 

func UserResult(content string) *DualToolOutput

UserResult creates a result visible to both LLM and user.

type EmbeddingFunc added in v1.0.3 

type EmbeddingFunc func(ctx context.Context, texts []string) ([][]float64, error)

EmbeddingFunc returns one vector per input text.

type EmbeddingToolSelector added in v1.0.3 

type EmbeddingToolSelector struct {
	Embed           EmbeddingFunc
	MinScore        float64
	Fallback        ToolSelector
	MaxCacheEntries int
	// contains filtered or unexported fields
}

EmbeddingToolSelector performs semantic tool retrieval and caches vectors for unchanged tool definitions. Fallback is used when embedding fails.

func (*EmbeddingToolSelector) SelectTools added in v1.0.3 

func (selector *EmbeddingToolSelector) SelectTools(ctx context.Context, selection ToolSelectionContext) ([]string, error)

type EngineNotFoundError 

type EngineNotFoundError struct {
	Name string
}

EngineNotFoundError is returned when a requested engine is not registered.

func (*EngineNotFoundError) Error 

func (e *EngineNotFoundError) Error() string

type EngineRegistry 

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

EngineRegistry manages registered context engine factories.

func NewEngineRegistry 

func NewEngineRegistry() *EngineRegistry

NewEngineRegistry creates a new registry with the built-in compressor as default.

func (*EngineRegistry) Create 

func (r *EngineRegistry) Create(name string, cfg ContextEngineConfig) (ContextEngine, error)

Create instantiates a context engine by name.

func (*EngineRegistry) Default 

func (r *EngineRegistry) Default() string

Default returns the default engine name.

func (*EngineRegistry) List 

func (r *EngineRegistry) List() []string

List returns all registered engine names.

func (*EngineRegistry) Register 

func (r *EngineRegistry) Register(name string, factory ContextEngineFactory)

Register adds a context engine factory.

type Event 

type Event interface {
	EventKind() EventType
	EventTime() time.Time
}

Event is the common interface for all agent lifecycle events.

func WithEventRunInfo added in v1.0.3 

func WithEventRunInfo(event Event, info RunInfo) Event

WithEventRunInfo attaches a defensive copy of execution metadata to a framework event. Events not implemented by agentcore are returned unchanged.

type EventBus 

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

EventBus provides async pub/sub for agent lifecycle events. Events are dispatched via a buffered channel to avoid blocking the agent loop. Event ordering is preserved — a single goroutine processes events sequentially.

Handlers are keyed by a monotonic ID so they can be removed individually (Go func values can't be compared with ==). This matters for long-lived agents whose EventBus is reused across requests: a per-request handler (e.g. an SSE writer closure) must be unregistered when the request ends, otherwise it leaks and keeps writing to a stale sink on subsequent requests.

func NewEventBus 

func NewEventBus() *EventBus

func (*EventBus) Close 

func (eb *EventBus) Close()

Close shuts down the event bus. All queued events are processed before Close returns.

func (*EventBus) Drain 

func (eb *EventBus) Drain()

Drain blocks until all currently queued events have been processed. If the channel buffer is full, it spins briefly to ensure the sentinel is eventually enqueued rather than blocking the caller indefinitely. If the EventBus has been closed, Drain returns immediately without panic.

func (*EventBus) Emit 

func (eb *EventBus) Emit(e Event)

Emit dispatches an event to the async processing goroutine. Non-blocking: if the buffer is full the event is dropped to avoid blocking the caller (typically the agent main loop). Dropped events are preferable to a stalled agent — consumers that need guaranteed delivery should use a persistent store or checkpoint mechanism instead.

func (*EventBus) On 

func (eb *EventBus) On(t EventType, h EventHandler) func()

On registers a handler for a specific event type and returns a function that removes the handler when called. Callers that attach scoped handlers (e.g. per-request SSE writers on a long-lived agent) MUST invoke the returned function when their scope ends — otherwise the handler stays registered on a reused agent and leaks, writing to a dead/stale sink.

func (*EventBus) OnAll 

func (eb *EventBus) OnAll(h EventHandler) func()

OnAll registers a handler that receives every event and returns a function that removes the handler when called. See On for the scoping contract.

type EventHandler 

type EventHandler func(Event)

EventHandler is a callback invoked when an event is emitted.

type EventSnapshotProvider 

type EventSnapshotProvider interface {
	SnapshotEvents() []Event
}

EventSnapshotProvider is an optional interface extensions can implement to expose their current state as events for newly attached listeners.

type EventType 

type EventType string
const (
	EventAgentStart         EventType = "agent_start"
	EventAgentEnd           EventType = "agent_end"
	EventAgentError         EventType = "agent_error"
	EventSkillLoaded        EventType = "skill_loaded"
	EventSkillsReloaded     EventType = "skills_reloaded"
	EventTurnStart          EventType = "turn_start"
	EventTurnEnd            EventType = "turn_end"
	EventMessageDelta       EventType = "message_delta"
	EventMessageReset       EventType = "message_reset"
	EventModelFailover      EventType = "model_failover"
	EventToolCallStart      EventType = "tool_call_start"
	EventToolCallEnd        EventType = "tool_call_end"
	EventHandoffStart       EventType = "handoff_start"
	EventHandoffEnd         EventType = "handoff_end"
	EventCompactionStart    EventType = "compaction_start"
	EventCompactionEnd      EventType = "compaction_end"
	EventAutoRetry          EventType = "auto_retry"
	EventAgentInterrupt     EventType = "agent_interrupt"
	EventRepetitionRecovery EventType = "repetition_recovery"
)

type ExecuteCallbacks 

type ExecuteCallbacks struct {
	OnStart func(tc ToolCall)
	OnEnd   func(result ToolResult)
}

ExecuteCallbacks provides optional real-time notifications during ExecuteAll.

type ExecuteFunc 

type ExecuteFunc func(ctx context.Context, tc ToolCall) (string, error)

ExecuteFunc is the signature for a single tool execution step in the middleware chain.

type ExecutionConfig 

type ExecutionConfig struct {
	ExecutionMode      ExecutionMode
	Concurrency        int64
	MaxTurns           int64
	Middleware         []Middleware
	GlobalBefore       []BeforeHook
	GlobalAfter        []AfterHook
	ValidateArguments  bool
	UnknownToolHandler UnknownToolHandler
	SteeringMode       SteeringMode // default: SteeringAll
	FollowUpMode       SteeringMode // default: SteeringAll

	// RepetitionRecovery controls the soft repetition-loop recovery ladder
	// (nudge, then escalate, then give up) used by runLoop when a
	// degeneration/repetition loop is detected. nil uses built-in defaults
	// (MaxAttempts=2, English prompts).
	RepetitionRecovery *RepetitionRecoveryConfig

	// ArgumentRepairFunc is called when tool arguments contain invalid JSON.
	// It receives the raw arguments string and tool name, and should return
	// repaired JSON or the original string if no repair is possible.
	ArgumentRepairFunc func(rawArgs string, toolName string) string

	// ToolSelection limits the tool definitions exposed on each model request.
	// All registered tools remain available to the executor.
	ToolSelection *ToolSelectionConfig
}

ExecutionConfig groups execution mode, concurrency, middleware, and hooks.

type ExecutionMode 

type ExecutionMode string

ExecutionMode controls whether tool calls run serially or in parallel. 

const (
	ModeSerial   ExecutionMode = "serial"
	ModeParallel ExecutionMode = "parallel"
)

type Executor 

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

Executor dispatches tool calls against a Registry with hooks and middleware.

func NewExecutor 

func NewExecutor(registry *Registry, cfg ...ExecutorConfig) *Executor

func (*Executor) Execute 

func (e *Executor) Execute(ctx context.Context, tc ToolCall, state *AgentState) ToolResult

Execute runs a single tool call: tool-before → global-before → middleware chain → global-after → tool-after.

func (*Executor) ExecuteAll 

func (e *Executor) ExecuteAll(ctx context.Context, calls []ToolCall, state *AgentState, cb *ExecuteCallbacks) []ToolResult

ExecuteAll runs multiple tool calls using the configured execution mode, firing optional callbacks in real time for each tool.

type ExecutorConfig 

type ExecutorConfig struct {
	Mode               ExecutionMode
	Concurrency        int64 // max parallel goroutines; 0 = unlimited
	Middleware         []Middleware
	Before             []BeforeHook       // global before hooks applied to every tool
	After              []AfterHook        // global after hooks applied to every tool
	ValidateArguments  bool               // enable JSON Schema validation of tool arguments
	UnknownToolHandler UnknownToolHandler // called when the model hallucinates a tool name

	// ArgumentRepairFunc is called when tool arguments contain invalid JSON.
	// It receives the raw arguments string and tool name, and should return
	// repaired JSON or the original string if no repair is possible.
	// When set, repair is attempted before rejecting invalid JSON.
	ArgumentRepairFunc func(rawArgs string, toolName string) string
}

ExecutorConfig tunes how the executor dispatches tool calls.

type Extension 

type Extension interface {
	// Name returns a unique identifier for the extension.
	Name() string
	// Init is called once when the extension is registered with an agent.
	Init(ctx context.Context, agent *Agent) error
	// Dispose is called when the agent is shutting down or the extension is unloaded.
	Dispose() error
}

Extension is a plugin that can augment an agent with tools, hooks, and lifecycle callbacks.

func NewSkillExtension 

func NewSkillExtension(skills []skill.Skill, selected []string) Extension

NewSkillExtension exposes discovered skills to the model and expands selected or explicit skill invocations at request time.

type ExtensionRegistry 

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

ExtensionRegistry manages the lifecycle of extensions attached to an agent.

func NewExtensionRegistry 

func NewExtensionRegistry() *ExtensionRegistry

func (*ExtensionRegistry) Dispose 

func (r *ExtensionRegistry) Dispose() error

Dispose tears down all registered extensions in reverse order.

func (*ExtensionRegistry) Names 

func (r *ExtensionRegistry) Names() []string

Names returns the names of all registered extensions.

func (*ExtensionRegistry) Register 

func (r *ExtensionRegistry) Register(ctx context.Context, agent *Agent, exts ...Extension) error

Register adds extensions and immediately initializes them.

func (*ExtensionRegistry) SnapshotEvents 

func (r *ExtensionRegistry) SnapshotEvents() []Event

SnapshotEvents collects current-state events from extensions that expose them.

func (*ExtensionRegistry) Visit 

func (r *ExtensionRegistry) Visit(name string, fn func(Extension))

Visit calls fn for the extension with the given name.

type FileReader added in v1.0.2 

type FileReader interface {
	ReadFile(name string) ([]byte, error)
}

FileReader is the minimal file-reading interface used by RulesExtension. Inject a custom implementation to load rules from a sandbox, embedded data, or test fixtures instead of the local filesystem.

type GuardrailHook 

type GuardrailHook struct {
	BaseLifecycleHook
	Validate func(ctx context.Context, response *ProviderResponse) error
}

GuardrailHook validates model output before tool execution. If the validator returns an error, the model response is persisted (so it is not lost), then an error system message is fed back to the model. The agent continues running, giving the model a chance to self-correct.

func (*GuardrailHook) AfterModelCall 

func (g *GuardrailHook) AfterModelCall(ctx context.Context, arc *AgentRunContext, mcc *ModelCallContext)

type HandoffConfig 

type HandoffConfig struct {
	Name        string
	Description string // shown to the LLM so it can decide when to hand off
	Mode        HandoffMode
	AgentConfig Config
}

HandoffConfig describes a sub-agent that the current agent can hand off to.

type HandoffEndEvent 

type HandoffEndEvent struct {
	TargetAgent string        `json:"target_agent"`
	Output      string        `json:"output"`
	Duration    time.Duration `json:"duration"`
	Err         error         `json:"error,omitempty"`
	// contains filtered or unexported fields
}

func (HandoffEndEvent) EventKind 

func (e HandoffEndEvent) EventKind() EventType

func (HandoffEndEvent) EventTime 

func (e HandoffEndEvent) EventTime() time.Time

func (HandoffEndEvent) MarshalJSON 

func (e HandoffEndEvent) MarshalJSON() ([]byte, error)

func (*HandoffEndEvent) UnmarshalJSON 

func (e *HandoffEndEvent) UnmarshalJSON(data []byte) error

type HandoffMode 

type HandoffMode string

HandoffMode determines how control is transferred to a target agent. 

const (
	// HandoffDelegate runs the target agent as a sub-task and returns its output
	// as a tool result back to the calling agent. The calling agent continues.
	HandoffDelegate HandoffMode = "delegate"

	// HandoffTransfer fully transfers the conversation to the target agent.
	// The calling agent stops and the target agent takes over.
	HandoffTransfer HandoffMode = "transfer"
)

type HandoffStartEvent 

type HandoffStartEvent struct {
	SourceAgent string `json:"source_agent"`
	TargetAgent string `json:"target_agent"`
	Mode        string `json:"mode"`
	Context     string `json:"context"`
	// contains filtered or unexported fields
}

func (HandoffStartEvent) EventKind 

func (e HandoffStartEvent) EventKind() EventType

func (HandoffStartEvent) EventTime 

func (e HandoffStartEvent) EventTime() time.Time

type HookContext 

type HookContext struct {
	ToolName  string
	Arguments json.RawMessage
	State     *AgentState
}

HookContext carries contextual information passed to before/after hooks.

type HookProvider 

type HookProvider interface {
	BeforeHooks() []BeforeHook
	AfterHooks() []AfterHook
}

HookProvider is an optional interface extensions can implement to contribute hooks.

type InterruptReason added in v1.0.1 

type InterruptReason struct {
	ToolCallID string
	ToolName   string
	Reason     string
	Data       map[string]any
}

InterruptReason carries structured data about why an agent was interrupted.

type InvokeRunnable 

type InvokeRunnable[I, O any] struct {
	InvokeFn func(ctx context.Context, input I) (O, error)
}

func (*InvokeRunnable[I, O]) Collect 

func (r *InvokeRunnable[I, O]) Collect(ctx context.Context, input *StreamReader[I]) (O, error)

func (*InvokeRunnable[I, O]) Invoke 

func (r *InvokeRunnable[I, O]) Invoke(ctx context.Context, input I) (O, error)

func (*InvokeRunnable[I, O]) Stream 

func (r *InvokeRunnable[I, O]) Stream(ctx context.Context, input I) (*StreamReader[O], error)

func (*InvokeRunnable[I, O]) Transform 

func (r *InvokeRunnable[I, O]) Transform(ctx context.Context, input *StreamReader[I]) (*StreamReader[O], error)

type KeywordToolSelector added in v1.0.3 

type KeywordToolSelector struct {
	RecentUserMessages int
	IncludeUnmatched   bool
}

KeywordToolSelector ranks tools by overlap with recent user messages. It supports Unicode words and CJK character n-grams without external packages.

func (KeywordToolSelector) SelectTools added in v1.0.3 

func (selector KeywordToolSelector) SelectTools(_ context.Context, selection ToolSelectionContext) ([]string, error)

type LifecycleChain 

type LifecycleChain []LifecycleHook

LifecycleChain composes multiple LifecycleHooks into one. Hooks are called in order; AfterXxx hooks are called in reverse order.

func (LifecycleChain) AfterAgentRun 

func (lc LifecycleChain) AfterAgentRun(ctx context.Context, arc *AgentRunContext, output string, err error)

func (LifecycleChain) AfterMessagePersist 

func (lc LifecycleChain) AfterMessagePersist(ctx context.Context, arc *AgentRunContext, msg Message)

func (LifecycleChain) AfterModelCall 

func (lc LifecycleChain) AfterModelCall(ctx context.Context, arc *AgentRunContext, mcc *ModelCallContext)

func (LifecycleChain) AfterToolExecution 

func (lc LifecycleChain) AfterToolExecution(ctx context.Context, arc *AgentRunContext, tec *ToolExecutionContext)

func (LifecycleChain) AfterTurn 

func (lc LifecycleChain) AfterTurn(ctx context.Context, arc *AgentRunContext, info TurnInfo)

func (LifecycleChain) BeforeAgentRun 

func (lc LifecycleChain) BeforeAgentRun(ctx context.Context, arc *AgentRunContext) error

func (LifecycleChain) BeforeMessagePersist 

func (lc LifecycleChain) BeforeMessagePersist(ctx context.Context, arc *AgentRunContext, msg *Message) error

func (LifecycleChain) BeforeModelCall 

func (lc LifecycleChain) BeforeModelCall(ctx context.Context, arc *AgentRunContext, mcc *ModelCallContext) error

func (LifecycleChain) BeforeToolExecution 

func (lc LifecycleChain) BeforeToolExecution(ctx context.Context, arc *AgentRunContext, tec *ToolExecutionContext) error

func (LifecycleChain) BeforeTurn 

func (lc LifecycleChain) BeforeTurn(ctx context.Context, arc *AgentRunContext) error

type LifecycleHook 

type LifecycleHook interface {
	// BeforeAgentRun is called once when the agent starts.
	// Modify arc.Messages to alter the initial prompt.
	BeforeAgentRun(ctx context.Context, arc *AgentRunContext) error

	// AfterAgentRun is called once when the agent finishes (success or error).
	AfterAgentRun(ctx context.Context, arc *AgentRunContext, output string, err error)

	// BeforeModelCall is called before each LLM call.
	// Modify mcc.Request to alter the request.
	BeforeModelCall(ctx context.Context, arc *AgentRunContext, mcc *ModelCallContext) error

	// AfterModelCall is called after each LLM call.
	AfterModelCall(ctx context.Context, arc *AgentRunContext, mcc *ModelCallContext)

	// BeforeToolExecution is called before tool calls are dispatched.
	// Return error to skip tool execution entirely.
	BeforeToolExecution(ctx context.Context, arc *AgentRunContext, tec *ToolExecutionContext) error

	// AfterToolExecution is called after all tool calls in a turn complete.
	AfterToolExecution(ctx context.Context, arc *AgentRunContext, tec *ToolExecutionContext)

	// BeforeTurn runs once per inner-loop iteration after compaction / steering
	// injection and before TurnStart is emitted.
	BeforeTurn(ctx context.Context, arc *AgentRunContext) error

	// AfterTurn runs once after TurnEnd for that iteration (with or without tools).
	AfterTurn(ctx context.Context, arc *AgentRunContext, info TurnInfo)

	// BeforeMessagePersist runs immediately before a message is appended to state.
	// Mutate *msg to change what gets stored; return error to abort the agent run.
	BeforeMessagePersist(ctx context.Context, arc *AgentRunContext, msg *Message) error

	// AfterMessagePersist runs after the message was stored.
	AfterMessagePersist(ctx context.Context, arc *AgentRunContext, msg Message)
}

LifecycleHook intercepts a specific phase of agent execution. Returning a non-nil error short-circuits the phase.

type LifecycleProvider 

type LifecycleProvider interface {
	LifecycleHook() LifecycleHook
}

LifecycleProvider is an optional interface extensions can implement to participate in the agent execution lifecycle.

type LoadAgentOptions 

type LoadAgentOptions struct {
	ThreadID          string
	CallCfg           *CallConfig
	ThreadCfgProvider ThreadConfigProvider
}

type MemoryArtifactStore added in v1.0.3 

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

func NewMemoryArtifactStore added in v1.0.3 

func NewMemoryArtifactStore() *MemoryArtifactStore

func (*MemoryArtifactStore) Get added in v1.0.3 

func (s *MemoryArtifactStore) Get(ctx context.Context, id string) (Artifact, error)

func (*MemoryArtifactStore) Put added in v1.0.3 

func (s *MemoryArtifactStore) Put(ctx context.Context, artifact Artifact) (Artifact, error)

type MemoryCheckpointSaver 

type MemoryCheckpointSaver struct {
	MaxCheckpointsPerThread int
	// contains filtered or unexported fields
}

MemoryCheckpointSaver is an in-memory CheckpointSaver for tests and single-process resume. To prevent unbounded memory growth, set MaxCheckpointsPerThread to limit how many checkpoints are retained per thread (oldest are evicted). Zero means unlimited.

func NewMemoryCheckpointSaver 

func NewMemoryCheckpointSaver() *MemoryCheckpointSaver

NewMemoryCheckpointSaver creates an empty in-memory saver.

func (*MemoryCheckpointSaver) All 

func (m *MemoryCheckpointSaver) All(threadID string) []StateSnapshot

All returns every checkpoint for threadID (oldest first). For debugging/tests.

func (*MemoryCheckpointSaver) Append 

func (m *MemoryCheckpointSaver) Append(ctx context.Context, threadID string, snap StateSnapshot) (int64, error)

func (*MemoryCheckpointSaver) Latest 

func (m *MemoryCheckpointSaver) Latest(ctx context.Context, threadID string) (StateSnapshot, int64, error)

type Message 

type Message struct {
	// ID optional stable id for merge semantics: AddMessage replaces an existing
	// message with the same non-empty ID instead of appending (LangGraph add_messages style).
	ID         string         `json:"id,omitempty"`
	Role       Role           `json:"role"`
	Content    string         `json:"content,omitempty"`
	ToolCalls  []ToolCall     `json:"tool_calls,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
	Name       string         `json:"name,omitempty"`
	Type       MessageType    `json:"type,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	// CacheControl is an optional Anthropic cache_control marker for prompt caching.
	// When set, providers that support caching (e.g. Anthropic) will add cache_control
	// breakpoints to the corresponding content blocks.
	CacheControl *CacheControlMarker `json:"cache_control,omitempty"`
	// Blocks optional multi-segment body (for example text, thinking, images).
	// DefaultConvertToLLM collapses text/thinking into Content and preserves any
	// richer blocks for providers that support multipart content.
	Blocks []ContentBlock `json:"blocks,omitempty"`
	// InvocationID optionally correlates this message with one provider call.
	InvocationID string `json:"invocation_id,omitempty"`
}

Message represents a single message in the conversation history.

func DefaultConvertToLLM 

func DefaultConvertToLLM(msgs []Message) []Message

DefaultConvertToLLM keeps standard messages as-is and strips custom types down to their basic role + content.

func MessageCollapseForLLM 

func MessageCollapseForLLM(m Message, includeThinking bool) Message

MessageCollapseForLLM builds a provider-facing copy: concatenates text blocks and legacy Content. Thinking blocks are preserved on out.Blocks so that providers can serialize them back (e.g. OpenAI reasoning_content, Anthropic thinking content blocks). Non-text rich blocks (for example images) are also preserved on out.Blocks.

func NormalizeToolCallHistory added in v1.0.3 

func NormalizeToolCallHistory(msgs []Message) []Message

NormalizeToolCallHistory inserts synthetic tool results for assistant tool calls that do not have a matching result in the immediately following tool message group. The returned slice is safe to send to providers that require every tool call to have a corresponding result.

func (Message) AppendImageURLBlock 

func (m Message) AppendImageURLBlock(url string) Message

AppendImageURLBlock appends an image block using an HTTPS URL or data URL.

func (Message) AppendTextBlock 

func (m Message) AppendTextBlock(text string) Message

AppendTextBlock appends a text block and returns the mutated message.

func (Message) AppendThinkingBlock 

func (m Message) AppendThinkingBlock(text string) Message

AppendThinkingBlock appends a thinking block.

func (Message) Clone 

func (m Message) Clone() Message

Clone returns a deep copy of the message. All reference-type fields (ToolCalls, Blocks, Metadata) are independently copied so that mutations to the clone never affect the original.

func (Message) IsStandard 

func (m Message) IsStandard() bool

IsStandard returns true if the message is a standard LLM message (no custom type).

type MessageBus 

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

MessageBus is a simple fan-out / fan-in message channel for orchestrating multiple agents. It is optional; use it when you want explicit routing between steps without sharing a single Agent state.

func NewMessageBus 

func NewMessageBus() *MessageBus

NewMessageBus creates an empty bus.

func (*MessageBus) Publish 

func (b *MessageBus) Publish(topic string, m Message)

Publish delivers a copy of m to every subscriber of topic (non-blocking per subscriber: drops if channel buffer full).

func (*MessageBus) Subscribe 

func (b *MessageBus) Subscribe(topic string, cap int) (recv <-chan Message, cancel func())

Subscribe returns a receive-only channel for topic with buffer cap, and cancel removes the subscription and closes the channel.

type MessageDeltaEvent 

type MessageDeltaEvent struct {
	Delta     string    `json:"delta"`
	Kind      BlockKind `json:"kind,omitempty"`
	AttemptID string    `json:"attempt_id,omitempty"`
	// contains filtered or unexported fields
}

func (MessageDeltaEvent) EventKind 

func (e MessageDeltaEvent) EventKind() EventType

func (MessageDeltaEvent) EventTime 

func (e MessageDeltaEvent) EventTime() time.Time

type MessageResetEvent added in v1.0.3 

type MessageResetEvent struct {
	AttemptID string `json:"attempt_id"`
	Reason    string `json:"reason,omitempty"`
	// contains filtered or unexported fields
}

MessageResetEvent retracts all deltas emitted for one failed streaming attempt. Streaming consumers should discard that attempt before rendering deltas from a retry or failover target.

func (MessageResetEvent) EventKind added in v1.0.3 

func (e MessageResetEvent) EventKind() EventType

func (MessageResetEvent) EventTime added in v1.0.3 

func (e MessageResetEvent) EventTime() time.Time

type MessageType 

type MessageType string

MessageType distinguishes internal message variants from standard LLM messages. Standard messages have Type == "" and are sent directly to the provider. Custom types are converted via ConvertToLLM before reaching the provider. 

const (
	MessageTypeStandard          MessageType = ""
	MessageTypeCompactionSummary MessageType = "compaction_summary"
	MessageTypeBranchSummary     MessageType = "branch_summary"
	MessageTypeCustom            MessageType = "custom"
)

type Metrics added in v1.0.5 

type Metrics interface {
	// RecordModelCall records token usage and wall-clock duration of a
	// completed LLM call. usage may be nil for calls that did not report
	// usage; start must be the time the call began.
	RecordModelCall(ctx context.Context, req *ProviderRequest, usage *TokenUsage, start time.Time)

	// RecordError counts a failed component run. component is one of "model",
	// "tool", or "agent"; err is the failure that triggered the recording and
	// may be nil.
	RecordError(ctx context.Context, component string, err error)
}

Metrics receives agent runtime metrics. It is the semantic contract for agent observability; concrete adapters map it to a backend (see NewOtelMetrics). A nil Metrics means metrics are disabled (noop).

The interface is deliberately small and aligned with the GenAI semantic conventions so that adapters can emit standard metrics without loss. It is complementary to the Tracer interface: tracing records what happened, metrics count and measure it.

func NewOtelMetrics added in v1.0.5 

func NewOtelMetrics(meter metric.Meter) Metrics

NewOtelMetrics adapts the agentcore Metrics contract to an OpenTelemetry meter, emitting standard GenAI semantic-convention metrics plus the library's own error counter. The meter is typically provided by the host's metrics SDK; a nil meter yields a noop adapter.

type Middleware 

type Middleware func(next ExecuteFunc) ExecuteFunc

Middleware wraps tool execution with cross-cutting logic. Call next(ctx, tc) to proceed to the next middleware or the core executor.

func MetricsMiddleware added in v1.0.5 

func MetricsMiddleware(metrics Metrics) Middleware

MetricsMiddleware wraps each tool execution to record tool errors. It is injected into the executor chain automatically when Config.Metrics is set; it is also exported for hosts composing their own middleware chains.

func RetryMiddleware 

func RetryMiddleware(maxRetries int64, delay time.Duration) Middleware

RetryMiddleware retries failed tool calls up to maxRetries times with a fixed delay.

func TimeoutMiddleware 

func TimeoutMiddleware(timeout time.Duration) Middleware

TimeoutMiddleware wraps each tool call with a context deadline.

func TracingMiddleware 

func TracingMiddleware(tracer Tracer) Middleware

TracingMiddleware creates an Executor middleware that wraps each tool call in a trace span. Input (tool arguments) and output (result content) are recorded as span attributes so observability backends can inspect what was passed to and returned by each tool.

Multi-backend compatibility: different LLM observability platforms use different attribute names for input/output. We write all known conventions so data appears regardless of which backend is active:

  • langfuse.observation.input/output (Langfuse)
  • langsmith.input/output (LangSmith)
  • input.value/output.value (OpenInference / MLflow)
  • tool.input/output (generic fallback for Jaeger, Tempo, etc.)

Additionally, observation type/kind attributes ensure tool calls are correctly classified (not as LLM generations):

  • langfuse.observation.type = "span" (Langfuse)
  • langsmith.span.kind = "tool" (LangSmith)

type MiddlewareProvider 

type MiddlewareProvider interface {
	Middleware() []Middleware
}

MiddlewareProvider is an optional interface extensions can implement to contribute middleware.

type ModelCallContext 

type ModelCallContext struct {
	Request  *ProviderRequest
	Response *ProviderResponse // nil in Before, populated in After
	Err      error             // only in After
}

ModelCallContext carries context for model call hooks.

type ModelConfig 

type ModelConfig struct {
	Name        string   // optional: identifies this agent in events and handoff logs
	Model       string   // model identifier (e.g. "gpt-5.6")
	Provider    Provider // LLM provider implementation
	Temperature float64  // sampling temperature; 0 = deterministic
	MaxTokens   int64    // max tokens in response; 0 = provider default

	// FrequencyPenalty / PresencePenalty reduce the model's tendency to
	// degenerate into repeating the same text verbatim (see EventAutoRetry /
	// stream_health repetition-loop detection for the after-the-fact
	// mitigation). 0 = provider default (unset). Only forwarded by providers
	// that support the OpenAI-style penalty params (e.g. chatcompat); other
	// providers (Anthropic, Gemini, Bedrock) silently ignore these fields.
	// Not all models accept non-zero penalties (some reasoning models reject
	// them), so this is opt-in and never defaulted automatically.
	FrequencyPenalty float64
	PresencePenalty  float64
	ResponseFormat   *ResponseFormat // optional: force JSON mode etc.
	Thinking         *ThinkingConfig // optional: extended thinking / reasoning
	Streaming        bool            // enable streaming responses

	// FastMode requests priority/low-latency processing where supported
	// (e.g. OpenAI Priority Processing, Anthropic Fast Mode).
	FastMode bool

	// Failover switches to alternate provider/model targets after retries for
	// the current target are exhausted.
	Failover *ModelFailoverConfig
}

ModelConfig groups LLM model selection and generation parameters.

type ModelFailoverConfig added in v1.0.3 

type ModelFailoverConfig struct {
	Targets        []ModelTarget
	MaxAttempts    int
	ShouldFailover func(ctx context.Context, failure ModelFailoverContext) bool
	SelectTarget   func(ctx context.Context, failure ModelFailoverContext) (ModelTarget, error)
}

ModelFailoverConfig switches provider/model targets after normal retry is exhausted. SelectTarget overrides the default ordered Targets selection.

type ModelFailoverContext added in v1.0.3 

type ModelFailoverContext struct {
	Attempt      int
	LastTarget   ModelTarget
	LastResponse *ProviderResponse
	LastErr      error
}

ModelFailoverContext describes the last failed target and any partial response accumulated before a streaming failure.

type ModelFailoverEvent added in v1.0.3 

type ModelFailoverEvent struct {
	Attempt   int    `json:"attempt"`
	From      string `json:"from,omitempty"`
	To        string `json:"to,omitempty"`
	FromModel string `json:"from_model,omitempty"`
	ToModel   string `json:"to_model,omitempty"`
	Err       error  `json:"-"`
	// contains filtered or unexported fields
}

ModelFailoverEvent reports a switch to an alternate provider/model target.

func (ModelFailoverEvent) EventKind added in v1.0.3 

func (e ModelFailoverEvent) EventKind() EventType

func (ModelFailoverEvent) EventTime added in v1.0.3 

func (e ModelFailoverEvent) EventTime() time.Time

type ModelProfile added in v1.0.2 

type ModelProfile struct {
	// Name is the profile identifier, matched against Config.Model.
	// Typically the model name (e.g. "claude-sonnet-4-6") or a
	// "provider:model" key.
	Name string

	// SystemPromptSuffix is appended to Config.SystemPrompt when this
	// profile is active. Useful for model-specific guidance such as
	// "use parallel tool calls" or "investigate before answering".
	SystemPromptSuffix string

	// ExcludedTools lists tool names removed from Config.Tools when this
	// profile is active. Use when a model cannot reliably use a tool.
	// Handoff tools (transfer_to_*) are never excluded.
	ExcludedTools []string

	// Temperature overrides Config.Temperature only when the caller left
	// it at the zero value (0). nil means no override.
	Temperature *float64

	// MaxTurns overrides Config.MaxTurns only when the caller left it at
	// zero (before the default-20 fallback applies). nil means no override.
	MaxTurns *int64
}

ModelProfile provides model-specific default configuration overrides. Register a profile for a model identifier (typically Config.Model) and New() will automatically apply it. User-set fields always take precedence over profile values; SystemPromptSuffix and ExcludedTools are additive/removal and always apply.

This is the lightweight equivalent of a full profile system: enough to let the community contribute model-specific tuning without forcing every caller to hand-tune Config for each model.

func LookupProfile added in v1.0.2 

func LookupProfile(model string) (ModelProfile, bool)

LookupProfile returns the registered profile for the given model identifier. Returns ok=false if no profile matches.

type ModelTarget added in v1.0.3 

type ModelTarget struct {
	Name     string
	Model    string
	Provider Provider
}

ModelTarget identifies one provider/model pair in a failover chain.

type NodeError 

type NodeError struct {
	Path    []string // execution path, e.g. ["coordinator", "turn:3", "tool:get_weather"]
	Message string
	Err     error
}

NodeError is a structured error that carries the execution path (agent name, turn, node/tool) where the error occurred. This makes debugging complex multi-agent workflows significantly easier.

func NewNodeError 

func NewNodeError(msg string, err error, path ...string) *NodeError

NewNodeError creates a NodeError with the given path segments.

func (*NodeError) Error 

func (e *NodeError) Error() string

func (*NodeError) Unwrap 

func (e *NodeError) Unwrap() error

type OtelTracer added in v1.0.5 

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

OtelTracer adapts the agentcore Tracer interface to OpenTelemetry so that agent/model/tool spans are emitted as standard OTLP spans (including the GenAI semantic convention attributes set elsewhere in agentcore).

func NewOtelTracer added in v1.0.5 

func NewOtelTracer(t trace.Tracer) *OtelTracer

NewOtelTracer wraps an OpenTelemetry tracer. Use nil-safe: a nil *OtelTracer behaves like the noop tracer.

func (*OtelTracer) Start added in v1.0.5 

func (t *OtelTracer) Start(ctx context.Context, name string, attrs ...SpanAttribute) (context.Context, Span)

Start implements agentcore.Tracer. The returned context carries the created span so nested StartComponentRun calls become child spans automatically.

type PendingHandoff 

type PendingHandoff struct {
	TargetName   string
	TargetConfig Config
	Context      string
}

PendingHandoff is set on state when a transfer-mode handoff tool is called.

type PromptCachingExtension added in v1.0.2 

type PromptCachingExtension struct {
	// MaxBreakpoints caps the total number of markers the extension will
	// add. 0 or negative disables the extension entirely (no markers
	// added). NewPromptCachingExtension defaults to 4 (Anthropic limit).
	MaxBreakpoints int

	// CacheSystemPrompt adds a breakpoint to the first system message.
	// Defaults to true.
	CacheSystemPrompt bool

	// CacheLastN adds a breakpoint to the message at position
	// len(msgs)-CacheLastN, so everything before it stays cached as the
	// conversation grows. Set to 0 to disable. Defaults to 3.
	CacheLastN int
}

PromptCachingExtension automatically annotates messages with CacheControlMarker breakpoints so that providers supporting prompt caching (e.g. Anthropic) can cache stable prefixes and reduce token costs by up to ~75%.

The extension implements TransformContextProvider: it runs on every model call, after the agent assembles the message list and before it is sent to the provider. Messages already carrying a CacheControl marker are left untouched, so manual markers win over the automatic strategy.

Anthropic limits cache_control to 4 breakpoints per request; the default strategy uses 2 (one on the system prompt, one near the tail of the conversation) which keeps a stable prefix cached while leaving room for manual markers if needed.

func NewPromptCachingExtension added in v1.0.2 

func NewPromptCachingExtension(opts ...PromptCachingOption) *PromptCachingExtension

NewPromptCachingExtension creates an extension with sensible defaults: up to 4 breakpoints, system prompt cached, tail breakpoint at -3.

func (*PromptCachingExtension) Dispose added in v1.0.2 

func (e *PromptCachingExtension) Dispose() error

Dispose implements Extension.

func (*PromptCachingExtension) Init added in v1.0.2 

func (e *PromptCachingExtension) Init(_ context.Context, _ *Agent) error

Init implements Extension.

func (*PromptCachingExtension) Name added in v1.0.2 

func (e *PromptCachingExtension) Name() string

Name implements Extension.

func (*PromptCachingExtension) TransformContext added in v1.0.2 

func (e *PromptCachingExtension) TransformContext(_ context.Context, msgs []Message) []Message

TransformContext implements TransformContextProvider. It returns a new slice; the input messages are not mutated. Messages that already carry a CacheControl marker are preserved as-is.

type PromptCachingOption added in v1.0.2 

type PromptCachingOption func(*PromptCachingExtension)

PromptCachingOption configures a PromptCachingExtension.

func WithCacheLastN added in v1.0.2 

func WithCacheLastN(n int) PromptCachingOption

WithCacheLastN sets the tail-breakpoint offset. 0 disables it.

func WithCacheSystemPrompt added in v1.0.2 

func WithCacheSystemPrompt(b bool) PromptCachingOption

WithCacheSystemPrompt enables/disables the system-prompt breakpoint.

func WithMaxBreakpoints added in v1.0.2 

func WithMaxBreakpoints(n int) PromptCachingOption

WithMaxBreakpoints sets the breakpoint cap.

type Provider 

type Provider interface {
	Complete(ctx context.Context, req *ProviderRequest) (*ProviderResponse, error)
	Stream(ctx context.Context, req *ProviderRequest) (<-chan StreamDelta, error)
}

Provider is the abstraction layer over different LLM backends.

type ProviderRequest 

type ProviderRequest struct {
	Model            string
	Messages         []Message
	Tools            []ToolDefinition
	Temperature      float64
	FrequencyPenalty float64
	PresencePenalty  float64
	MaxTokens        int64
	ResponseFormat   *ResponseFormat
	Thinking         *ThinkingConfig

	// FastMode requests priority/low-latency processing where supported
	// (e.g. OpenAI Priority Processing, Anthropic Fast Mode).
	FastMode bool
}

ProviderRequest is the input for a model completion call.

type ProviderResponse 

type ProviderResponse struct {
	Content    string
	Blocks     []ContentBlock
	Structured json.RawMessage
	ToolCalls  []ToolCall
	Usage      TokenUsage
	// FinishReason reports why the model stopped generating. Common values:
	// "stop" (natural end), "length" (max_tokens truncated the output),
	// "tool_calls" (stopped to call tools), "content_filter".
	// When "length" and ToolCalls is non-empty, the tool-call arguments may be
	// truncated mid-JSON; the executor guards against this by validating JSON
	// before dispatch, but callers may also inspect FinishReason directly.
	FinishReason string
	// SuppressPersist skips storing this assistant response in conversation state.
	// Extensions may use this for internal control turns that should trigger
	// another model call without surfacing an intermediate assistant message.
	SuppressPersist bool
}

ProviderResponse is the output of a non-streaming completion call.

type RateLimitHook 

type RateLimitHook struct {
	BaseLifecycleHook
	MaxTurnsPerMinute int64
	// contains filtered or unexported fields
}

RateLimitHook enforces per-turn rate limits by injecting delays or errors. It resets the counter at the start of each Agent.Run() via BeforeAgentRun. When MaxTurnsPerMinute is set, it enforces a sliding window: if the number of turns within the last 60 seconds exceeds the limit, an error is returned.

func (*RateLimitHook) BeforeAgentRun 

func (r *RateLimitHook) BeforeAgentRun(_ context.Context, _ *AgentRunContext) error

func (*RateLimitHook) BeforeModelCall 

func (r *RateLimitHook) BeforeModelCall(_ context.Context, _ *AgentRunContext, _ *ModelCallContext) error

type Registry 

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

Registry is a thread-safe collection of available tools.

func NewRegistry 

func NewRegistry() *Registry

func (*Registry) Count 

func (r *Registry) Count() int64

func (*Registry) Definitions 

func (r *Registry) Definitions() []ToolDefinition

func (*Registry) Get 

func (r *Registry) Get(name string) (*Tool, bool)

func (*Registry) Names 

func (r *Registry) Names() []string

func (*Registry) Register 

func (r *Registry) Register(tools ...*Tool)

func (*Registry) Tools 

func (r *Registry) Tools() []*Tool

Tools returns all registered tools.

func (*Registry) Unregister 

func (r *Registry) Unregister(names ...string)

type RepetitionKind added in v1.0.2 

type RepetitionKind string

RepetitionKind identifies which detector triggered a repetition-recovery nudge, so a custom Prompt function (or the built-in default) can tailor the corrective message to what actually went wrong. 

const (
	// RepetitionKindStream: mid-stream degeneration reported by a provider
	// middleware (e.g. covo-agent's stream_health n-gram/periodicity detector).
	RepetitionKindStream RepetitionKind = "stream"
	// RepetitionKindText: the model produced (near-)identical assistant text
	// across consecutive turns.
	RepetitionKindText RepetitionKind = "text"
	// RepetitionKindTool: the model made the same tool call (name+arguments)
	// across consecutive turns without progress.
	RepetitionKindTool RepetitionKind = "tool"
)

type RepetitionRecoveryConfig added in v1.0.2 

type RepetitionRecoveryConfig struct {
	// MaxAttempts is how many corrective nudges to send (per detector) before
	// giving up and ending the turn with a terminal error. <= 0 uses the
	// built-in default (2), matching a "mild nudge, then a stronger replan
	// nudge, then give up" ladder.
	MaxAttempts int64

	// Prompt returns the corrective steering message for the given detector
	// and 0-based attempt number (0 = first/mildest nudge, increasing
	// severity thereafter). If nil, a built-in English default ladder is
	// used. Callers wanting localized text should supply this.
	Prompt func(kind RepetitionKind, attempt int64) string
}

RepetitionRecoveryConfig controls the soft repetition-loop recovery ladder used by runLoop: when a degeneration/repetition loop is detected (mid- stream via a provider middleware, or across turns via repeated content or repeated tool calls), a corrective steering message is injected and the model gets another chance — escalating in severity — before the turn is finally given up on with a terminal error.

type RepetitionRecoveryEvent added in v1.0.2 

type RepetitionRecoveryEvent struct {
	Kind        RepetitionKind `json:"kind"`
	Attempt     int64          `json:"attempt"`
	MaxAttempts int64          `json:"max_attempts"`
	// contains filtered or unexported fields
}

RepetitionRecoveryEvent is emitted each time runLoop's repetition-recovery ladder injects a corrective steering nudge (see RepetitionKind / RepetitionRecoveryConfig in retry.go). It fires on the soft-recovery path only; if the ladder is ultimately exhausted, the turn ends with a normal AgentErrorEvent (wrapping ErrRepetitionLoop) instead.

func (RepetitionRecoveryEvent) EventKind added in v1.0.2 

func (e RepetitionRecoveryEvent) EventKind() EventType

func (RepetitionRecoveryEvent) EventTime added in v1.0.2 

func (e RepetitionRecoveryEvent) EventTime() time.Time

type ResponseFormat 

type ResponseFormat struct {
	Type       ResponseFormatType              `json:"type"`
	JSONSchema *ResponseFormatJSONSchemaConfig `json:"json_schema,omitempty"`
}

ResponseFormat requests constrained model output from providers that support it.

func CloneResponseFormat 

func CloneResponseFormat(f *ResponseFormat) *ResponseFormat

func NewJSONObjectResponseFormat 

func NewJSONObjectResponseFormat() *ResponseFormat

NewJSONObjectResponseFormat requests a valid JSON object response.

func NewJSONSchemaResponseFormat 

func NewJSONSchemaResponseFormat(name string, schema map[string]any) *ResponseFormat

NewJSONSchemaResponseFormat requests output that conforms to the given schema.

func (*ResponseFormat) PromptInstruction 

func (f *ResponseFormat) PromptInstruction() string

PromptInstruction renders a provider-agnostic fallback instruction for providers that do not expose a first-class structured output API.

func (*ResponseFormat) String 

func (f *ResponseFormat) String() string

type ResponseFormatJSONSchemaConfig 

type ResponseFormatJSONSchemaConfig struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Schema      map[string]any `json:"schema"`
	Strict      bool           `json:"strict,omitempty"`
}

ResponseFormatJSONSchemaConfig configures a named JSON Schema response format.

type ResponseFormatType 

type ResponseFormatType string
const (
	ResponseFormatText       ResponseFormatType = "text"
	ResponseFormatJSONObject ResponseFormatType = "json_object"
	ResponseFormatJSONSchema ResponseFormatType = "json_schema"
)

type RetryConfig 

type RetryConfig struct {
	MaxRetries  int64 // max retry attempts; default 3
	BaseDelayMs int64 // initial delay in ms; default 1000
	MaxDelayMs  int64 // max delay cap in ms; default 30000
}

RetryConfig controls LLM-level automatic retry behavior.

type Role 

type Role string

Role represents the sender of a message in a conversation. 

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

type RulesExtension added in v1.0.2 

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

RulesExtension loads project rule files (such as AGENTS.md, .cursorrules, or any caller-specified file) and appends their content to the agent's system prompt. This gives the agent persistent, project-specific guidance without hard-coding it into Config.SystemPrompt.

The extension is intentionally generic: it does not bind to any single convention filename. Pass whichever files make sense for your project. Missing files are silently skipped, so a single extension can try several candidate paths.

Files are read once during Init. Callers needing hot-reload should dispose and re-register the extension.

func NewRulesExtension added in v1.0.2 

func NewRulesExtension(opts ...RulesOption) *RulesExtension

NewRulesExtension creates an extension that loads rule files. With no options it tries "AGENTS.md" in the working directory.

func (*RulesExtension) Dispose added in v1.0.2 

func (e *RulesExtension) Dispose() error

Dispose implements Extension.

func (*RulesExtension) Init added in v1.0.2 

func (e *RulesExtension) Init(_ context.Context, _ *Agent) error

Init implements Extension. It reads all configured paths, skipping any that are missing or empty, and concatenates the surviving contents.

func (*RulesExtension) Loaded added in v1.0.2 

func (e *RulesExtension) Loaded() string

Loaded returns the content gathered during Init. Useful for diagnostics.

func (*RulesExtension) Name added in v1.0.2 

func (e *RulesExtension) Name() string

Name implements Extension.

func (*RulesExtension) SystemPromptSuffix added in v1.0.2 

func (e *RulesExtension) SystemPromptSuffix() string

SystemPromptSuffix implements SystemPromptProvider. Returns the concatenated rule-file content (empty if no files were found).

type RulesOption added in v1.0.2 

type RulesOption func(*RulesExtension)

RulesOption configures a RulesExtension.

func WithRulesPaths added in v1.0.2 

func WithRulesPaths(paths ...string) RulesOption

WithRulesPaths sets the candidate file paths to read, in order. Earlier paths take precedence in the output ordering. Missing files are skipped.

func WithRulesReader added in v1.0.2 

func WithRulesReader(r FileReader) RulesOption

WithRulesReader replaces the default OS file reader with a custom one.

type RunInfo added in v1.0.3 

type RunInfo struct {
	RunID       string   `json:"run_id"`
	ParentRunID string   `json:"parent_run_id,omitempty"`
	Component   string   `json:"component"`
	Name        string   `json:"name,omitempty"`
	Path        []string `json:"path,omitempty"`
}

RunInfo identifies one component invocation in a parent/child execution tree.

func EventRunInfo added in v1.0.3 

func EventRunInfo(event Event) (RunInfo, bool)

EventRunInfo returns correlated execution metadata when the event was emitted from a component run context.

func RunInfoFromContext added in v1.0.3 

func RunInfoFromContext(ctx context.Context) (RunInfo, bool)

type Runnable 

type Runnable[I, O any] interface {
	Invoke(ctx context.Context, input I) (O, error)
	Stream(ctx context.Context, input I) (*StreamReader[O], error)
	Collect(ctx context.Context, input *StreamReader[I]) (O, error)
	Transform(ctx context.Context, input *StreamReader[I]) (*StreamReader[O], error)
}

Runnable[I, O] is a generic interface for any executable component. A four-mode design that supports all data flow patterns:

  • Invoke: single input → single output
  • Stream: single input → stream output
  • Collect: stream input → single output
  • Transform: stream input → stream output

Components only need to implement the methods they care about. Use NewInvokeRunnable / NewStreamRunnable / NewCollectRunnable / NewTransformRunnable to create partial implementations — the framework auto-derives the missing modes.

func NewCollectRunnable 

func NewCollectRunnable[I, O any](fn func(ctx context.Context, input *StreamReader[I]) (O, error)) Runnable[I, O]

func NewInvokeRunnable 

func NewInvokeRunnable[I, O any](fn func(ctx context.Context, input I) (O, error)) Runnable[I, O]

func NewStreamRunnable 

func NewStreamRunnable[I, O any](fn func(ctx context.Context, input I) (*StreamReader[O], error)) Runnable[I, O]

func NewTransformRunnable 

func NewTransformRunnable[I, O any](fn func(ctx context.Context, input *StreamReader[I]) (*StreamReader[O], error)) Runnable[I, O]

type RunnableStep 

type RunnableStep[I, O any] struct {
	Name       string
	R          Runnable[I, O]
	ToInput    func(string) I
	FromOutput func(O) string
}

RunnableStep adapts a Runnable to the Step interface for workflows.

func (*RunnableStep[I, O]) Run 

func (rs *RunnableStep[I, O]) Run(ctx context.Context, input string) (string, error)

type SkillConfig 

type SkillConfig struct {
	AvailableSkills         []skill.Skill
	SelectedSkills          []string
	SkillPaths              []string
	SkillDiagnostics        []skill.Diagnostic
	SkillAPIAuthToken       string
	DisableSkillRegistryAPI bool
	DisableSkillReloadAPI   bool
}

SkillConfig groups skill loading, selection, and API control.

type SkillLoadedEvent 

type SkillLoadedEvent struct {
	SkillName string `json:"skill_name"`
	Path      string `json:"path,omitempty"`
	Source    string `json:"source"`
	Arguments string `json:"arguments,omitempty"`
	// contains filtered or unexported fields
}

func (SkillLoadedEvent) EventKind 

func (e SkillLoadedEvent) EventKind() EventType

func (SkillLoadedEvent) EventTime 

func (e SkillLoadedEvent) EventTime() time.Time

type SkillsReloadedEvent 

type SkillsReloadedEvent struct {
	SkillPaths         []string           `json:"skill_paths,omitempty"`
	TotalSkills        int                `json:"total_skills"`
	VisibleSkills      int                `json:"visible_skills"`
	HiddenSkills       int                `json:"hidden_skills"`
	DiagnosticsCount   int                `json:"diagnostics_count"`
	AddedSkills        []string           `json:"added_skills,omitempty"`
	RemovedSkills      []string           `json:"removed_skills,omitempty"`
	UpdatedSkills      []string           `json:"updated_skills,omitempty"`
	AddedDiagnostics   []skill.Diagnostic `json:"added_diagnostics,omitempty"`
	RemovedDiagnostics []skill.Diagnostic `json:"removed_diagnostics,omitempty"`
	// contains filtered or unexported fields
}

func NewSkillsReloadedEvent 

func NewSkillsReloadedEvent(
	skillPaths []string,
	totalSkills, visibleSkills, hiddenSkills, diagnosticsCount int,
	addedSkills, removedSkills, updatedSkills []string,
	addedDiagnostics, removedDiagnostics []skill.Diagnostic,
) SkillsReloadedEvent

func (SkillsReloadedEvent) EventKind 

func (e SkillsReloadedEvent) EventKind() EventType

func (SkillsReloadedEvent) EventTime 

func (e SkillsReloadedEvent) EventTime() time.Time

type Span 

type Span interface {
	End()
	SetAttributes(attrs ...SpanAttribute)
	RecordError(err error)
	AddEvent(name string, attrs ...SpanAttribute)
}

Span represents a unit of work in a distributed trace. Implement this interface with OpenTelemetry, Datadog, Jaeger, or any other backend.

type SpanAttribute 

type SpanAttribute struct {
	Key   string
	Value any
}

SpanAttribute is a key-value pair attached to a span.

func Attr 

func Attr(key string, value any) SpanAttribute

Attr is a convenience constructor for SpanAttribute.

type StateSnapshot 

type StateSnapshot struct {
	Version         int              `json:"version,omitempty"`
	Status          Status           `json:"status"`
	Messages        []Message        `json:"messages"`
	Turn            int64            `json:"turn"`
	TotalUsage      TokenUsage       `json:"total_usage"`
	InterruptReason *InterruptReason `json:"interrupt_reason,omitempty"`
}

Snapshot serializes the current state for persistence / resume.

func MigrateStateSnapshot added in v1.0.3 

func MigrateStateSnapshot(ctx context.Context, snapshot StateSnapshot, migrators map[int]StateSnapshotMigrator) (StateSnapshot, error)

MigrateStateSnapshot upgrades a snapshot to the current schema. Version zero is the legacy unversioned format and uses an identity migration by default.

type StateSnapshotMigrator added in v1.0.3 

type StateSnapshotMigrator func(ctx context.Context, snapshot StateSnapshot) (StateSnapshot, error)

StateSnapshotMigrator upgrades one snapshot version to the next version.

type Status 

type Status string
const (
	StatusIdle        Status = "idle"
	StatusRunning     Status = "running"
	StatusFinished    Status = "finished"
	StatusError       Status = "error"
	StatusInterrupted Status = "interrupted"
)

type SteeringMode 

type SteeringMode string

SteeringMode controls how multiple queued messages are drained. 

const (
	// SteeringAll drains all pending messages at once.
	SteeringAll SteeringMode = "all"
	// SteeringOneAtATime drains one message per LLM turn.
	SteeringOneAtATime SteeringMode = "one_at_a_time"
)

type Step 

type Step interface {
	Run(ctx context.Context, input string) (string, error)
}

Step is a unit of work in a workflow or graph. All workflow primitives (Pipeline, Parallel, Router, CompiledGraph) implement Step.

func NewStringRunnableStep 

func NewStringRunnableStep(r StringRunnable) Step

func StreamStepToStep added in v1.0.1 

func StreamStepToStep(s StreamStep) Step

StreamStepToStep adapts a StreamStep to Step by feeding the input as a single-element stream and collecting all output chunks into one string.

type Store 

type Store interface {
	Save(ctx context.Context, key string, snap StateSnapshot) error
	Load(ctx context.Context, key string) (StateSnapshot, error)
	Delete(ctx context.Context, key string) error
	List(ctx context.Context) ([]string, error)
	// Has returns true if a state snapshot exists for the given key.
	Has(ctx context.Context, key string) (bool, error)
}

Store persists and retrieves agent state snapshots. Implementations: store.FileStore (file-based).

type StreamDelta 

type StreamDelta struct {
	Content   string
	Blocks    []ContentBlock
	ToolCalls []ToolCallDelta
	Done      bool
	Usage     *TokenUsage // populated on the final chunk by some providers
	// FinishReason is populated on the final chunk by providers that expose it.
	// Common values: "stop", "length", "tool_calls", "content_filter".
	FinishReason string
	// Err, when non-nil, signals a terminal mid-stream condition detected by a
	// provider middleware (e.g. a degenerate repetition loop) rather than a
	// genuine model-generated finish. When set, this should be the last delta
	// sent before the channel is closed; runStreaming discards any content
	// accumulated so far and returns this error instead of a normal response,
	// so the bad/partial output never gets persisted as a real assistant turn.
	Err error
}

StreamDelta is one incremental chunk from a streaming completion.

type StreamReader 

type StreamReader[T any] struct {
	// contains filtered or unexported fields
}

StreamReader[T] is a managed stream with explicit lifecycle control. Unlike raw channels, it tracks errors, supports Close() for producer cleanup, and prevents goroutine leaks by closing the stop channel when the consumer is finished.

func Map 

func Map[I, O any](src *StreamReader[I], fn func(I) (O, error)) *StreamReader[O]

Map transforms each element using fn and returns a new StreamReader.

func Merge 

func Merge[T any](readers ...*StreamReader[T]) *StreamReader[T]

Merge combines multiple StreamReaders into one. Items arrive in non-deterministic order.

func NewStreamFromValue added in v1.0.1 

func NewStreamFromValue[T any](val T) *StreamReader[T]

NewStreamFromValue creates a single-element stream containing val.

func NewStreamReader 

func NewStreamReader[T any](bufSize int64) *StreamReader[T]

NewStreamReader creates a stream with the given buffer size.

func (*StreamReader[T]) Cancel 

func (s *StreamReader[T]) Cancel()

Cancel tells the producer the consumer no longer needs data. Producers watching the stop channel should stop sending.

func (*StreamReader[T]) Close 

func (s *StreamReader[T]) Close()

Close signals end-of-stream from the producer side.

func (*StreamReader[T]) Collect 

func (s *StreamReader[T]) Collect() ([]T, error)

Collect drains the stream into a slice.

func (*StreamReader[T]) Done 

func (s *StreamReader[T]) Done() <-chan struct{}

Done returns a channel that is closed when the consumer cancels the stream or the stream is done.

func (*StreamReader[T]) Err 

func (s *StreamReader[T]) Err() error

Err returns the terminal error, if any.

func (*StreamReader[T]) Pipe 

func (s *StreamReader[T]) Pipe(target *StreamReader[T]) error

Pipe connects this reader to another writer: every item received is forwarded. Blocks until the source is exhausted, then closes the target.

func (*StreamReader[T]) Recv 

func (s *StreamReader[T]) Recv() (T, bool)

Recv reads the next value. Returns (zero, false) when the stream is exhausted.

func (*StreamReader[T]) Send 

func (s *StreamReader[T]) Send(val T) bool

Send pushes a value into the stream. Returns false if the stream is closed or the consumer cancelled.

func (*StreamReader[T]) SetError 

func (s *StreamReader[T]) SetError(err error)

SetError records a terminal error and closes the stream.

type StreamRunnable 

type StreamRunnable[I, O any] struct {
	StreamFn func(ctx context.Context, input I) (*StreamReader[O], error)
}

func (*StreamRunnable[I, O]) Collect 

func (r *StreamRunnable[I, O]) Collect(ctx context.Context, input *StreamReader[I]) (O, error)

func (*StreamRunnable[I, O]) Invoke 

func (r *StreamRunnable[I, O]) Invoke(ctx context.Context, input I) (O, error)

func (*StreamRunnable[I, O]) Stream 

func (r *StreamRunnable[I, O]) Stream(ctx context.Context, input I) (*StreamReader[O], error)

func (*StreamRunnable[I, O]) Transform 

func (r *StreamRunnable[I, O]) Transform(ctx context.Context, input *StreamReader[I]) (*StreamReader[O], error)

type StreamStep added in v1.0.1 

type StreamStep interface {
	RunStream(ctx context.Context, input *StreamReader[string]) (*StreamReader[string], error)
}

StreamStep is a streaming variant of Step. Nodes implementing this can produce output progressively without waiting for all input to arrive, enabling pipelined execution between graph layers.

func AsStreamStep added in v1.0.1 

func AsStreamStep(s Step) StreamStep

AsStreamStep returns the Step as a StreamStep if it implements the interface, or wraps it with StepToStreamStep otherwise.

func StepToStreamStep added in v1.0.1 

func StepToStreamStep(s Step) StreamStep

StepToStreamStep adapts a Step to StreamStep by collecting the entire input stream, running once, and wrapping the result as a single-element stream.

type StringRunnable 

type StringRunnable = Runnable[string, string]

type StructuredCompactionSummary 

type StructuredCompactionSummary struct {
	ActiveTask        string `json:"active_task"`
	Goal              string `json:"goal"`
	ConstraintsPrefs  string `json:"constraints_preferences"`
	CompletedActions  string `json:"completed_actions"`
	ActiveState       string `json:"active_state"`
	InProgress        string `json:"in_progress"`
	Blocked           string `json:"blocked"`
	KeyDecisions      string `json:"key_decisions"`
	ResolvedQuestions string `json:"resolved_questions"`
	PendingUserAsks   string `json:"pending_user_asks"`
	RelevantFiles     string `json:"relevant_files"`
	RemainingWork     string `json:"remaining_work"`
	CriticalContext   string `json:"critical_context"`
}

StructuredCompactionSummary is the JSON shape requested when Config.StructuredCompaction is enabled.

func (StructuredCompactionSummary) MarshalJSONMetadata 

func (s StructuredCompactionSummary) MarshalJSONMetadata() map[string]any

MarshalJSONMetadata stores the structured summary on message metadata.

func (StructuredCompactionSummary) ToReadableSummary 

func (s StructuredCompactionSummary) ToReadableSummary() string

ToReadableSummary renders the structured fields as a markdown block for the compaction user message and for models that only see text.

type SystemPromptProvider 

type SystemPromptProvider interface {
	SystemPromptSuffix() string
}

SystemPromptProvider is an optional interface extensions can implement to append content to the system prompt.

type TaskOption added in v1.0.1 

type TaskOption struct {
	Name        string
	Description string
	Tool        *Tool
}

TaskOption describes a sub-agent available through TaskTool.

type ThinkingConfig 

type ThinkingConfig struct {
	// IncludeThoughts asks the provider to return reasoning summaries as
	// `thinking` blocks in the response when available.
	IncludeThoughts bool `json:"include_thoughts,omitempty"`
	// Display controls whether providers should return summarized reasoning
	// blocks or omit their visible text while still keeping internal signatures.
	// If unset, providers infer a display from IncludeThoughts.
	Display ThinkingDisplay `json:"display,omitempty"`
	// Effort hints how much reasoning depth the provider should use when it
	// exposes such a control. Support is provider-specific.
	Effort ThinkingEffort `json:"effort,omitempty"`
	// Budget optionally caps internal reasoning tokens for providers that expose
	// that control. Zero means provider default. Negative values may map to a
	// provider-specific "dynamic" mode where supported.
	Budget int64 `json:"budget,omitempty"`
}

ThinkingConfig requests provider-native reasoning / thought summaries when supported. Providers that do not support explicit thinking controls ignore it.

func CloneThinkingConfig 

func CloneThinkingConfig(c *ThinkingConfig) *ThinkingConfig

func (*ThinkingConfig) NormalizedDisplay 

func (c *ThinkingConfig) NormalizedDisplay() ThinkingDisplay

NormalizedDisplay returns the provider-facing display mode.

func (*ThinkingConfig) VisibleThoughtsEnabled 

func (c *ThinkingConfig) VisibleThoughtsEnabled() bool

VisibleThoughtsEnabled reports whether visible reasoning summaries should be requested from providers.

type ThinkingDisplay 

type ThinkingDisplay string
const (
	ThinkingDisplayDefault    ThinkingDisplay = ""
	ThinkingDisplaySummarized ThinkingDisplay = "summarized"
	ThinkingDisplayOmitted    ThinkingDisplay = "omitted"
)

type ThinkingEffort 

type ThinkingEffort string
const (
	ThinkingEffortDefault ThinkingEffort = ""
	ThinkingEffortLow     ThinkingEffort = "low"
	ThinkingEffortMedium  ThinkingEffort = "medium"
	ThinkingEffortHigh    ThinkingEffort = "high"
	ThinkingEffortMax     ThinkingEffort = "max"
)

type ThreadConfigProvider 

type ThreadConfigProvider interface {
	GetThreadConfig(ctx context.Context, threadID string) (*CallConfig, bool, error)
}

type TokenUsage 

type TokenUsage struct {
	PromptTokens     int64 `json:"prompt_tokens"`
	CompletionTokens int64 `json:"completion_tokens"`
	TotalTokens      int64 `json:"total_tokens"`
}

TokenUsage tracks token consumption for a single request.

type Tool 

type Tool struct {
	Name        string
	Description string
	Tags        []string
	Parameters  map[string]any
	Func        ToolFunc
	Before      []BeforeHook
	After       []AfterHook
}

Tool represents a callable tool available to the agent.

func AgentAsTool 

func AgentAsTool(cfg Config) *Tool

AgentAsTool wraps an Agent config as a Tool that can be registered with a parent agent. The sub-agent runs a full conversation loop when invoked, producing a result string. Events from the sub-agent are forwarded to the parent's EventBus for unified observability.

Parameters schema: 

{"type": "object", "properties": {"input": {"type": "string", "description": "The task to delegate"}}, "required": ["input"]}

func AgentAsToolWithEventBus 

func AgentAsToolWithEventBus(cfg Config, parentBus *EventBus) *Tool

AgentAsToolWithEventBus is like AgentAsTool but forwards the sub-agent's events to the given EventBus for centralized observability.

func NewArtifactReadTool added in v1.0.3 

func NewArtifactReadTool(store ArtifactStore) *Tool

func TaskTool added in v1.0.1 

func TaskTool(name string, options []TaskOption) *Tool

TaskTool creates a meta-tool that lets an LLM delegate work to any of the given sub-agents via a single tool call. The LLM selects a sub-agent by name and provides a task string; the tool routes the call to the matching sub-agent tool.

Each sub-agent's task parameter is automatically wrapped as {"input": "..."} so that tools created via AgentAsTool work out of the box.

Usage: 

tt := TaskTool("delegate", []TaskOption{
    {Name: "coder", Description: "Writes Go code", Tool: AgentAsTool(coderCfg)},
    {Name: "reviewer", Description: "Reviews Go code", Tool: AgentAsTool(reviewCfg)},
})

agent := New(Config{Tools: []*Tool{tt, readFile, writeFile}})

func TaskToolFromConfigs added in v1.0.1 

func TaskToolFromConfigs(name string, configs []Config) *Tool

TaskToolFromConfigs is a convenience wrapper that creates AgentAsTool instances from each Config and then bundles them into a single TaskTool.

func (*Tool) Definition 

func (t *Tool) Definition() ToolDefinition

Definition converts a Tool to its schema representation for the model.

type ToolCall 

type ToolCall struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

ToolCall represents a function call requested by the model.

type ToolCallDelta 

type ToolCallDelta struct {
	Index     int64
	ID        string
	Name      string
	Arguments string
}

ToolCallDelta is an incremental fragment of a tool call during streaming.

type ToolCallEndEvent 

type ToolCallEndEvent struct {
	ToolCallID string        `json:"tool_call_id"`
	ToolName   string        `json:"tool_name"`
	Result     string        `json:"result"`
	Err        error         `json:"error,omitempty"`
	Duration   time.Duration `json:"duration"`
	// contains filtered or unexported fields
}

func (ToolCallEndEvent) EventKind 

func (e ToolCallEndEvent) EventKind() EventType

func (ToolCallEndEvent) EventTime 

func (e ToolCallEndEvent) EventTime() time.Time

func (ToolCallEndEvent) MarshalJSON 

func (e ToolCallEndEvent) MarshalJSON() ([]byte, error)

func (*ToolCallEndEvent) UnmarshalJSON 

func (e *ToolCallEndEvent) UnmarshalJSON(data []byte) error

type ToolCallOverride 

type ToolCallOverride struct {
	Block   bool   // if true, skip execution
	Result  string // result to use when blocked (empty = default error message)
	IsError bool   // whether the override result should be treated as an error
}

ToolCallOverride controls how a loop-level BeforeToolCall can block or replace the execution of a tool call.

type ToolCallStartEvent 

type ToolCallStartEvent struct {
	ToolCall ToolCall `json:"tool_call"`
	// contains filtered or unexported fields
}

func (ToolCallStartEvent) EventKind 

func (e ToolCallStartEvent) EventKind() EventType

func (ToolCallStartEvent) EventTime 

func (e ToolCallStartEvent) EventTime() time.Time

type ToolDefinition 

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"`
	// SearchTerms contains local retrieval tags and is never sent to providers.
	SearchTerms []string `json:"-"`
}

ToolDefinition describes a tool's schema for the model.

type ToolExecutionContext 

type ToolExecutionContext struct {
	ToolCalls []ToolCall
	Results   []ToolResult // nil in Before, populated in After
}

ToolExecutionContext carries context for tool execution hooks.

type ToolFunc 

type ToolFunc func(ctx context.Context, args json.RawMessage) (any, error)

ToolFunc is the function signature for tool implementations.

type ToolProvider 

type ToolProvider interface {
	Tools() []*Tool
}

ToolProvider is an optional interface extensions can implement to contribute tools.

type ToolResult 

type ToolResult struct {
	ToolCallID string
	ToolName   string
	Result     string
	// ForLLM provides alternative content shown to the LLM.
	// When set, this replaces Result in the model context.
	ForLLM string
	// ForUser provides alternative content shown to the user.
	// When set, this replaces Result in the user display.
	ForUser string
	// Silent suppresses display output.
	Silent   bool
	Err      error
	Duration time.Duration
}

ToolResult holds the outcome of a single tool call execution.

func (*ToolResult) EffectiveResult 

func (r *ToolResult) EffectiveResult() string

EffectiveResult returns the content for LLM context.

func (*ToolResult) IsDualOutput 

func (r *ToolResult) IsDualOutput() bool

IsDualOutput returns true when LLM and user outputs differ.

type ToolSelectionConfig added in v1.0.3 

type ToolSelectionConfig struct {
	Selector      ToolSelector
	MaxVisible    int
	AlwaysVisible []string
}

ToolSelectionConfig enables per-request tool visibility filtering.

type ToolSelectionContext added in v1.0.3 

type ToolSelectionContext struct {
	Messages []Message
	Tools    []ToolDefinition
	Limit    int
}

ToolSelectionContext describes the tools and conversation available when choosing which definitions to expose to the model for one request.

type ToolSelector added in v1.0.3 

type ToolSelector interface {
	SelectTools(ctx context.Context, selection ToolSelectionContext) ([]string, error)
}

ToolSelector chooses tool names to expose to the model. The executor keeps the complete registry, so selected tools remain executable by name.

type ToolSelectorFunc added in v1.0.3 

type ToolSelectorFunc func(ctx context.Context, selection ToolSelectionContext) ([]string, error)

func (ToolSelectorFunc) SelectTools added in v1.0.3 

func (f ToolSelectorFunc) SelectTools(ctx context.Context, selection ToolSelectionContext) ([]string, error)

type Tracer 

type Tracer interface {
	Start(ctx context.Context, name string, attrs ...SpanAttribute) (context.Context, Span)
}

Tracer creates spans for tracing agent operations. Set Config.Tracer to plug in your preferred tracing backend.

type TransformContextProvider 

type TransformContextProvider interface {
	TransformContext(ctx context.Context, msgs []Message) []Message
}

TransformContextProvider is an optional interface extensions can implement to inject or rewrite messages before they are sent to the provider.

type TransformRunnable 

type TransformRunnable[I, O any] struct {
	TransformFn func(ctx context.Context, input *StreamReader[I]) (*StreamReader[O], error)
}

func (*TransformRunnable[I, O]) Collect 

func (r *TransformRunnable[I, O]) Collect(ctx context.Context, input *StreamReader[I]) (O, error)

func (*TransformRunnable[I, O]) Invoke 

func (r *TransformRunnable[I, O]) Invoke(ctx context.Context, input I) (O, error)

func (*TransformRunnable[I, O]) Stream 

func (r *TransformRunnable[I, O]) Stream(ctx context.Context, input I) (*StreamReader[O], error)

func (*TransformRunnable[I, O]) Transform 

func (r *TransformRunnable[I, O]) Transform(ctx context.Context, input *StreamReader[I]) (*StreamReader[O], error)

type TruncateEngine 

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

TruncateEngine is a simple context engine that drops old messages without LLM summarization. Useful for testing or when you want fast context management without the cost of a summary LLM call.

It preserves:

  • System message
  • First N messages (ProtectFirstN)
  • Last M tokens (KeepRecentTokens)

Everything in the middle is dropped.

func (*TruncateEngine) CheckFeasibility 

func (e *TruncateEngine) CheckFeasibility(mainModelContextLength int64) string

func (*TruncateEngine) Compress 

func (e *TruncateEngine) Compress(ctx context.Context, msgs []Message, focusTopic string) ([]Message, int64, error)

func (*TruncateEngine) CompressionCount 

func (e *TruncateEngine) CompressionCount() int64

func (*TruncateEngine) ContextLength 

func (e *TruncateEngine) ContextLength() int64

func (*TruncateEngine) GetToolSchemas 

func (e *TruncateEngine) GetToolSchemas() []ToolDefinition

func (*TruncateEngine) LastSavingsPct 

func (e *TruncateEngine) LastSavingsPct() float64

func (*TruncateEngine) Name 

func (e *TruncateEngine) Name() string

func (*TruncateEngine) OnSessionEnd 

func (e *TruncateEngine) OnSessionEnd()

func (*TruncateEngine) OnSessionReset 

func (e *TruncateEngine) OnSessionReset()

func (*TruncateEngine) OnSessionStart 

func (e *TruncateEngine) OnSessionStart(ctx context.Context, model string, contextLength int64)

func (*TruncateEngine) ShouldCompact 

func (e *TruncateEngine) ShouldCompact(msgs []Message, toolDefs []ToolDefinition, contextWindow int64) bool

func (*TruncateEngine) ThresholdTokens 

func (e *TruncateEngine) ThresholdTokens() int64

func (*TruncateEngine) UpdateFromResponse 

func (e *TruncateEngine) UpdateFromResponse(usage TokenUsage)

type TurnEndEvent 

type TurnEndEvent struct {
	Turn  int64      `json:"turn"`
	Usage TokenUsage `json:"usage"`
	// contains filtered or unexported fields
}

func (TurnEndEvent) EventKind 

func (e TurnEndEvent) EventKind() EventType

func (TurnEndEvent) EventTime 

func (e TurnEndEvent) EventTime() time.Time

type TurnInfo 

type TurnInfo struct {
	HadToolCalls bool
}

TurnInfo describes the inner-loop iteration that just finished.

type TurnStartEvent 

type TurnStartEvent struct {
	Turn int64 `json:"turn"`
	// contains filtered or unexported fields
}

func (TurnStartEvent) EventKind 

func (e TurnStartEvent) EventKind() EventType

func (TurnStartEvent) EventTime 

func (e TurnStartEvent) EventTime() time.Time

type UnknownToolHandler 

type UnknownToolHandler func(ctx context.Context, tc ToolCall) (string, error)

UnknownToolHandler is called when the model requests a tool that doesn't exist. It receives the tool call and should return a result string to send back to the model. This is the recommended way to handle LLM "hallucinated" tool names gracefully.

func DefaultUnknownToolHandler 

func DefaultUnknownToolHandler(availableNames []string) UnknownToolHandler

DefaultUnknownToolHandler returns an error message listing available tools.

func DynamicUnknownToolHandler 

func DynamicUnknownToolHandler(registry interface{ Names() []string }) UnknownToolHandler

DynamicUnknownToolHandler returns an error message listing the registry's current tool names, which is useful when tools can be hot-reloaded.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.