Version 1

Auto-generated from config struct types and tags.

Config

Config is the root of .agentsmithy.yaml. It declares the project identity, the model and tool catalogs the pipeline draws from, and the pipeline itself: the agent (or composition of agents) that runs when the service is invoked.

Field	Type	Required	Default	Description
`version`	string	yes	—	Config schema version. Must be "1".
`project`	Project	yes	—	Project identity and the model catalog the pipeline draws from.
`tools`	Tools	no	—	Tool catalog. Names declared here are referenced by pipeline and sub-agent `tools:` lists.
`pipeline`	Pipeline	yes	—	The pipeline that runs when this service is invoked.

Project

Project declares top-level identity for the service: the service name, the root system prompt, and the model catalog the pipeline draws from.

Field	Type	Required	Default	Description
`name`	string	yes	—	Service name. Used in logs and as the A2A service identifier other agents address this pipeline by.
`instruction`	string	yes	—	System prompt for the root pipeline agent. Sub-agents declare their own instruction inside their kind block.
`models`	Models	yes	—	Model catalog grouped by provider. At least one model must be declared so the pipeline (and any descendants) has something to run on.

Tools

Tools is the tool catalog. Tools listed here can be referenced by pipeline and sub-agent tools: lists by name. Categories (mcp, a2a) reflect how the tool is reached at runtime. Each entry maps the named mcp/agents to the endpoint that serves it.

Field	Type	Required	Default	Exclusivity	Description
`mcp`	map[string]string	no	—		MCP tools. Each value is the streamable HTTP endpoint of one MCP server (e.g. "http://localhost:8080").
`a2a`	map[string]string	no	—		Agent-to-agent endpoints. Each value is the base URL of another agentsmithy or A2A-compatible service the pipeline can call as a tool.

Pipeline

Pipeline is the root agent. Exactly one kind block must be set; the chosen kind's struct dictates which fields are valid and which are required. Pipeline carries no name: or instruction: of its own (those live at the file root) and cannot inherit (it has no ancestor).

Field	Type	Required	Default	Exclusivity	Description
`autonomous`	Autonomous	oneof	—	mutually exclusive with `sequential`, `parallel`, `loop`, `orchestrator`	Single LLM agent that decides its own tool calls. The 90% case.
`sequential`	Sequential	oneof	—	mutually exclusive with `autonomous`, `parallel`, `loop`, `orchestrator`	Sub-agents run in declaration order, sharing transcript history.
`parallel`	Parallel	oneof	—	mutually exclusive with `autonomous`, `sequential`, `loop`, `orchestrator`	Sub-agents fan out concurrently against the same input; outputs collected as `map[name]string`.
`loop`	Loop	oneof	—	mutually exclusive with `autonomous`, `sequential`, `parallel`, `orchestrator`	Sub-agents run repeatedly until an exit signal fires (`exit_loop`, `until:`, or `maxIterations`).
`orchestrator`	Orchestrator	oneof	—	mutually exclusive with `autonomous`, `sequential`, `parallel`, `loop`	Explicit step graph wired with Go templates. Steps reference prior step outputs and call tools, sub-agents, or skills via helpers.

Models

Models is the model catalog, keyed by provider. Each provider holds a map of author-chosen aliases to model entries. These aliases are what model: refs point to.

Field	Type	Required	Default	Description
`openai`	map[string]ModelEntry	no	—	OpenAI native and OpenAI-compatible endpoints. Use baseUrl on the entry to target a compatible server (Ollama, LM Studio, vLLM, Together, Groq, OpenRouter, DeepSeek, xAI).
`anthropic`	map[string]ModelEntry	no	—	Anthropic Claude (native Messages API).
`google`	map[string]ModelEntry	no	—	Google Gemini (developer API key).
`bedrock`	map[string]ModelEntry	no	—	AWS Bedrock-hosted models.
`vertex`	map[string]ModelEntry	no	—	Google Vertex AI-hosted models.
`borrowed`	map[string]ModelEntry	no	—	Borrowed: delegate completion to the connecting MCP client via sampling/createMessage. Requires an MCP transport.

Autonomous

Autonomous is a single LLM agent that decides its own tool calls. The 90% case. Sub-agents listed here are delegation targets the LLM may hand control to via transfer_to_agent.

