agents

Documentation

Overview

Package agents provides interfaces and implementations for spawning AI agents. Unlike providers (which track usage), agents execute tasks autonomously.

claude.go implements the Agent interface for Claude Code CLI.

codex.go implements the Agent interface for OpenAI Codex CLI.

Index

• Constants
• type Agent
• type ClaudeAgent
  • func NewClaudeAgent(opts ...ClaudeOption) *ClaudeAgent
  • func (a *ClaudeAgent) Available() bool
  • func (a *ClaudeAgent) Execute(ctx context.Context, opts ExecuteOptions) (*ExecuteResult, error)
  • func (a *ClaudeAgent) ExecuteWithFiles(ctx context.Context, prompt string, files []string, workDir string) (*ExecuteResult, error)
  • func (a *ClaudeAgent) Name() string
  • func (a *ClaudeAgent) Version() (string, error)
• type ClaudeOption
  • func WithBinaryPath(path string) ClaudeOption
  • func WithDangerouslySkipPermissions(enabled bool) ClaudeOption
  • func WithDefaultTimeout(d time.Duration) ClaudeOption
  • func WithRunner(r CommandRunner) ClaudeOption
• type CodexAgent
  • func NewCodexAgent(opts ...CodexOption) *CodexAgent
  • func (a *CodexAgent) Available() bool
  • func (a *CodexAgent) Execute(ctx context.Context, opts ExecuteOptions) (*ExecuteResult, error)
  • func (a *CodexAgent) ExecuteWithFiles(ctx context.Context, prompt string, files []string, workDir string) (*ExecuteResult, error)
  • func (a *CodexAgent) Name() string
  • func (a *CodexAgent) Version() (string, error)
• type CodexOption
  • func WithCodexBinaryPath(path string) CodexOption
  • func WithCodexDefaultTimeout(d time.Duration) CodexOption
  • func WithCodexRunner(r CommandRunner) CodexOption
  • func WithDangerouslyBypassApprovalsAndSandbox(enabled bool) CodexOption
• type CommandRunner
• type ExecRunner
  • func (r *ExecRunner) Run(ctx context.Context, name string, args []string, dir string, stdin string) (string, string, int, error)
• type ExecuteOptions
• type ExecuteResult
  • func (r *ExecuteResult) IsSuccess() bool

Constants

const DefaultTimeout = 30 * time.Minute

DefaultTimeout is the default agent execution timeout (30 minutes).

Types

type Agent

type Agent interface {
	// Name returns the agent identifier.
	Name() string

	// Execute runs a prompt and returns the output.
	Execute(ctx context.Context, opts ExecuteOptions) (*ExecuteResult, error)
}

Agent is the interface for AI agent execution.

type ClaudeAgent

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

ClaudeAgent spawns Claude Code CLI for task execution.

func NewClaudeAgent

func NewClaudeAgent(opts ...ClaudeOption) *ClaudeAgent

NewClaudeAgent creates a Claude Code agent.

func (*ClaudeAgent) Available

func (a *ClaudeAgent) Available() bool

Available checks if the claude binary is available in PATH.

func (*ClaudeAgent) Execute

func (a *ClaudeAgent) Execute(ctx context.Context, opts ExecuteOptions) (*ExecuteResult, error)

Execute runs claude --print with the given prompt.

func (*ClaudeAgent) ExecuteWithFiles

func (a *ClaudeAgent) ExecuteWithFiles(ctx context.Context, prompt string, files []string, workDir string) (*ExecuteResult, error)

ExecuteWithFiles runs claude with file context included.

func (*ClaudeAgent) Name

func (a *ClaudeAgent) Name() string

Name returns "claude".

func (*ClaudeAgent) Version

func (a *ClaudeAgent) Version() (string, error)

Version returns the claude CLI version.

type ClaudeOption

type ClaudeOption func(*ClaudeAgent)

ClaudeOption configures a ClaudeAgent.

func WithBinaryPath

func WithBinaryPath(path string) ClaudeOption

WithBinaryPath sets a custom path to the claude binary.

func WithDangerouslySkipPermissions

func WithDangerouslySkipPermissions(enabled bool) ClaudeOption

WithDangerouslySkipPermissions sets whether to pass --dangerously-skip-permissions.

func WithDefaultTimeout

func WithDefaultTimeout(d time.Duration) ClaudeOption

WithDefaultTimeout sets the default execution timeout.

func WithRunner

func WithRunner(r CommandRunner) ClaudeOption

WithRunner sets a custom command runner (for testing).

type CodexAgent

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

CodexAgent spawns Codex CLI for task execution.

func NewCodexAgent

func NewCodexAgent(opts ...CodexOption) *CodexAgent

NewCodexAgent creates a Codex CLI agent.

func (*CodexAgent) Available

func (a *CodexAgent) Available() bool

Available checks if the codex binary is available in PATH.

func (*CodexAgent) Execute

func (a *CodexAgent) Execute(ctx context.Context, opts ExecuteOptions) (*ExecuteResult, error)

Execute runs codex with the given prompt in non-interactive mode.

func (*CodexAgent) ExecuteWithFiles

func (a *CodexAgent) ExecuteWithFiles(ctx context.Context, prompt string, files []string, workDir string) (*ExecuteResult, error)

ExecuteWithFiles runs codex with file context included.

func (*CodexAgent) Name

func (a *CodexAgent) Name() string

Name returns "codex".

func (*CodexAgent) Version

func (a *CodexAgent) Version() (string, error)

Version returns the codex CLI version.

type CodexOption

type CodexOption func(*CodexAgent)

CodexOption configures a CodexAgent.

func WithCodexBinaryPath

func WithCodexBinaryPath(path string) CodexOption

WithCodexBinaryPath sets a custom path to the codex binary.

func WithCodexDefaultTimeout

func WithCodexDefaultTimeout(d time.Duration) CodexOption

WithCodexDefaultTimeout sets the default execution timeout.

func WithCodexRunner

func WithCodexRunner(r CommandRunner) CodexOption

WithCodexRunner sets a custom command runner (for testing).

func WithDangerouslyBypassApprovalsAndSandbox

func WithDangerouslyBypassApprovalsAndSandbox(enabled bool) CodexOption

WithDangerouslyBypassApprovalsAndSandbox sets whether to pass --dangerously-bypass-approvals-and-sandbox.

type CommandRunner

type CommandRunner interface {
	Run(ctx context.Context, name string, args []string, dir string, stdin string) (stdout, stderr string, exitCode int, err error)
}

CommandRunner executes shell commands. Allows mocking in tests.

type ExecRunner

type ExecRunner struct{}

ExecRunner is the default CommandRunner using os/exec.

func (*ExecRunner) Run

func (r *ExecRunner) Run(ctx context.Context, name string, args []string, dir string, stdin string) (string, string, int, error)

Run executes a command and returns output.

type ExecuteOptions

type ExecuteOptions struct {
	Prompt  string        // The prompt/task for the agent
	WorkDir string        // Working directory for execution
	Files   []string      // Optional file paths to include as context
	Timeout time.Duration // Execution timeout (0 = default)
}

ExecuteOptions configures an agent execution.

type ExecuteResult

type ExecuteResult struct {
	Output   string        // Agent's text output
	JSON     []byte        // Structured JSON output if available
	ExitCode int           // Process exit code
	Duration time.Duration // Execution duration
	Error    string        // Error message if failed
}

ExecuteResult holds the outcome of an agent execution.

func (*ExecuteResult) IsSuccess

func (r *ExecuteResult) IsSuccess() bool

IsSuccess returns true if the execution succeeded.