Documentation
¶
Overview ¶
Package agentloop is a bounded tool-call broker over a typed registry (ADR-005). Handlers drive guaranteed tools; models may only select from registered, schema-validated tools. Model text never becomes an arbitrary action.
Layout for extension:
- loop.go — Call/Run orchestration and recording
- budget.go — tool/model/wall budgets
- tools.go — registry types + core-tool table (add always-on tools there)
- core_tools.go — default handlers/schemas for core tools
- schema.go — args-schema validation
Job-specific tools (rubrics, PR-history GitHub tools) use Register at loop start.
Index ¶
- Constants
- Variables
- type Budget
- type CallSource
- type Clock
- type Loop
- func (l *Loop) Budget() Budget
- func (l *Loop) Call(ctx context.Context, source CallSource, name string, args json.RawMessage) (json.RawMessage, error)
- func (l *Loop) Calls() []RecordedCall
- func (l *Loop) Register(spec ToolSpec) error
- func (l *Loop) Run(ctx context.Context, gw TurnGateway, prompt string) (RunResult, error)
- type Options
- type RecordedCall
- type RunResult
- type ToolCall
- type ToolHandler
- type ToolSpec
- type TurnGateway
- type TurnResponse
Constants ¶
const ( // DefaultMaxToolCalls is the v1 default tool-call budget. DefaultMaxToolCalls = 50 // DefaultMaxModelCalls is the v1 default model-turn budget. DefaultMaxModelCalls = 20 // DefaultMaxWallTime is the v1 default wall-clock budget. DefaultMaxWallTime = 5 * time.Minute )
const ( ToolSemanticsAnalyze = "semantics_analyze" ToolCodeSignalReport = "codesignal_report" )
Core tool names always registered on a Loop (baseline v1). Additional always-on tools are added to coreToolDefs — not scattered through New/Register.
Variables ¶
var ( // ErrUnknownTool is returned when a call targets a name with no registered handler. ErrUnknownTool = errors.New("agentloop: unknown tool") // ErrBudgetExceeded is returned when a run exhausts max_tool_calls, max_model_calls, // or max_wall_time. ErrBudgetExceeded = errors.New("agentloop: budget exceeded") // ErrInvalidArgs is returned when tool arguments fail the registered args schema. ErrInvalidArgs = errors.New("agentloop: invalid tool arguments") )
Functions ¶
This section is empty.
Types ¶
type CallSource ¶
type CallSource string
CallSource identifies who initiated a tool call (ADR-005 layers 1 and 2).
const ( // CallSourceHandler marks a handler-driven (guaranteed/deterministic) call. CallSourceHandler CallSource = "handler" // CallSourceModel marks a model-selected call from the fixed allowlist. CallSourceModel CallSource = "model" )
type Loop ¶
type Loop struct {
// contains filtered or unexported fields
}
Loop is a bounded tool-call broker over a typed registry (ADR-005).
func New ¶
New constructs a Loop with core tools always registered and the given budget defaults applied.
func (*Loop) Call ¶
func (l *Loop) Call(ctx context.Context, source CallSource, name string, args json.RawMessage) (json.RawMessage, error)
Call invokes a registered tool once under the given source and budgets. Unknown tools, schema-invalid args, and budget exhaustion are typed errors.
func (*Loop) Calls ¶
func (l *Loop) Calls() []RecordedCall
Calls returns a defensive copy of every registry invocation so far, in order.
func (*Loop) Register ¶
Register adds a job-specific tool for this run. Core tool names cannot be replaced here — inject handlers via Options instead.
type Options ¶
type Options struct {
Budget Budget
Clock Clock
SemanticsAnalyze ToolHandler
CodeSignalReport ToolHandler
}
Options configures New. Core tool handlers may be injected; nil uses package defaults. When adding a new always-on core tool, extend Options (if injectable) and coreToolDefs.
type RecordedCall ¶
type RecordedCall struct {
Name string
Source CallSource
Args json.RawMessage
Result json.RawMessage
Err error
}
RecordedCall is one registry invocation observed by Calls().
type RunResult ¶
type RunResult struct {
FinalText string
}
RunResult is the outcome of a multi-turn Run that ends on a text-only model turn.
type ToolCall ¶
type ToolCall struct {
Name string
Args json.RawMessage
}
ToolCall is one model- or handler-requested invocation.
type ToolHandler ¶
type ToolHandler func(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
ToolHandler is the function shape registered under a tool name.
func DefaultCodeSignalReport ¶
func DefaultCodeSignalReport() ToolHandler
DefaultCodeSignalReport returns a thin wrapper around pkg/codesignal.
func DefaultSemanticsAnalyze ¶
func DefaultSemanticsAnalyze() ToolHandler
DefaultSemanticsAnalyze returns a thin wrapper around pkg/semantics.
type ToolSpec ¶
type ToolSpec struct {
Name string
ArgsSchema json.RawMessage
Handler ToolHandler
}
ToolSpec describes a named, schema-validated tool handler.
type TurnGateway ¶
type TurnGateway interface {
Generate(ctx context.Context, prompt string) (TurnResponse, error)
}
TurnGateway is the multi-turn model seam for tool-call sequences. Distinct from modelgateway.Gateway (Judge-only); production wiring and tests inject adapters without pulling LLM HTTP clients into this package.
type TurnResponse ¶
TurnResponse is one model generation result used by the loop's multi-turn seam.
Source Files