Field	Type	Required	Default	Description
`instruction`	string	no	—	System prompt for this agent. Required on sub-agents (enforced by SubAgent.Validate); the root pipeline reads its instruction from project.instruction instead.
`inherits`	InheritField[]	no	—	Fields to pull from the nearest ancestor that declares them. Local declarations always win; `inherits:` only fills gaps. Not valid on the root pipeline (it has no ancestor).
`model`	ModelRef	no	—	Reference into the model catalog.
`tools`	string[]	no	—	Tool names from the root `tools:` catalog this agent may use. (must reference a declared key in: tools.mcp, tools.a2a)
`skills`	Skills	no	—	Built-in skills bound to this agent.
`memory`	Memory	no	—	Memory overrides (kind-aware defaults apply when unset).
`subagents`	SubAgent[]	no	—	Delegation targets the LLM may hand control to.
`maxIterations`	integer	no	—	Cap on guard-driven retries. (min: 1)
`output`	TemplateString	no	—	Return-value template. Defaults to the LLM's final reply.

Sequential

Sequential runs sub-agents in declaration order, sharing transcript history. Each sub-agent sees the prior sub-agents' outputs as inbound context.

Field	Type	Required	Default	Description
`instruction`	string	no	—	System prompt for this agent. Required on sub-agents (enforced by SubAgent.Validate); the root pipeline reads its instruction from project.instruction instead.
`inherits`	InheritField[]	no	—	Fields to pull from the nearest ancestor that declares them.
`model`	ModelRef	no	—	Reference into the model catalog. Backs the `{{ prompt }}` helper in `output:` and is the inheritance source for descendants.
`tools`	string[]	no	—	Tool names this agent's `output:` template may reference. (must reference a declared key in: tools.mcp, tools.a2a)
`skills`	Skills	no	—	Built-in skills bound to this agent.
`memory`	Memory	no	—	Memory overrides (kind-aware defaults apply when unset).
`subagents`	SubAgent[]	yes	—	Composition children, run in declaration order.
`output`	TemplateString	no	—	Return-value template. Defaults to the last child's output.

Parallel

Parallel fans sub-agents out concurrently against the same input. Outputs are collected as map[name]string and exposed to output: as .<name>.

Field	Type	Required	Default	Description
`instruction`	string	no	—	System prompt for this agent. Required on sub-agents (enforced by SubAgent.Validate); the root pipeline reads its instruction from project.instruction instead.
`inherits`	InheritField[]	no	—	Fields to pull from the nearest ancestor that declares them.
`model`	ModelRef	no	—	Reference into the model catalog.
`tools`	string[]	no	—	Tool names this agent's `output:` template may reference. (must reference a declared key in: tools.mcp, tools.a2a)
`skills`	Skills	no	—	Built-in skills bound to this agent.
`memory`	Memory	no	—	Memory overrides (kind-aware defaults apply when unset).
`subagents`	SubAgent[]	yes	—	Composition children, run concurrently.
`output`	TemplateString	no	—	Return-value template. Defaults to a `name→output` map.

Loop

Loop runs sub-agents repeatedly until an exit signal fires (exit_loop, until:, or maxIterations).

Field	Type	Required	Default	Description
`instruction`	string	no	—	System prompt for this agent. Required on sub-agents (enforced by SubAgent.Validate); the root pipeline reads its instruction from project.instruction instead.
`inherits`	InheritField[]	no	—	Fields to pull from the nearest ancestor that declares them.
`model`	ModelRef	no	—	Reference into the model catalog.
`tools`	string[]	no	—	Tool names this agent's `output:` template may reference. (must reference a declared key in: tools.mcp, tools.a2a)
`skills`	Skills	no	—	Built-in skills bound to this agent.
`memory`	Memory	no	—	Memory overrides (kind-aware defaults apply when unset).
`subagents`	SubAgent[]	yes	—	Loop body: composition children run on each pass.
`maxIterations`	integer	yes	—	Iteration cap (runaway guardrail). (min: 1)
`until`	TemplateString	no	—	Loop exit predicate. A Go template evaluated after each pass; when it renders to truthy the loop exits. The `agent` helper is forbidden here; use a reviewer sub-agent with `exit_loop` for LLM-judgment exits.
`output`	TemplateString	no	—	Return-value template. Defaults to the last pass's output.

Orchestrator

Orchestrator is an explicit step graph wired with Go templates. Steps reference prior step outputs and call tools, sub-agents, or skills via helpers.

