Documentation
¶
Overview ¶
Package agent provides the bucket-1 shim over ADK v2's runner and llmagent primitives. It hides the llmagent.Config boilerplate behind mast-shaped constructors and encodes the mode conventions the design corpus uses (Task-mode specialists, SingleTurn classifiers, Chat-mode coordinators).
Index ¶
- Constants
- func NewCoordinator(cfg CoordinatorConfig) (adkagent.Agent, error)
- func NewEchoModel(name string) model.LLM
- func NewSingleTurnAgent(cfg SingleTurnAgentConfig) (adkagent.Agent, error)
- func NewTaskAgent(cfg TaskAgentConfig) (adkagent.Agent, error)
- func NewToolActorModel(name string) model.LLM
- type CoordinatorConfig
- type SingleTurnAgentConfig
- type TaskAgentConfig
Constants ¶
const DefaultChatInstruction = `` /* 751-byte string literal not displayed */
DefaultChatInstruction is the fallback system prompt for Chat-mode agents (NewCoordinator). Chat mode fronts an interactive operator — an attach-mode terminal or a mast-web session — so the framing is conversational rather than autonomous (docs/positioning.md, "Change shape" -> DefaultInstruction: "Chat-mode gets conversational framing for attach-mode / mast-web operators").
const DefaultSingleTurnInstruction = `` /* 334-byte string literal not displayed */
DefaultSingleTurnInstruction is the fallback system prompt for SingleTurn-mode agents (NewSingleTurnAgent). SingleTurn agents are classifier-shaped — one model call, no tool loop — so the default is deliberately minimal (docs/positioning.md, "Change shape" -> DefaultInstruction: "SingleTurn-mode gets minimal framing (used by LLM-as-router classifiers)").
const DefaultTaskInstruction = `` /* 1270-byte string literal not displayed */
DefaultTaskInstruction is the fallback system prompt for Task-mode agents (NewTaskAgent). Task mode is mast's unattended workhorse, so the default encodes the unattended-loop discipline from docs/positioning.md ("Change shape" -> DefaultInstruction): conservative defaults; explicit state persistence to the eventlog; fail-fast on ambiguity; structured tool preference; plan-before-act; subagents over open-ended search.
Variables ¶
This section is empty.
Functions ¶
func NewCoordinator ¶
func NewCoordinator(cfg CoordinatorConfig) (adkagent.Agent, error)
NewCoordinator constructs a Chat-mode LlmAgent with the given sub-agents and tools. The coordinator drives the top-level conversation; sub-agents handle delegated tasks.
When cfg.Instruction is empty, DefaultChatInstruction is used. A non-empty Instruction is used verbatim — callers with a bundle-specific prompt (e.g. router.Build's per-workload coordinator default) keep full control.
func NewEchoModel ¶
NewEchoModel returns a model.LLM that responds to any request with a canned "acknowledged" reply summarising the last user message. It makes no network calls and requires no credentials, so it lets the runtime wiring be smoke-tested end-to-end without ADK-model dependencies.
This is a spike-only helper; it will be replaced by google.golang.org/adk/v2/model/gemini.NewModel once the real Gemini wiring lands (spike step 6).
func NewSingleTurnAgent ¶
func NewSingleTurnAgent(cfg SingleTurnAgentConfig) (adkagent.Agent, error)
NewSingleTurnAgent constructs a SingleTurn-mode agent.
When cfg.Instruction is empty, DefaultSingleTurnInstruction is used. A non-empty Instruction is used verbatim — specialists keep full control of their prompt; nothing is prepended.
func NewTaskAgent ¶
func NewTaskAgent(cfg TaskAgentConfig) (adkagent.Agent, error)
NewTaskAgent constructs a Task-mode agent. Suitable for per-failure-mode specialists (diagnose, remediate, return a structured digest).
When cfg.Instruction is empty, DefaultTaskInstruction is used. A non-empty Instruction is used verbatim — specialists keep full control of their prompt; nothing is prepended.
func NewToolActorModel ¶ added in v0.2.0
NewToolActorModel returns a REQUEST-DRIVEN offline fake model that drives registered tool calls deterministically — the double the v0.2 end-to-end UAT (scripts/uat-v0.2.sh) needs to exercise the crash / drain / abort legs against a real, blocking MCP tool.
Why not the scripted provider (pkg/providers/mock)? The scripted model replays a fixed positional list of turns behind a single global cursor that RESETS to 0 on every process restart. The legs this UAT targets restart the daemon mid-flight, and the daemon's model-call count differs before vs. after a restart (auto-resume drives a continuation turn; an ambiguous-effect session refuses the mutating call; etc.), so a positional script and the live call sequence drift apart across exactly the crash-restart boundary under test. A request-driven double has no cursor: it decides purely from the current request, so it is restart-safe, session-independent, and needs no per-leg JSONL. This is a documented deviation from docs/uat-v0.2-plan.md's "scripted provider" note (which predates local/stdio MCP); see that doc's implementation status.
Behavior, decided per request:
- Coordinator turn (Chat mode: a sub-agent "task" tool is offered, finish_task is not): if the delegation tool has not yet produced a response in the history, call it once (delegate to the worker); otherwise emit a short final text (the worker's result has come back — the turn is done).
- Worker turn (Task mode: finish_task is offered): if the incident envelope's reason selects a UAT tool (apply -> apply_change, read -> read_status) that is registered and not yet answered in the history, call it once; otherwise call finish_task.
Selecting the tool from the inject reason keeps each leg's control in the harness's payload (reason "ApplyChange" vs "ReadStatus"), not in a brittle out-of-band script. It is offline and credential-free.
Set MAST_TOOLACTOR_DEBUG=1 to log each request's offered tool names and the chosen action to stderr — used when adapting the fixture to a new ADK tool-naming convention.
Types ¶
type CoordinatorConfig ¶
type CoordinatorConfig struct {
Name string
Description string
Instruction string
Model model.LLM
SubAgents []adkagent.Agent
Tools []tool.Tool
Toolsets []tool.Toolset
}
CoordinatorConfig bundles the parameters for constructing a Chat-mode coordinator with Task or SingleTurn sub-agents. ADK auto-installs a task tool for each Task sub-agent and a single_turn tool for each SingleTurn sub-agent — the coordinator's LLM invokes sub-agents by calling those tools. No explicit agenttool.New call is required for this dispatch pattern.
type SingleTurnAgentConfig ¶
type SingleTurnAgentConfig struct {
Name string
Description string
Instruction string
Model model.LLM
InputSchema *genai.Schema
OutputSchema *genai.Schema
}
SingleTurnAgentConfig bundles the parameters for constructing a SingleTurn-mode LlmAgent. SingleTurn agents run exactly one model call; no finish_task loop. Cheap and predictable — the shape behind LLM-as-router classifiers.
type TaskAgentConfig ¶
type TaskAgentConfig struct {
Name string
Description string
Instruction string
Model model.LLM
Tools []tool.Tool
Toolsets []tool.Toolset
OutputSchema *genai.Schema
}
TaskAgentConfig bundles the parameters for constructing a Task-mode LlmAgent. Task-mode agents auto-install the ADK-provided finish_task helper; the value the agent passes to finish_task becomes the agent's output.
Source Files