agent

package
v0.10.1 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ToolSearchReservedName = "tool_search"

	ToolTransportTUI = "tui"
	ToolTransportWeb = "web"
	ToolTransportACP = "acp"

	ToolModeNormal = "normal"
	ToolModePlan   = "plan"
)
View Source 
const DefaultMaxLengthForTrunc = 50000

DefaultMaxLengthForTrunc is the per-result character cap: tool outputs above this are offloaded to a file and truncated in the conversation.

View Source 
const DefaultTurnToolResultBudget = 150_000

DefaultTurnToolResultBudget is the default aggregate character budget for one turn's new tool results: three full-size (50k) results, ~37k tokens.

Variables

View Source 
var ReductionExcludeTools = []string{"ask_user", "load_skill"}

ReductionExcludeTools lists tools whose results must never be truncated: their content is irreplaceable direct input (a user's answer, a loaded skill body), not re-derivable command output. Shared by the reduction middleware's TruncExcludeTools and the per-turn budget middleware.

Functions

func BuildReductionConfig added in v0.9.2 

func BuildReductionConfig(
	rootDir string,
	contextLimit int,
	compactThreshold float64,
	counter func(ctx context.Context, msgs []*schema.Message, tools []*schema.ToolInfo) (int64, error),
) *reduction.Config

BuildReductionConfig is the single source for the reduction middleware configuration shared by all surfaces (TUI/ACP/web). rootDir is where offloaded content is written (both the Backend fallback root and the offload path base). contextLimit is the RAW model window; the clear trigger is computed on the EFFECTIVE window (output headroom reserved) so it uses the same base as the summarization trigger. counter is the TokenCounter to inject; nil keeps eino's default (len/4).

It returns the config rather than the constructed middleware so callers can wrap it in reduction.New and tests can assert fields directly.

func CompactHistory 

func CompactHistory(ctx context.Context, cm einomodel.BaseChatModel, history []adk.Message) []adk.Message

CompactHistory summarizes the conversation history using the model, replacing all messages with a system summary + the last few messages.

func DrainBgNotifications 

func DrainBgNotifications(bm *tools.BackgroundManager, history []adk.Message) []adk.Message

DrainBgNotifications injects any completed background task results into the conversation history so the agent is aware of them on the next turn.

func NewAgent 

func NewAgent(
	ctx context.Context,
	chatmodel model.ToolCallingChatModel,
	tools []tool.BaseTool,
	instruction string,
	approvalFunc ApprovalFunc,
	middlewares []adk.ChatModelAgentMiddleware,
	handlers []adk.ChatModelAgentMiddleware,
) (*adk.ChatModelAgent, error)

NewAgent creates a ChatModelAgent with the following handler stack (outermost to innermost): 

Handlers: [langfuse tracing, ...caller handlers, approval+safeTool]

All tools passed to this compatibility entry point are disclosed directly to the model. Use NewAgentWithToolPlan to progressively disclose deferred tools. ModelRetryConfig is always enabled (5 retries with smart backoff).

func NewAgentWithToolPlan added in v0.10.1 

func NewAgentWithToolPlan(
	ctx context.Context,
	chatmodel model.ToolCallingChatModel,
	plan ToolPlan,
	instruction string,
	approvalFunc ApprovalFunc,
	middlewares []adk.ChatModelAgentMiddleware,
	handlers []adk.ChatModelAgentMiddleware,
) (*adk.ChatModelAgent, error)

NewAgentWithToolPlan creates a ChatModelAgent from a validated exposure plan. Direct tools are disclosed on the first model call. Deferred tools are kept in the executable tool registry but their schemas are disclosed only after the model calls tool_search. Hidden tools are neither disclosed nor registered.

DirectModelOnly is deliberately unsupported by the current chat-model path: it has no safe way to expose a schema without also registering an executable endpoint. A non-empty partition therefore fails closed.

func NewBudgetMiddleware 

func NewBudgetMiddleware(manager *BudgetManager, tokenUsage *internalmodel.TokenUsage, onWarn func(BudgetStatus)) adk.ChatModelAgentMiddleware

NewBudgetMiddleware creates a ChatModelAgentMiddleware that tracks budget. tokenUsage is the per-agent tracker to read from. onWarn is called when the budget warning level changes to WarningApproach or WarningExceeded. It may be nil.

func NewCompactionMiddleware 

func NewCompactionMiddleware(strategy CompactionStrategy, contextLimit int, tokenUsage *internalmodel.TokenUsage, onCompact func(int)) adk.ChatModelAgentMiddleware

NewCompactionMiddleware creates a ChatModelAgentMiddleware that monitors token usage and compacts the conversation when the strategy says to. tokenUsage is the per-agent tracker to read from. onCompact is an optional callback invoked after a successful compaction.

func NewReminderMiddleware 

func NewReminderMiddleware(cfg ReminderConfig, tokenUsage *internalmodel.TokenUsage) adk.ChatModelAgentMiddleware

NewReminderMiddleware creates a ChatModelAgentMiddleware that injects conditional reminders (todo check, token warning, error streak, external file changes, env drift, AGENTS.md reload) into the message stream before each model invocation. tokenUsage is the per-agent tracker to read from; may be nil.

func NewTeammateHandlers 

func NewTeammateHandlers(approvalFunc ApprovalFunc) []adk.ChatModelAgentMiddleware

NewTeammateHandlers returns the middleware stack for a teammate agent. It includes the approval + safe-tool-error middleware with the given approval function.

func NewTurnToolResultBudgetMiddleware added in v0.9.2 

func NewTurnToolResultBudgetMiddleware(maxChars int) adk.ChatModelAgentMiddleware

NewTurnToolResultBudgetMiddleware creates a middleware enforcing an aggregate character budget across the trailing batch of tool results. maxChars <= 0 selects DefaultTurnToolResultBudget. Tools in ReductionExcludeTools are never truncated.

func ReductionThreshold added in v0.9.2 

func ReductionThreshold(compactThreshold float64) float64

ReductionThreshold derives the reduction (tool-output clearing) trigger fraction from the compaction threshold: the lighter, earlier clearing sits 0.15 below compaction; when that would drop under 0.1 it falls back to 80% of the compaction threshold. Single source for what was previously copy-pasted (and drifting) across the TUI/ACP/web surfaces.

func SyncSummarization 

func SyncSummarization(cap *SummarizationCapture, history []adk.Message, rec *session.Recorder) []adk.Message

SyncSummarization checks whether Eino's summarization middleware fired during the last runner.Run() and, if so, replaces history with the compacted version so the next turn starts from the summarized state.

func ToolCallIDFromContext added in v0.9.4 

func ToolCallIDFromContext(ctx context.Context) string

ToolCallIDFromContext returns the tool-call id stamped by the approval middleware, or "" when the context is not part of a tool invocation.

func TruncateStr 

func TruncateStr(s string, maxLen int) string

TruncateStr truncates a string to maxLen characters, appending "..." if truncated.

func WithToolCallID added in v0.9.4 

func WithToolCallID(ctx context.Context, id string) context.Context

WithToolCallID returns a context carrying the tool-call id of the invocation currently flowing through the middleware chain.

func WithToolObservationSink added in v0.10.1 

func WithToolObservationSink(ctx context.Context, sink ToolObservationSink) context.Context

WithToolObservationSink enables metadata collection for one runner turn. The shared run object keeps request sequence numbers monotonic across the runner's bounded continuation calls.

Types

type ApprovalFunc 

type ApprovalFunc func(ctx context.Context, toolName, toolArgs string) (bool, error)

type BudgetManager 

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

BudgetManager tracks token consumption and cost against configurable limits.

func NewBudgetManager 

func NewBudgetManager(cfg *config.BudgetConfig, pricing internalmodel.ModelPricing) *BudgetManager

NewBudgetManager creates a BudgetManager from config and model pricing. A nil BudgetConfig results in a manager with no limits.

func (*BudgetManager) Check 

func (b *BudgetManager) Check() (BudgetStatus, bool)

Check returns the current budget status and whether the budget has been exceeded.

func (*BudgetManager) Status 

func (b *BudgetManager) Status() BudgetStatus

Status returns the current budget status without modifying state.

func (*BudgetManager) Track 

func (b *BudgetManager) Track(promptTokens, completionTokens int64) BudgetStatus

Track records a model call's token usage and returns the updated status.

type BudgetStatus 

type BudgetStatus struct {
	PromptTokens     int64
	CompletionTokens int64
	TotalTokens      int64
	EstimatedCost    float64
	RemainingBudget  float64
	WarningLevel     WarningLevel
}

BudgetStatus is a snapshot of current token/cost usage.

type CompactionState 

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

CompactionState tracks compaction history for diagnostics.

func (*CompactionState) CompactionCount 

func (cs *CompactionState) CompactionCount() int

CompactionCount returns how many compactions have occurred.

func (*CompactionState) SavedTokens 

func (cs *CompactionState) SavedTokens() int

SavedTokens returns the total estimated tokens saved by compaction.

type CompactionStrategy 

type CompactionStrategy interface {
	// ShouldCompact returns true when the current token count warrants compaction.
	ShouldCompact(currentTokens, limit int) bool
	// Compact compresses the messages slice, keeping the most recent keepRecent
	// messages intact and summarising the rest.
	Compact(ctx context.Context, messages []*schema.Message, keepRecent int) ([]*schema.Message, error)
}

CompactionStrategy decides when and how to compact conversation history.

type LocalReductionBackend 

type LocalReductionBackend struct {
	RootDir string
}

LocalReductionBackend implements reduction.Backend by writing truncated tool output to local files so the agent can re-read them via the read tool.

func (*LocalReductionBackend) Write 

func (b *LocalReductionBackend) Write(_ context.Context, req *filesystem.WriteRequest) error

type ReminderConfig 

type ReminderConfig struct {
	TodoStore    *tools.TodoStore
	GoalStore    *tools.GoalStore
	PlanStore    *tools.PlanStore
	EnvLabel     string
	IsRemote     bool
	ContextLimit int
	TaskManager  *tools.SubagentTaskManager

	// FileTracker, when non-nil, is swept before each model call for files
	// modified outside the session since the agent last read them.
	FileTracker *tools.FileTracker

	// Env, when non-nil, is the live tool environment. switch_env mutates it
	// in place (local ↔ SSH/Docker) without rebuilding the agent on every
	// surface, so remote-ness is re-read from here each round: while remote,
	// the env-drift / AGENTS.md / external-file sweeps are paused — they all
	// inspect the LOCAL filesystem and would report wrong-host state.
	Env *tools.Env

	// Pwd enables the periodic environment refresh and the AGENTS.md reload
	// check. Empty disables both (remote sessions, subagents, tests).
	Pwd string
	// Platform is the platform string used when serializing env snapshots.
	Platform string
	// EnvSnapshot is the SerializeEnvInfo baseline captured at startup. When
	// empty, the first refresh cycle only establishes a baseline (no diff).
	EnvSnapshot string
	// EnvRefreshEvery is the env-refresh cadence in model iterations;
	// 0 means defaultEnvRefreshEvery.
	EnvRefreshEvery int
	// EnvCollector overrides the environment collector (for tests); nil uses
	// utils.CollectEnvInfoLight.
	EnvCollector func(pwd string) *utils.EnvInfo
}

ReminderConfig holds the static configuration for the reminder middleware.

type ReviewDeniedError added in v0.9.6 

type ReviewDeniedError struct{ Reason string }

ReviewDeniedError is returned by an ApprovalFunc when the automatic safety reviewer (not the user) denied a call. The approval middleware special-cases it to surface the reviewer's rationale to the model with distinct guidance, instead of the generic "rejected by user" message.

func (*ReviewDeniedError) Error added in v0.9.6 

func (e *ReviewDeniedError) Error() string

type SummarizationCapture 

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

SummarizationCapture captures the result when Eino's summarization middleware fires, so that the application-level history can be synced afterwards.

func (*SummarizationCapture) Capture 

func (c *SummarizationCapture) Capture(summary string, compactedN int)

Capture records a summarization event. Called from the Finalize callback.

type ThresholdCompactionStrategy 

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

ThresholdCompactionStrategy triggers compaction when token usage exceeds a configurable fraction of the context limit and uses a chat model to generate a summary of older messages.

func NewThresholdCompactionStrategy 

func NewThresholdCompactionStrategy(threshold float64, summarizer einomodel.ToolCallingChatModel, keepRecent int) *ThresholdCompactionStrategy

NewThresholdCompactionStrategy creates a compaction strategy. threshold is the fraction (0-1) of the context limit that triggers compaction. summarizer is the model used to generate summaries. keepRecent is the number of recent messages to preserve verbatim.

func (*ThresholdCompactionStrategy) Compact 

func (s *ThresholdCompactionStrategy) Compact(ctx context.Context, messages []*schema.Message, keepRecent int) ([]*schema.Message, error)

func (*ThresholdCompactionStrategy) ShouldCompact 

func (s *ThresholdCompactionStrategy) ShouldCompact(currentTokens, limit int) bool

type ToolDescriptor added in v0.10.1 

type ToolDescriptor struct {
	Tool                 tool.BaseTool
	Name                 string
	Aliases              []string
	Source               string
	Bundle               string
	DisclosureGroup      string
	Exposure             ToolExposure
	Transports           []string
	Modes                []string
	RequiredCapabilities []string
	ApprovalClass        string
}

ToolDescriptor is the transport-independent metadata for one executable tool. Empty transport/mode lists mean the tool is available in every transport/mode. RequiredCapabilities uses all-of semantics.

type ToolExposure added in v0.10.1 

type ToolExposure string

ToolExposure controls when a registered tool is disclosed to the model. 

const (
	ToolExposureDirect          ToolExposure = "direct"
	ToolExposureDeferred        ToolExposure = "deferred"
	ToolExposureHidden          ToolExposure = "hidden"
	ToolExposureDirectModelOnly ToolExposure = "direct_model_only"
)

type ToolObservation added in v0.10.1 

type ToolObservation struct {
	Kind ToolObservationKind

	ModelRequestSeq      int
	VisibleNames         []string
	VisibleCount         int
	SchemaBytes          int
	SchemaTokensEstimate int64
	NewlyVisibleDeferred []string

	ToolCallID           string
	QueryMode            string
	QueryBytes           int
	TermCount            int
	RequiredTermCount    int
	MaxResults           int
	ValidatedSelectNames []string
	UnknownSelectCount   int
	MatchNames           []string
	NewMatchNames        []string
	RepeatedQuery        bool
	Redundant            bool
	Success              bool

	ToolName string
	Reason   string
}

ToolObservation is safe-to-persist metadata used by the evaluation harness. Only the fields relevant to Kind are populated.

type ToolObservationKind added in v0.10.1 

type ToolObservationKind string

ToolObservationKind identifies one metadata-only progressive-disclosure observation. Observations deliberately exclude model messages, raw search queries, tool arguments, schemas, outputs, and errors. 

const (
	ToolObservationModelRequest ToolObservationKind = "model_request"
	ToolObservationSearch       ToolObservationKind = "tool_search"
	ToolObservationBypass       ToolObservationKind = "deferred_bypass"
)

type ToolObservationSink added in v0.10.1 

type ToolObservationSink func(ToolObservation)

ToolObservationSink receives metadata synchronously. Implementations must be goroutine-safe because tool calls in one model response may run concurrently.

type ToolPlan added in v0.10.1 

type ToolPlan struct {
	Direct          []ToolDescriptor
	Deferred        []ToolDescriptor
	Hidden          []ToolDescriptor
	DirectModelOnly []ToolDescriptor
}

ToolPlan is the effective, stably ordered exposure plan for one context.

func (ToolPlan) AllRuntimeTools added in v0.10.1 

func (p ToolPlan) AllRuntimeTools() []tool.BaseTool

AllRuntimeTools returns every executable endpoint in stable name order. Hidden tools are deliberately excluded: a transport, mode, or capability gate must be an execution boundary, not merely a schema-visibility hint.

func (ToolPlan) DeferredTools added in v0.10.1 

func (p ToolPlan) DeferredTools() []tool.BaseTool

DeferredTools returns a new slice containing the tools available to search.

func (ToolPlan) DirectTools added in v0.10.1 

func (p ToolPlan) DirectTools() []tool.BaseTool

DirectTools returns a new slice containing the tools disclosed initially.

func (ToolPlan) Validate added in v0.10.1 

func (p ToolPlan) Validate() error

Validate checks that no effective plan partition contains the same tool name.

type ToolPlanBuilder added in v0.10.1 

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

ToolPlanBuilder validates descriptors and classifies them for a runtime context.

func NewToolPlanBuilder added in v0.10.1 

func NewToolPlanBuilder(descriptors []ToolDescriptor) *ToolPlanBuilder

func (*ToolPlanBuilder) Build added in v0.10.1 

func (b *ToolPlanBuilder) Build(ctx context.Context, planContext ToolPlanContext) (ToolPlan, error)

Build returns an effective plan. A descriptor that fails a transport, mode, or capability gate is retained in Hidden so callers can inspect why it was omitted.

type ToolPlanContext added in v0.10.1 

type ToolPlanContext struct {
	Transport    string
	Mode         string
	Capabilities map[string]bool
}

ToolPlanContext identifies the runtime surface for which a plan is built.

type WarningLevel 

type WarningLevel int

WarningLevel indicates the severity of a budget warning. 

const (
	WarningNone     WarningLevel = iota
	WarningApproach              // approaching budget limit
	WarningExceeded              // budget limit exceeded
)

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.