Field	Type	Required	Default	Description
`instruction`	string	no	—	System prompt for this agent. Required on sub-agents (enforced by SubAgent.Validate); the root pipeline reads its instruction from project.instruction instead.
`inherits`	InheritField[]	no	—	Fields to pull from the nearest ancestor that declares them.
`model`	ModelRef	no	—	Reference into the model catalog. Backs the `{{ prompt }}` helper inside `steps[].run` and `output:`.
`tools`	string[]	no	—	Tool names this orchestrator may call from `steps[].run` and `output:`. (must reference a declared key in: tools.mcp, tools.a2a)
`skills`	Skills	no	—	Built-in skills bound to this agent.
`memory`	Memory	no	—	Memory overrides (kind-aware defaults apply when unset).
`subagents`	SubAgent[]	no	—	Callable building blocks for `steps:` (referenced via `{{ agent "name" }}`).
`steps`	OrchestratorStep[]	yes	—	Step graph. Steps run in declaration order; each step's record is exposed to subsequent steps and `output:` as `.<name>`.
`output`	TemplateString	yes	—	Return-value template. Same template engine as `steps[].run`.

ModelEntry

ModelEntry holds the connection and runtime parameters for one model alias. Provider-specific fields are passed through to the provider SDK at call time.

Field	Type	Required	Default	Description
`model`	string	yes	—	Provider's model identifier.
`baseUrl`	string	no	—	Override the provider endpoint. Required for OpenAI-compatible servers (LM Studio, vLLM); optional for the native provider.
`apiKeyEnv`	string	no	—	Name of the environment variable holding the API key for this model. Defaults to the provider's conventional variable when unset (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, AWS_ACCESS_KEY_ID, GOOGLE_APPLICATION_CREDENTIALS). Ignored by the borrowed provider (the connecting MCP client owns auth).
`temperature`	number	no	—	Sampling temperature passed through to the provider.
`maxTokens`	integer	no	—	Maximum response tokens. Provider-defined when unset. (min: 1)

ModelRef

ModelRef points at a model entry in the catalog. Both fields together identify exactly one entry: models.<provider>.<name>.

Field	Type	Required	Default	Exclusivity	Description
`provider`	Provider	yes	—		Provider key under `models:` (e.g. openai, anthropic).
`name`	string	yes	—		Alias under that provider (e.g. "default"). (must reference a declared key in: project.models.openai, project.models.anthropic, project.models.google, project.models.bedrock, project.models.vertex, project.models.borrowed)

Skills

Skills binds built-in skills to an agent.

Field	Type	Required	Default	Description
`guards`	Guard[]	no	—	Guard names from the built-in registry. Guards run alongside the agent's LLM loop and can force retries or short-circuit on rule violations.
`shell`	map[string]ShellSkill	no	—	Shell command execution skills, keyed by skill name. Each entry declares a command, working directory, and typed args; invocable by the agent as a tool (autonomous) or via `{{ skill "name" ... }}` in templates (sequential/parallel/loop/orchestrator). (must not be a reserved engine name)
`file`	FileSkill	no	—	File read/write skills (read/list/glob/write within workingDir).
`web`	WebSkill	no	—	Single-page web scrape skill (URL allowlisted).

Memory

Memory controls what conversation context an agent sees and keeps. Defaults are kind- and position-aware (root autonomous retains; composition children do not), so most agents leave this unset.

Field	Type	Required	Default	Exclusivity	Description
`retain`	boolean	no	—		When true, this agent remembers its own turns across calls (durable conversation). Defaults: root autonomous true; loop body children true; everything else false.
`inherit`	boolean	no	—		When true, this agent receives the parent's transcript as inbound context in addition to its hand-off input. Defaults to false everywhere; opt in only when a child needs the parent's earlier turns (e.g. a panel specialist).

SubAgent

SubAgent is a child agent. Identified by its name: field. Exactly one kind block must be set. Identity fields (instruction, nherits) live inside the kind block alongside everything else, so a sub-agent body is just <kind>: { ... } with no wrapper noise.

