agent

Documentation

Overview

Package agent runs a Claude agent invocation and returns its result alongside token/cost accounting and a JSONL transcript.

Index

• Constants
• Variables
• type Config
• type Result
  • func Run(ctx context.Context, cfg Config) (Result, error)
• type StreamEvent
• type StreamEventType
• type StreamHandler
• type Tool

Constants

const (
	DefaultModel     = "claude-opus-4-7"
	DefaultMaxTokens = 4096
)

Variables

var ErrBudgetExceeded = errors.New("agent run exceeded configured budget")

ErrBudgetExceeded is returned when the run's actual cost crosses cfg.BudgetUSD.

Types

type Config

type Config struct {
	Prompt        string
	System        string
	Model         string
	MaxTokens     int
	BudgetUSD     float64
	APIKey        string
	TranscriptDir string
	RunID         string
	// StreamHandler, when non-nil, is called with semantic streaming events
	// (text/thinking deltas, tool use start/delta/stop) as they arrive from
	// the API. Use it to render deltas in real time. The aggregated Result
	// is still returned by Run regardless. nil = silent (still streamed
	// internally; no per-delta callback fired).
	StreamHandler StreamHandler
	// Tools is the set of tools the model can invoke. Each tool's
	// Definition is sent on every turn; Execute is called when the model
	// emits a matching tool_use block. When empty, the agent runs single
	// turn (no tool dispatch).
	Tools []Tool
	// MaxTurns bounds the agent loop iterations. Default 1 when no Tools,
	// otherwise treated as 30. The loop also exits naturally when the
	// model's stop_reason != "tool_use".
	MaxTurns int
}

Config carries the inputs for a single agent invocation.

type Result

type Result struct {
	exec.Result
	Model          string
	InputTokens    int
	OutputTokens   int
	CacheReadIn    int
	CacheWriteIn   int
	CostUSD        float64
	StopReason     string
	TranscriptPath string
}

Result is what an agent run produces. It embeds exec.Result so it can drop into the rest of cronicle's task execution path; the agent-specific fields (tokens, cost, transcript path) are additive.

func Run

func Run(ctx context.Context, cfg Config) (Result, error)

Run drives the multi-turn agent loop: send conversation, stream the response, dispatch any tool_use blocks to the configured Tools, append tool_result blocks back into the conversation, and continue until the model stops calling tools, MaxTurns is reached, the context is cancelled (for wallclock bounds), or BudgetUSD is exceeded mid-run. With no Tools configured, the loop terminates after one turn (single-turn behavior preserved). The transcript captures every turn and tool result.

type StreamEvent

type StreamEvent struct {
	Type       StreamEventType
	Text       string // text_delta and thinking_delta carry the partial text here
	ToolID     string // tool_use_* events
	ToolName   string // tool_use_start; also tool_result
	ToolInput  string // tool_use_delta carries partial JSON here
	ToolOutput string // tool_result: the executed tool's output
	IsError    bool   // tool_result: did the tool fail
	DurationMs int64  // tool_result: execution time
	TurnIndex  int    // turn_start: 0-based turn number
}

StreamEvent is a single semantic event from an agent run.

type StreamEventType

type StreamEventType string

StreamEventType identifies the kind of streaming event.

const (
	StreamEventTextDelta     StreamEventType = "text_delta"
	StreamEventThinkingDelta StreamEventType = "thinking_delta"
	StreamEventToolUseStart  StreamEventType = "tool_use_start"
	StreamEventToolUseDelta  StreamEventType = "tool_use_delta"
	StreamEventToolUseStop   StreamEventType = "tool_use_stop"
	// StreamEventToolResult fires after cronicle has executed a tool and
	// has the result string ready. Not from the API stream — emitted by
	// the agent loop itself.
	StreamEventToolResult StreamEventType = "tool_result"
	// StreamEventTurnStart fires at the top of each loop iteration after
	// the first. Useful for renderers that want to delineate turns.
	StreamEventTurnStart StreamEventType = "turn_start"
)

type StreamHandler

type StreamHandler func(StreamEvent)

StreamHandler is called with each StreamEvent as it arrives.

type Tool

type Tool interface {
	// Name is the tool name as the model sees it (e.g. "bash").
	Name() string
	// Definition returns the SDK tool param union (one of the Anthropic-
	// defined tool variants like ToolBash20250124Param, or a custom
	// ToolParam).
	Definition() anthropic.ToolUnionParam
	// Execute runs the tool with input from the model. The returned string
	// becomes the tool_result content; isError reports whether the tool
	// failed (the model gets a tool_result with is_error=true and can
	// recover).
	Execute(ctx context.Context, input json.RawMessage) (output string, isError bool)
}

Tool is an executable tool the agent can invoke. Implementations live in the cronicle wrapper (so they can use pkg/exec etc. without an import cycle on this package).