Documentation
¶
Overview ¶
Package subagent runs child agents in-process.
It lives under runtime/ rather than plugins/ because it must import runtime/agent to construct a child — the same reason agent/coding is registered from runtime/agent. Kind names are independent of package paths.
Why the child needs its own tool runtime ¶
Wiring the parent's tool runtime here would be a dependency cycle:
tools.default → tool.subagent.default → subagent.default → tools.default
pluginkit rejects that at build time. So deps.tools must point at a sibling runtime instance, and since that instance does not mount tool/subagent, "only the main agent can delegate" stops being a policy and becomes structural.
Index ¶
- func DefaultDefinitionDirs() []string
- func FindDefinition(defs []subagent.Definition, name string) (subagent.Definition, bool)
- func HelpCommand(ws workspace.Service, dirs []string) agentkit.Command
- func LoadDefinitions(ctx context.Context, ws workspace.Service, dirs []string) ([]subagent.Definition, error)
- func New(cfg Config, deps Deps) (subagent.Spawner, error)
- func NewComposite(_ struct{}, deps CompositeDeps) (subagent.Spawner, error)
- func NewLoopAgent(cfg LoopAgentConfig, deps LoopAgentDeps) (subagent.Spawner, error)
- type CompositeDeps
- type Config
- type Deps
- type LoopAgentConfig
- type LoopAgentDeps
- type LoopAgentEntry
- type LoopAgentSpawner
- type Spawner
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultDefinitionDirs ¶ added in v0.1.2
func DefaultDefinitionDirs() []string
DefaultDefinitionDirs returns the dirs scanned when config.dirs is empty.
func FindDefinition ¶ added in v0.1.2
func FindDefinition(defs []subagent.Definition, name string) (subagent.Definition, bool)
FindDefinition looks up a definition by name, case-insensitively.
func HelpCommand ¶ added in v0.1.2
HelpCommand exposes the subagent definition help slash command.
func LoadDefinitions ¶ added in v0.1.2
func LoadDefinitions(ctx context.Context, ws workspace.Service, dirs []string) ([]subagent.Definition, error)
LoadDefinitions scans dirs in precedence order and returns subagent definitions.
func New ¶
New registers subagent/inprocess: Run a child agent in-process from an agents/<name>.md definition and return only its conclusion.
Best practices:
- deps.tools must be a sibling tools/runtime instance that does NOT mount tool/subagent: wiring the parent's runtime is a dependency cycle, and the separate instance is what makes 'only the main agent delegates' structural.
- Give the child a narrower tool set than the parent — read-only is the common case. Delegation is for context isolation, not for a second agent editing the same workspace.
- Pair with prompt/section/subagents so the parent can see who it may delegate to; the delegate tool's description is static and cannot list definitions read from disk.
- Raise the delegate entry in the parent's toolTimeouts: a child agent takes far longer than a normal tool call.
func NewComposite ¶ added in v0.1.24
func NewComposite(_ struct{}, deps CompositeDeps) (subagent.Spawner, error)
NewComposite registers subagent/composite: merge inprocess and loop-agent delegatable catalogs.
func NewLoopAgent ¶ added in v0.1.24
func NewLoopAgent(cfg LoopAgentConfig, deps LoopAgentDeps) (subagent.Spawner, error)
NewLoopAgent registers subagent/loop-agent: delegate to a Loop agent instance and return only its conclusion.
Types ¶
type CompositeDeps ¶ added in v0.1.24
type CompositeDeps struct {
Inprocess subagent.Spawner `json:"inprocess"`
Loop subagent.Spawner `json:"loop,omitempty"`
}
CompositeDeps merges multiple spawners. Inprocess definitions win on name conflict.
type Config ¶
type Config struct {
// Dirs are definition directories in precedence order; defaults to local:agents then global:agents.
Dirs []string `json:"dirs,omitempty"`
// MaxSteps is step cap for definitions that do not set their own; defaults to 20.
MaxSteps int `json:"maxSteps,omitempty"`
// TimeoutSeconds is wall clock for one delegation; 0 leaves the delegate tool's own timeout as the only bound.
TimeoutSeconds int `json:"timeoutSeconds,omitempty"`
}
type Deps ¶
type Deps struct {
Workspace workspace.Service `json:"workspace"`
SessionStore agentkit.SessionStore `json:"sessionStore"`
LLM agentkit.LLMProvider `json:"llm"`
Tools agentkit.ToolRuntime `json:"tools"`
Prompt agentkit.PromptAssembler `json:"prompt"`
Hooks agentkit.HookRuntime `json:"hooks,omitempty"`
Compaction []compaction.Service `json:"compaction,omitempty"`
}
type LoopAgentConfig ¶ added in v0.1.24
type LoopAgentConfig struct {
// Agents lists Loop-backed subagents exposed to the delegate tool.
Agents []LoopAgentEntry `json:"agents,omitempty"`
// TimeoutSeconds is the default wall clock for one delegation.
TimeoutSeconds int `json:"timeoutSeconds,omitempty"`
}
LoopAgentConfig configures subagent/loop-agent.
type LoopAgentDeps ¶ added in v0.1.24
type LoopAgentDeps struct {
SessionStore agentkit.SessionStore `json:"sessionStore"`
Agents []agentkit.Agent `json:"agents"`
}
LoopAgentDeps holds injected capabilities for Loop-backed delegation.
type LoopAgentEntry ¶ added in v0.1.24
type LoopAgentEntry struct {
Name string `json:"name"`
Description string `json:"description"`
Agent string `json:"agent"`
Async bool `json:"async,omitempty"`
TimeoutSeconds int `json:"timeoutSeconds,omitempty"`
}
LoopAgentEntry configures one delegatable Loop agent.
type LoopAgentSpawner ¶ added in v0.1.24
type LoopAgentSpawner struct {
// contains filtered or unexported fields
}
LoopAgentSpawner delegates to configured Loop agents (e.g. agent/acp-remote).
func (*LoopAgentSpawner) BindSubmit ¶ added in v0.1.24
func (s *LoopAgentSpawner) BindSubmit(fn capschedule.SubmitFunc)
func (*LoopAgentSpawner) Definitions ¶ added in v0.1.24
func (s *LoopAgentSpawner) Definitions(context.Context) ([]subagent.Definition, error)
type Spawner ¶
type Spawner struct {
// contains filtered or unexported fields
}
Source Files