Field	Type	Required	Default	Exclusivity	Description
`name`	string	yes	—		Agent name. Used by templates (`{{ agent "name" }}`), by composition kinds, and as the ADK agent name. (must not be a reserved engine name)
`autonomous`	Autonomous	oneof	—	mutually exclusive with `sequential`, `parallel`, `loop`, `orchestrator`	Single LLM agent that decides its own tool calls.
`sequential`	Sequential	oneof	—	mutually exclusive with `autonomous`, `parallel`, `loop`, `orchestrator`	Sub-agents run in declaration order, sharing transcript history.
`parallel`	Parallel	oneof	—	mutually exclusive with `autonomous`, `sequential`, `loop`, `orchestrator`	Sub-agents fan out concurrently against the same input.
`loop`	Loop	oneof	—	mutually exclusive with `autonomous`, `sequential`, `parallel`, `orchestrator`	Sub-agents run repeatedly until an exit signal fires.
`orchestrator`	Orchestrator	oneof	—	mutually exclusive with `autonomous`, `sequential`, `parallel`, `loop`	Explicit step graph wired with Go templates.

OrchestratorStep

OrchestratorStep is one entry in an orchestrator's step graph. Each step's record is exposed to subsequent steps and the orchestrator's output: as .<name>.{input, output}. Steps run in the order declared in the steps: sequence.

Field	Type	Required	Default	Exclusivity	Description
`name`	string	yes	—		Step name. Used as the `.<name>` path in templates. (must not be a reserved engine name)
`run`	TemplateString	yes	—		Step body. A Go text/template that calls one or more helpers. A run that renders to whitespace-only is treated as skipped: `.<stepName>.input` and `.<stepName>.output` are absent from the template scope so downstream `{{ coalesce ... }}` / `{{if ... }}` checks fall through naturally.

ShellSkill

ShellSkill is one user-declared shell command exposed to an agent. The map key under skills.shell: becomes the entry name; the command runs in WorkingDir with an empty environment. Args are typed inputs rendered into Command via Go text/template.

Field	Type	Required	Default	Description
`command`	string[]	yes	—	Program and arguments. Element 0 must be a program name (not a shell interpreter). Templates may appear inside elements but must occupy the entire element — splicing template output into a literal substring (e.g. `"-l {{ .path }}"`) is rejected.
`workingDir`	string	yes	—	Working directory for command execution. Project-rooted; no `..` escape allowed at runtime.
`args`	Param[]	no	—	Typed input parameters provided by the caller (LLM as tool, or template helper as positional args).

FileSkill

FileSkill enables sandboxed file ops for an agent rooted at WorkingDir. Each operation is gated by an explicit Enabled flag; omitted blocks are denied. Empty Paths with Enabled=true means "any path under WorkingDir" for read; for write it means "any path under WorkingDir" (use a Paths allowlist to narrow further).

Field	Type	Required	Default	Description
`workingDir`	string	yes	—	WorkingDir is the filesystem root for all file ops. Absolute or relative to project root.
`read`	FileOp	no	—	Read configuration. Omitted means reads denied.
`write`	FileOp	no	—	Write configuration. Omitted means writes denied.

WebSkill

WebSkill enables sandboxed HTTP scraping for an agent. Exposes a single web_scrape tool that GETs an allowlisted URL and returns its content as Markdown (HTML pages are converted; plain text and markdown pass through). For richer HTTP (POST, auth, custom headers) run mcpsmithy as an MCP server and reference it via the project tools.mcp catalog instead — credentials stay out of the agent's reach.

Field	Type	Required	Default	Exclusivity	Description
`enabled`	boolean	no	—		Enabled toggles the skill. False (or omitted) denies it.
`urls`	string[]	no	—		URLs lists the full URLs (scheme+host) to allow, e.g. "https://example.com". Required when Enabled=true.

Param

Param declares one input the caller (LLM as tool, or template helper as positional argument) provides when invoking a skill.

Field	Type	Required	Default	Description
`name`	string	yes	—	Name is used as the tool input name and the template variable inside ShellSkill.Command elements. (must not be a reserved engine name)
`type`	ParamType	yes	—	Type drives input validation and template zero-value rendering.
`required`	boolean	no	false	Required marks the parameter mandatory.
`description`	string	no	—	Description is shown to the LLM. Use it to explain the expected format.
`default`	any	no	—	Default value when not supplied. The YAML type must match Type.
`constraints`	ParamConstraints	no	—	Constraints on the parameter value (enum or numeric range).

FileOp

FileOp gates one file operation (read or write).

Field	Type	Required	Default	Exclusivity	Description
`enabled`	boolean	no	—		Enabled is true when this operation is allowed. False (or omitted) denies it.
`paths`	string[]	no	—		Paths is a glob allowlist within FileSkill.WorkingDir. Empty with Enabled=true means the full WorkingDir subtree.

