Documentation
¶
Overview ¶
Package local provides an embedded local mode for running agents in-process with filesystem access. This enables CLI assistants like Gemini CLI and Codex that lack native sub-agents to leverage multi-agent orchestration via MCP.
Index ¶
- type AgentConfig
- type AgentInfo
- type AgentResult
- type AgentTask
- type CommandResult
- type CompletionResponse
- type Config
- type ConfigFormat
- type Duration
- type EmbeddedAgent
- type FileInfo
- type GlobTool
- type GrepMatch
- type GrepTool
- type LLMClient
- type LLMConfig
- type MCPConfig
- type Message
- type OrchestratedResult
- type OrchestratedTask
- type ReadTool
- type Runner
- func (r *Runner) Close() error
- func (r *Runner) ExecuteOrchestrated(ctx context.Context, task OrchestratedTask) (*OrchestratedResult, error)
- func (r *Runner) GetAgent(name string) (*EmbeddedAgent, bool)
- func (r *Runner) GetAgentInfo(name string) (*AgentInfo, error)
- func (r *Runner) Invoke(ctx context.Context, agentName, input string) (*AgentResult, error)
- func (r *Runner) InvokeParallel(ctx context.Context, tasks []AgentTask) ([]*AgentResult, error)
- func (r *Runner) InvokeSequential(ctx context.Context, tasks []AgentTask) ([]*AgentResult, error)
- func (r *Runner) ListAgentInfo() []AgentInfo
- func (r *Runner) ListAgents() []string
- func (r *Runner) ToolSet() *ToolSet
- func (r *Runner) Workspace() string
- type ShellTool
- type TimeoutConfig
- type Tool
- type ToolCall
- type ToolDefinition
- type ToolSet
- func (ts *ToolSet) CreateTools(names []string) ([]Tool, error)
- func (ts *ToolSet) GlobFiles(ctx context.Context, pattern string) ([]string, error)
- func (ts *ToolSet) GrepFiles(ctx context.Context, pattern, filePattern string) ([]GrepMatch, error)
- func (ts *ToolSet) ListDirectory(ctx context.Context, path string) ([]FileInfo, error)
- func (ts *ToolSet) ReadFile(ctx context.Context, path string) (string, error)
- func (ts *ToolSet) RunCommand(ctx context.Context, command string, args []string) (*CommandResult, error)
- func (ts *ToolSet) RunShell(ctx context.Context, shellCmd string) (*CommandResult, error)
- func (ts *ToolSet) SetMaxFileSize(size int64)
- func (ts *ToolSet) WriteFile(ctx context.Context, path, content string) error
- type WriteTool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentConfig ¶
type AgentConfig struct {
// Name is the unique identifier for the agent.
Name string `yaml:"name" json:"name"`
// Description explains when to use this agent.
Description string `yaml:"description" json:"description"`
// Instructions is the system prompt or path to a markdown file.
Instructions string `yaml:"instructions" json:"instructions"`
// Tools lists the tools available to this agent.
// Available: read, write, glob, grep, shell
Tools []string `yaml:"tools" json:"tools"`
// Model overrides the default LLM model for this agent.
Model string `yaml:"model,omitempty" json:"model,omitempty"`
// MaxTokens limits the response length.
MaxTokens int `yaml:"max_tokens,omitempty" json:"max_tokens,omitempty"`
}
AgentConfig defines a single agent.
type AgentResult ¶
type AgentResult struct {
Agent string `json:"agent"`
Input string `json:"input"`
Output string `json:"output"`
Success bool `json:"success"`
Error string `json:"error,omitempty"`
}
AgentResult holds the result of an agent invocation.
type CommandResult ¶
type CommandResult struct {
Command string `json:"command"`
Args []string `json:"args,omitempty"`
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
ExitCode int `json:"exit_code"`
}
CommandResult holds the result of a command execution.
func (*CommandResult) Success ¶
func (r *CommandResult) Success() bool
Success returns true if the command exited successfully.
type CompletionResponse ¶
type CompletionResponse struct {
Content string `json:"content"`
ToolCalls []ToolCall `json:"tool_calls,omitempty"`
Done bool `json:"done"`
}
CompletionResponse holds the LLM response.
type Config ¶
type Config struct {
// Mode should be "local" for embedded mode.
Mode string `yaml:"mode" json:"mode"`
// Workspace is the root directory for filesystem access.
// Defaults to current working directory.
Workspace string `yaml:"workspace" json:"workspace"`
// Agents defines the available agents.
Agents []AgentConfig `yaml:"agents" json:"agents"`
// MCP configures the MCP server interface.
MCP MCPConfig `yaml:"mcp" json:"mcp"`
// LLM configures the language model.
LLM LLMConfig `yaml:"llm" json:"llm"`
// Timeouts for various operations.
Timeouts TimeoutConfig `yaml:"timeouts" json:"timeouts"`
}
Config holds configuration for local embedded mode.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a configuration with sensible defaults.
func LoadConfig ¶
LoadConfig loads configuration from a JSON or YAML file. The format is detected by file extension (.json, .yaml, .yml).
func LoadConfigFromBytes ¶
func LoadConfigFromBytes(data []byte, format ConfigFormat) (*Config, error)
LoadConfigFromBytes loads configuration from bytes with explicit format.
func (*Config) GetAgentConfig ¶
func (c *Config) GetAgentConfig(name string) (*AgentConfig, error)
GetAgentConfig returns the configuration for a specific agent.
func (*Config) ListAgentNames ¶
ListAgentNames returns the names of all configured agents.
type ConfigFormat ¶
type ConfigFormat string
ConfigFormat specifies the configuration file format.
const ( // FormatJSON indicates JSON format. FormatJSON ConfigFormat = "json" // FormatYAML indicates YAML format. FormatYAML ConfigFormat = "yaml" )
type Duration ¶
Duration is a time.Duration that supports human-readable strings in JSON/YAML. Examples: "5m", "30s", "2h30m", "100ms"
func (Duration) MarshalJSON ¶
MarshalJSON implements json.Marshaler for Duration.
func (*Duration) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler for Duration.
func (*Duration) UnmarshalYAML ¶
UnmarshalYAML implements yaml.Unmarshaler for Duration.
type EmbeddedAgent ¶
type EmbeddedAgent struct {
// contains filtered or unexported fields
}
EmbeddedAgent is a lightweight agent that runs in-process.
func NewEmbeddedAgent ¶
func NewEmbeddedAgent(cfg AgentConfig, toolSet *ToolSet, llm LLMClient) (*EmbeddedAgent, error)
NewEmbeddedAgent creates a new embedded agent.
func (*EmbeddedAgent) Description ¶
func (a *EmbeddedAgent) Description() string
Description returns the agent's description.
func (*EmbeddedAgent) Invoke ¶
func (a *EmbeddedAgent) Invoke(ctx context.Context, input string) (*AgentResult, error)
Invoke runs the agent with the given input and returns the result.
type FileInfo ¶
type FileInfo struct {
Name string `json:"name"`
IsDir bool `json:"is_dir"`
Size int64 `json:"size"`
}
FileInfo holds basic file information.
type GlobTool ¶
type GlobTool struct {
// contains filtered or unexported fields
}
GlobTool wraps GlobFiles as a Tool interface.
func (*GlobTool) Description ¶
type GrepMatch ¶
type GrepMatch struct {
File string `json:"file"`
Line int `json:"line"`
Content string `json:"content"`
}
GrepMatch represents a single grep match.
type GrepTool ¶
type GrepTool struct {
// contains filtered or unexported fields
}
GrepTool wraps GrepFiles as a Tool interface.
func (*GrepTool) Description ¶
type LLMClient ¶
type LLMClient interface {
// Complete generates a completion for the given messages.
Complete(ctx context.Context, messages []Message, tools []ToolDefinition) (*CompletionResponse, error)
}
LLMClient defines the interface for language model interactions.
type LLMConfig ¶
type LLMConfig struct {
// Provider is the LLM provider: "openai", "anthropic", "gemini", "ollama".
Provider string `yaml:"provider" json:"provider"`
// Model is the default model to use.
Model string `yaml:"model" json:"model"`
// APIKey is the API key (can use env var reference like ${OPENAI_API_KEY}).
APIKey string `yaml:"api_key,omitempty" json:"api_key,omitempty"`
// BaseURL overrides the API base URL.
BaseURL string `yaml:"base_url,omitempty" json:"base_url,omitempty"`
// Temperature controls randomness (0.0-1.0).
Temperature float64 `yaml:"temperature,omitempty" json:"temperature,omitempty"`
}
LLMConfig configures the language model provider.
type MCPConfig ¶
type MCPConfig struct {
// Enabled determines if the MCP server is active.
Enabled bool `yaml:"enabled" json:"enabled"`
// Transport is the MCP transport type: "stdio" or "http".
Transport string `yaml:"transport" json:"transport"`
// Port is used when transport is "http".
Port int `yaml:"port,omitempty" json:"port,omitempty"`
// ServerName is the name reported in MCP server info.
ServerName string `yaml:"server_name,omitempty" json:"server_name,omitempty"`
// ServerVersion is the version reported in MCP server info.
ServerVersion string `yaml:"server_version,omitempty" json:"server_version,omitempty"`
}
MCPConfig configures the MCP server interface.
type Message ¶
type Message struct {
Role string `json:"role"` // "system", "user", "assistant", "tool"
Content string `json:"content"`
Name string `json:"name,omitempty"` // For tool messages
ToolID string `json:"tool_id,omitempty"` // For tool messages
}
Message represents a chat message.
type OrchestratedResult ¶
type OrchestratedResult struct {
Task string `json:"task"`
Mode string `json:"mode"`
Results []*AgentResult `json:"results"`
}
OrchestratedResult holds the results of an orchestrated task.
func (*OrchestratedResult) AllSuccessful ¶
func (r *OrchestratedResult) AllSuccessful() bool
AllSuccessful returns true if all agent results were successful.
func (*OrchestratedResult) Summary ¶
func (r *OrchestratedResult) Summary() string
Summary returns a summary of all results.
type OrchestratedTask ¶
type OrchestratedTask struct {
// Name is a descriptive name for the task.
Name string `json:"name"`
// Agents lists the agents to involve, in order of execution for sequential,
// or all at once for parallel.
Agents []string `json:"agents"`
// Input is the task description/prompt.
Input string `json:"input"`
// Mode is "parallel" or "sequential".
Mode string `json:"mode"`
}
OrchestratedTask represents a high-level task that may involve multiple agents.
type ReadTool ¶
type ReadTool struct {
// contains filtered or unexported fields
}
ReadTool wraps ReadFile as a Tool interface.
func (*ReadTool) Description ¶
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner orchestrates multiple embedded agents.
func (*Runner) ExecuteOrchestrated ¶
func (r *Runner) ExecuteOrchestrated(ctx context.Context, task OrchestratedTask) (*OrchestratedResult, error)
ExecuteOrchestrated runs an orchestrated task involving multiple agents.
func (*Runner) GetAgent ¶
func (r *Runner) GetAgent(name string) (*EmbeddedAgent, bool)
GetAgent returns an agent by name.
func (*Runner) GetAgentInfo ¶
GetAgentInfo returns information about an agent.
func (*Runner) InvokeParallel ¶
InvokeParallel runs multiple agents concurrently.
func (*Runner) InvokeSequential ¶
InvokeSequential runs multiple agents in sequence, passing context between them.
func (*Runner) ListAgentInfo ¶
ListAgentInfo returns information about all registered agents.
func (*Runner) ListAgents ¶
ListAgents returns the names of all registered agents.
type ShellTool ¶
type ShellTool struct {
// contains filtered or unexported fields
}
ShellTool wraps RunShell as a Tool interface.
func (*ShellTool) Description ¶
type TimeoutConfig ¶
type TimeoutConfig struct {
// AgentInvoke is the timeout for a single agent invocation.
AgentInvoke Duration `yaml:"agent_invoke" json:"agent_invoke"`
// ShellCommand is the timeout for shell command execution.
ShellCommand Duration `yaml:"shell_command" json:"shell_command"`
// FileRead is the timeout for file read operations.
FileRead Duration `yaml:"file_read" json:"file_read"`
// ParallelTotal is the total timeout for parallel agent execution.
ParallelTotal Duration `yaml:"parallel_total" json:"parallel_total"`
}
TimeoutConfig defines timeouts for various operations.
type Tool ¶
type Tool interface {
Name() string
Description() string
Execute(ctx context.Context, args map[string]any) (any, error)
}
Tool represents a capability available to agents.
type ToolCall ¶
type ToolCall struct {
ID string `json:"id"`
Name string `json:"name"`
Arguments map[string]any `json:"arguments"`
}
ToolCall represents an LLM's request to call a tool.
type ToolDefinition ¶
type ToolDefinition struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters map[string]interface{} `json:"parameters"`
}
ToolDefinition defines a tool for the LLM.
type ToolSet ¶
type ToolSet struct {
// contains filtered or unexported fields
}
ToolSet provides filesystem and shell tools scoped to a workspace.
func NewToolSet ¶
NewToolSet creates a new tool set for the given workspace.
func (*ToolSet) CreateTools ¶
CreateTools creates Tool instances for the specified tool names.
func (*ToolSet) ListDirectory ¶
ListDirectory lists the contents of a directory within the workspace.
func (*ToolSet) RunCommand ¶
func (ts *ToolSet) RunCommand(ctx context.Context, command string, args []string) (*CommandResult, error)
RunCommand executes a shell command within the workspace.
func (*ToolSet) SetMaxFileSize ¶
SetMaxFileSize sets the maximum file size for read operations.