Documentation
¶
Overview ¶
Package agent is EXPERIMENTAL — tool-calling agent loop with safety-gated shell. It is subordinate to observed state and emits warnings automatically.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent drives a multi-turn tool-calling loop on top of the chat client. It is strictly a consumer of the fact plane — its output is never cluster truth.
func (*Agent) Conversation ¶
func (a *Agent) Conversation() *chat.Conversation
Conversation returns the underlying conversation for inspection/testing.
type Config ¶
type Config struct {
Endpoint string // Ollama endpoint (default: chat.DefaultEndpoint)
Model string // Ollama model name
MaxTurns int // Maximum agent loop iterations (default: 10)
MaxTokens int // Conversation token budget (default: 4096)
AutoApprove bool // Auto-approve safe commands (score < 70)
SystemExtra string // Extra text appended to system prompt
Verbose bool // Emit trace output for tool calls and turns
DryRun bool // Plan tool calls without executing them
// Cluster is optional. If non-nil, the agent injects a cluster summary
// into the system prompt and uses it for safety checks.
Cluster *chat.ClusterSummaryForPrompt
// Knowledge is optional. Used for safety gating shell commands.
Knowledge *knowledge.ClusterKnowledge
// Snapshot and State are used to initialize tools.
ToolContext *ToolContext
// Output is where the agent writes assistant text and traces.
Output io.Writer
// Confirm is the confirmation function. If nil, StdinConfirm() is used.
Confirm ConfirmFunc
// RunShell executes an approved shell command. If nil, the agent falls back
// to a direct local shell helper.
RunShell ShellRunner
}
Config configures an Agent.
type ConfirmFunc ¶
type ConfirmFunc func(toolName, description string, safetyScore int) ConfirmResult
ConfirmFunc asks the operator for confirmation before executing a tool call. It receives the tool name, a human-readable description of what will happen, and the safety score (0-100). It returns the operator's decision.
func AutoApproveConfirm ¶
func AutoApproveConfirm(threshold int, fallback ConfirmFunc) ConfirmFunc
AutoApproveConfirm returns a ConfirmFunc that auto-approves read-only tools and tools with safety score below the threshold, but still prompts for anything risky.
func DefaultConfirm ¶
func DefaultConfirm(r io.Reader, w io.Writer) ConfirmFunc
DefaultConfirm reads from stdin, writing the prompt to w.
func StdinConfirm ¶
func StdinConfirm() ConfirmFunc
StdinConfirm is a convenience for the common case of prompting on stdout/stdin.
type ConfirmResult ¶
type ConfirmResult int
ConfirmResult is the operator's response to a tool-execution prompt.
const ( ConfirmYes ConfirmResult = iota // Execute this one time ConfirmNo // Skip this tool call ConfirmAlways // Auto-approve all future calls this session ConfirmNever // Block all future calls this session )
type ShellRunner ¶ added in v0.7.0
ShellRunner executes an approved shell command and returns the tool-visible output. CLI callers can route this through guarded AXIS execution.
type ShellSafetyGate ¶
ShellSafetyGate is called before executing any shell command. It receives the command string and returns (allow bool, reason string, score int). If allow is false, the command is not executed and reason is returned to the model.
func DefaultSafetyGate ¶
func DefaultSafetyGate(k *knowledge.ClusterKnowledge) ShellSafetyGate
DefaultSafetyGate uses the safety package to gate shell commands.
type ToolContext ¶
type ToolContext struct {
Snapshot *models.ClusterSnapshot
State *state.ClusterState
}
ToolContext holds runtime state available to tool executors.
type ToolExecutor ¶
ToolExecutor runs a tool and returns its string result.
type ToolRegistry ¶
type ToolRegistry struct {
// contains filtered or unexported fields
}
ToolRegistry maps tool names to their definitions and executors.
func NewToolRegistry ¶
func NewToolRegistry(tc *ToolContext) *ToolRegistry
NewToolRegistry creates the default set of agent tools.
func (*ToolRegistry) Defs ¶
func (r *ToolRegistry) Defs() []chat.ToolDef
Defs returns Ollama-compatible tool definitions for the /api/chat request.
func (*ToolRegistry) Execute ¶
func (r *ToolRegistry) Execute(ctx context.Context, name string, args json.RawMessage) (string, error)
Execute dispatches a tool call. Returns an error message string (not a Go error) so the agent loop can feed it back to the model for self-correction.
func (*ToolRegistry) HasTool ¶
func (r *ToolRegistry) HasTool(name string) bool
HasTool returns true if the named tool is registered.
Source Files