ParamConstraints

ParamConstraints limits what a caller can supply for a parameter.

Field	Type	Required	Default	Exclusivity	Description
`enum`	any[]	no	—	mutually exclusive with `min`; mutually exclusive with `max`	Enum lists the fixed set of valid values. Compatible with string, number, bool.
`min`	number	no	—	mutually exclusive with `enum`	Min is the inclusive minimum. Applies to number only.
`max`	number	no	—	mutually exclusive with `enum`	Max is the inclusive maximum. Applies to number only.

Enum Reference

InheritField

InheritField names a field a sub-agent can pull from an ancestor instead of declaring locally.

Value	Description
`model`	Pull the nearest ancestor's `model:`.
`tools`	Pull the nearest ancestor's `tools:`.
`skills`	Pull the nearest ancestor's `skills:`.

Provider

Provider names a supported model provider.

Value	Description
`openai`	OpenAI native and OpenAI-compatible endpoints (Ollama, LM Studio, vLLM, Together, Groq, OpenRouter, DeepSeek, xAI). Override baseUrl on the entry to target a compatible server.
`anthropic`	Anthropic Claude (native Messages API).
`google`	Google Gemini (developer API key).
`bedrock`	AWS Bedrock-hosted models.
`vertex`	Google Vertex AI-hosted models.
`borrowed`	Borrowed: delegate completion to the connecting MCP client via sampling/createMessage. Requires an MCP transport.

Guard

Guard names a built-in guard skill. Guards run alongside the agent's LLM loop and can force retries or short-circuit on rule violations.

Value	Description
`requireToolCall`	Forces the LLM to issue at least one tool call per turn. Pairs with `maxIterations:` to cap retries.

ParamType

ParamType names the valid parameter types for skill args.

Value	Description
`string`	ParamTypeString accepts JSON Schema string values.
`number`	ParamTypeNumber accepts JSON Schema number values (float64 at runtime).
`bool`	ParamTypeBool accepts JSON Schema boolean values.
`array`	ParamTypeArray accepts JSON Schema array values.
`project_file_path`	ParamTypeProjectFilePath is a string validated as a project-sandbox path at invocation time.

BuiltinFunc

BuiltinFunc names a template helper available inside agent templates (run:, output:, until:). Helper availability varies by position (until: forbids agent), but every helper listed here is a known name; references to anything else fail at parse time.

Value	Description
`agent`	`agent <name> <input>`: invoke a sub-agent. Forbidden in `until:`.
`coalesce`	`coalesce <args...>`: first non-empty argument.
`contains`	`contains <s> <substr>`: reports whether substr is within s.
`dict`	`dict <key value...>`: build a map literal.
`exit_error`	`exit_error <reason>`: abort the pipeline with an error signal. Propagates to the caller as a non-zero exit / error response.
`fromJSON`	`fromJSON <s>`: parse JSON into a Go value (map / slice / scalar).
`join`	`join <sep> <parts>`: join a slice (string or any) with sep.
`list`	`list <args...>`: build a slice literal.
`lower`	`lower <s>`: lower-case the string.
`prompt`	`prompt <template> <args...>`: run a one-shot LLM call against the surrounding agent's model.
`replace`	`replace <old> <new> <s>`: replace all occurrences of old with new in s.
`skill`	`skill <name> <args...>`: invoke a built-in skill.
`split`	`split <sep> <s>`: split s on sep, returning a slice.
`tool`	`tool <name> <args...>`: invoke a tool from the catalog.
`trim`	`trim <s>`: strip leading and trailing whitespace.
`upper`	`upper <s>`: upper-case the string.

Type Reference

TemplateString

TemplateString is a Go text/template body used by run:, output:, and until: fields. Inside the template, the agent's inputs and prior step records are exposed as dotted paths (.input, .<stepName>.output, .<childName>.output); the available helpers are listed under [BuiltinFunc]. Templates are parsed at config validate time, so syntax errors and references to unknown helpers are caught before the agent runs.

Config​

Project​

Tools​

Pipeline​

Models​

Autonomous​

Sequential​

Parallel​

Loop​

Orchestrator​

ModelEntry​

ModelRef​

Skills​

Memory​

SubAgent​

OrchestratorStep​

ShellSkill​

FileSkill​

WebSkill​

Param​

FileOp​

ParamConstraints​

InheritField​

Provider​

Guard​

ParamType​

BuiltinFunc​

TemplateString​