agent

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 7, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package agent provides agent (subagent) execution for GenCode. Agents are specialized LLM instances that can be spawned to handle specific tasks with isolated contexts and tool restrictions.

Index

Constants

View Source 
const DefaultMaxTurns = 50

DefaultMaxTurns is the default maximum number of conversation turns

View Source 
const FallbackModel = "claude-sonnet-4-20250514"

FallbackModel is used when no parent model is available

Variables

View Source 
var DefaultRegistry = NewRegistry()

DefaultRegistry is the global agent registry

Functions

func Init 

func Init(cwd string)

Init is called to initialize the agent system This should be called during application startup It loads custom agents and initializes the enabled/disabled state stores

func LoadCustomAgents 

func LoadCustomAgents(cwd string)

LoadCustomAgents loads custom agent definitions from standard locations. Search order (priority):

  1. .gen/agents/*.md (project level, preferred)
  2. ~/.gen/agents/*.md (user level, preferred)
  3. .claude/agents/*.md (project level, Claude Code compatible)
  4. ~/.claude/agents/*.md (user level, Claude Code compatible)

Types

type AgentConfig 

type AgentConfig struct {
	// Name is the unique identifier for this agent type
	Name string `yaml:"name" json:"name"`

	// Description describes what this agent does (used for LLM decision making)
	Description string `yaml:"description" json:"description"`

	// Model specifies the model to use (inherit, sonnet, opus, haiku)
	Model string `yaml:"model" json:"model"`

	// PermissionMode controls how permissions are handled
	PermissionMode PermissionMode `yaml:"permission-mode" json:"permission_mode"`

	// Tools configures available tools
	Tools ToolAccess `yaml:"tools" json:"tools"`

	// Skills lists skills to preload
	Skills []string `yaml:"skills,omitempty" json:"skills,omitempty"`

	// SystemPrompt provides additional system prompt content
	SystemPrompt string `yaml:"system-prompt,omitempty" json:"system_prompt,omitempty"`

	// MaxTurns limits the number of conversation turns
	MaxTurns int `yaml:"max-turns" json:"max_turns"`

	// Background indicates whether this agent runs in background by default
	Background bool `yaml:"background" json:"background"`

	// SourceFile is the file path if loaded from AGENT.md (internal use)
	SourceFile string `yaml:"-" json:"-"`
}

AgentConfig defines the configuration for an agent type

type AgentFrontmatter 

type AgentFrontmatter struct {
	Name           string   `yaml:"name"`
	Description    string   `yaml:"description"`
	Model          string   `yaml:"model"`
	PermissionMode string   `yaml:"permission-mode"`
	MaxTurns       int      `yaml:"max-turns"`
	Background     bool     `yaml:"background"`
	Skills         []string `yaml:"skills"`
	Tools          struct {
		Mode  string   `yaml:"mode"`
		Allow []string `yaml:"allow"`
		Deny  []string `yaml:"deny"`
	} `yaml:"tools"`
}

AgentFrontmatter represents the YAML frontmatter structure in AGENT.md files This is used for parsing custom agents

type AgentRequest 

type AgentRequest struct {
	// Agent is the name of the agent type to use
	Agent string

	// Prompt is the task for the agent to perform
	Prompt string

	// Description is a short (3-5 word) description of the task
	Description string

	// Background if true, runs the agent in background
	Background bool

	// ResumeID is the ID of a previous agent to resume
	ResumeID string

	// Model overrides the agent's default model
	Model string

	// MaxTurns overrides the agent's max turns
	MaxTurns int

	// ParentMessages is the conversation history from the parent (for context)
	ParentMessages []provider.Message

	// Cwd is the current working directory
	Cwd string

	// OnProgress is called when the agent makes progress (tool execution, etc.)
	OnProgress ProgressCallback
}

AgentRequest represents a request to spawn an agent

type AgentResult 

type AgentResult struct {
	// AgentID is the unique identifier for this agent instance
	AgentID string

	// AgentName is the name of the agent type used
	AgentName string

	// Success indicates whether the agent completed successfully
	Success bool

	// Content is the final response content from the agent
	Content string

	// Summary is a brief summary of what was accomplished
	Summary string

	// Messages contains the full conversation history
	Messages []provider.Message

	// TurnCount is the number of turns used
	TurnCount int

	// TokenUsage is the total tokens consumed
	TokenUsage TokenUsage

	// Duration is the total execution time
	Duration time.Duration

	// Error contains any error message if not successful
	Error string
}

AgentResult contains the result of an agent execution

type AgentStore 

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

AgentStore handles persistence of agent enabled/disabled states

func NewAgentStore 

func NewAgentStore(path string) *AgentStore

NewAgentStore creates a new store at the given path

func NewProjectAgentStore 

func NewProjectAgentStore(cwd string) *AgentStore

NewProjectAgentStore creates a store for project-level (.gen/agents.json)

func NewUserAgentStore 

func NewUserAgentStore() *AgentStore

NewUserAgentStore creates a store for user-level (~/.gen/agents.json)

func (*AgentStore) GetDisabled 

func (s *AgentStore) GetDisabled() map[string]bool

GetDisabled returns a copy of the disabled agents map

func (*AgentStore) IsDisabled 

func (s *AgentStore) IsDisabled(name string) bool

IsDisabled returns whether an agent is disabled

func (*AgentStore) SetDisabled 

func (s *AgentStore) SetDisabled(name string, disabled bool) error

SetDisabled sets the disabled state for an agent

type AgentStoreData 

type AgentStoreData struct {
	Disabled []string `json:"disabled"`
}

AgentStoreData is the JSON structure for agents.json

type Executor 

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

Executor runs agent LLM loops

func NewExecutor 

func NewExecutor(llmProvider provider.LLMProvider, cwd string, parentModelID string) *Executor

NewExecutor creates a new agent executor parentModelID is the model used by the parent conversation (for inheritance)

func (*Executor) GetParentModelID 

func (e *Executor) GetParentModelID() string

GetParentModelID returns the parent model ID

func (*Executor) Run 

func (e *Executor) Run(ctx context.Context, req AgentRequest) (*AgentResult, error)

Run executes an agent request and returns the result For background agents, this should be called in a goroutine

func (*Executor) RunBackground 

func (e *Executor) RunBackground(req AgentRequest) (*task.AgentTask, error)

RunBackground executes an agent in the background and returns the task

type ExecutorAdapter 

type ExecutorAdapter struct {
	*Executor
}

ExecutorAdapter adapts the Executor to implement tool.AgentExecutor

func NewExecutorAdapter 

func NewExecutorAdapter(executor *Executor) *ExecutorAdapter

NewExecutorAdapter creates a new adapter for the Executor

func (*ExecutorAdapter) GetAgentConfig 

func (a *ExecutorAdapter) GetAgentConfig(agentType string) (tool.AgentConfigInfo, bool)

GetAgentConfig returns configuration for an agent type Returns false if agent is not found or is disabled

func (*ExecutorAdapter) GetParentModelID 

func (a *ExecutorAdapter) GetParentModelID() string

GetParentModelID returns the parent conversation's model ID

func (*ExecutorAdapter) Run 

func (a *ExecutorAdapter) Run(ctx context.Context, req tool.AgentExecRequest) (*tool.AgentExecResult, error)

Run executes an agent and returns the result

func (*ExecutorAdapter) RunBackground 

func (a *ExecutorAdapter) RunBackground(req tool.AgentExecRequest) (tool.AgentTaskInfo, error)

RunBackground executes an agent in background

type PermissionMode 

type PermissionMode string

PermissionMode controls how the agent handles permission requests 

const (
	// PermissionDefault uses normal permission flow
	PermissionDefault PermissionMode = "default"
	// PermissionAcceptEdits auto-accepts file edits but asks for commands
	PermissionAcceptEdits PermissionMode = "acceptEdits"
	// PermissionDontAsk auto-accepts all operations
	PermissionDontAsk PermissionMode = "dontAsk"
	// PermissionPlan is read-only mode (plan mode)
	PermissionPlan PermissionMode = "plan"
)

type ProgressCallback 

type ProgressCallback func(msg string)

ProgressCallback is called when the agent makes progress

type Registry 

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

Registry manages agent type definitions

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new agent registry

func (*Registry) Get 

func (r *Registry) Get(name string) (*AgentConfig, bool)

Get retrieves an agent configuration by name

func (*Registry) GetAgentPromptForLLM 

func (r *Registry) GetAgentPromptForLLM() string

GetAgentPromptForLLM returns a formatted string describing available agents. This is used to inform the LLM about what agents are available. Only includes enabled agents. Returns content wrapped in <available-agents> XML tags for consistency.

func (*Registry) GetDisabledAt 

func (r *Registry) GetDisabledAt(userLevel bool) map[string]bool

GetDisabledAt returns the disabled agents from the specified level

func (*Registry) InitStores 

func (r *Registry) InitStores(cwd string) error

InitStores initializes the user and project stores for enabled/disabled state

func (*Registry) IsEnabled 

func (r *Registry) IsEnabled(name string) bool

IsEnabled returns whether an agent is enabled An agent is enabled unless explicitly disabled in either store Project-level settings take priority over user-level

func (*Registry) List 

func (r *Registry) List() []string

List returns all registered agent names

func (*Registry) ListConfigs 

func (r *Registry) ListConfigs() []*AgentConfig

ListConfigs returns all registered agent configurations

func (*Registry) ListEnabled 

func (r *Registry) ListEnabled() []*AgentConfig

ListEnabled returns only enabled agent configurations

func (*Registry) Register 

func (r *Registry) Register(config *AgentConfig)

Register adds an agent configuration to the registry

func (*Registry) SetEnabled 

func (r *Registry) SetEnabled(name string, enabled bool, userLevel bool) error

SetEnabled sets the enabled state for an agent at the specified level

type TokenUsage 

type TokenUsage struct {
	InputTokens  int
	OutputTokens int
	TotalTokens  int
}

TokenUsage tracks token consumption

type ToolAccess 

type ToolAccess struct {
	Mode  ToolAccessMode `yaml:"mode" json:"mode"`
	Allow []string       `yaml:"allow,omitempty" json:"allow,omitempty"`
	Deny  []string       `yaml:"deny,omitempty" json:"deny,omitempty"`
}

ToolAccess configures which tools are available to the agent

type ToolAccessMode 

type ToolAccessMode string

ToolAccessMode controls how tool access is configured 

const (
	// ToolAccessAllowlist only allows specified tools
	ToolAccessAllowlist ToolAccessMode = "allowlist"
	// ToolAccessDenylist allows all except specified tools
	ToolAccessDenylist ToolAccessMode = "denylist"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.