latest

package
v1.73.0 Latest Latest
Warning

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

 Go to latest Published: Jun 3, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation ¶

Index ¶

Constants ¶

View Source 
const (
	LifecycleProfileResilient  = "resilient"
	LifecycleProfileStrict     = "strict"
	LifecycleProfileBestEffort = "best-effort"
)

Lifecycle profile names.

View Source 
const (
	AuthTypeWorkloadIdentityFederation = "workload_identity_federation"
)

AuthType values accepted by [AuthConfig.Type].

View Source 
const SkillSourceLocal = "local"
View Source 
const Version = "10"

Variables ¶

This section is empty.

Functions ¶

func EffectiveProviderType ¶ added in v1.55.0 

func EffectiveProviderType(m ModelConfig, providers map[string]ProviderConfig) string

EffectiveProviderType returns the underlying provider type for a model, resolving custom-provider indirection (a model whose `provider:` points to an entry in `providers:` inherits that entry's `provider:` field).

func Register ¶ 

func Register(parsers map[string]func([]byte) (any, error), upgraders *[]func(any, []byte) (any, error))

Types ¶

type APIToolConfig ¶ 

type APIToolConfig struct {
	Instruction string            `json:"instruction,omitempty"`
	Name        string            `json:"name,omitempty"`
	Required    []string          `json:"required,omitempty"`
	Args        map[string]any    `json:"args,omitempty"`
	Endpoint    string            `json:"endpoint,omitempty"`
	Method      string            `json:"method,omitempty"`
	Headers     map[string]string `json:"headers,omitempty"`
	// OutputSchema optionally describes the API response as JSON Schema for MCP/Code Mode consumers; runtime still returns the raw string body.
	OutputSchema map[string]any `json:"output_schema,omitempty"`
}

type AgentConfig ¶ 

type AgentConfig struct {
	Name           string
	Model          string          `json:"model,omitempty"`
	Fallback       *FallbackConfig `json:"fallback,omitempty"`
	Description    string          `json:"description,omitempty"`
	WelcomeMessage string          `json:"welcome_message,omitempty"`
	Toolsets       []Toolset       `json:"toolsets,omitempty"`
	Instruction    string          `json:"instruction,omitempty"`
	Harness        *HarnessConfig  `json:"harness,omitempty"`
	SubAgents      []string        `json:"sub_agents,omitempty"`
	Handoffs       []string        `json:"handoffs,omitempty"`

	AddDate            bool `json:"add_date,omitempty"`
	AddEnvironmentInfo bool `json:"add_environment_info,omitempty"`
	// RedactSecrets enables every leg of the redact_secrets feature:
	// the pre_tool_use builtin (scrubs tool arguments), the
	// before_llm_call hook (scrubs outgoing chat content), and the
	// tool_response_transform hook (scrubs tool output before it
	// reaches event consumers, the persisted session, the post_tool_use
	// hook, or the next LLM call). Equivalent to writing all three
	// hook entries by hand — the runtime auto-injects them when this
	// flag is true. See pkg/hooks/builtins/redact_secrets.go for the
	// hook-side implementation.
	//
	// Pointer (tri-state) so we can distinguish "unset" (nil → default
	// on) from "explicitly disabled" (false). Use
	// [AgentConfig.RedactSecretsEnabled] to read the effective value.
	RedactSecrets           *bool             `json:"redact_secrets,omitempty"`
	CodeModeTools           bool              `json:"code_mode_tools,omitempty"`
	AddDescriptionParameter bool              `json:"add_description_parameter,omitempty"`
	MaxIterations           int               `json:"max_iterations,omitempty"`
	MaxConsecutiveToolCalls int               `json:"max_consecutive_tool_calls,omitempty"`
	MaxOldToolCallTokens    int               `json:"max_old_tool_call_tokens,omitempty"`
	NumHistoryItems         int               `json:"num_history_items,omitempty"`
	AddPromptFiles          []string          `json:"add_prompt_files,omitempty" yaml:"add_prompt_files,omitempty"`
	Commands                types.Commands    `json:"commands,omitempty"`
	StructuredOutput        *StructuredOutput `json:"structured_output,omitempty"`
	Skills                  SkillsConfig      `json:"skills,omitzero"`
	// UseCommands and UseSkills reference reusable groups defined in the
	// top-level Config.Commands / Config.Skills sections. The referenced
	// groups are merged into Commands / Skills during config resolution;
	// inline entries on the agent take precedence on name conflicts.
	UseCommands []string     `json:"use_commands,omitempty"`
	UseSkills   []string     `json:"use_skills,omitempty"`
	Hooks       *HooksConfig `json:"hooks,omitempty"`
	Cache       *CacheConfig `json:"cache,omitempty"`
}

AgentConfig represents a single agent configuration

func (*AgentConfig) GetFallbackCooldown ¶ 

func (a *AgentConfig) GetFallbackCooldown() time.Duration

GetFallbackCooldown returns the fallback cooldown duration from the config. Returns the configured cooldown, or 0 if not set (caller should apply default).

func (*AgentConfig) GetFallbackModels ¶ 

func (a *AgentConfig) GetFallbackModels() []string

GetFallbackModels returns the fallback models from the config.

func (*AgentConfig) GetFallbackRetries ¶ 

func (a *AgentConfig) GetFallbackRetries() int

GetFallbackRetries returns the fallback retries from the config.

func (*AgentConfig) RedactSecretsEnabled ¶ added in v1.66.0 

func (a *AgentConfig) RedactSecretsEnabled() bool

RedactSecretsEnabled reports the effective value of the agent's redact_secrets flag. The feature is on by default: a nil pointer (the field omitted from YAML) means enabled, an explicit `redact_secrets: false` is the only way to disable it.

type Agents ¶ 

type Agents []AgentConfig

func (*Agents) First ¶ 

func (c *Agents) First() AgentConfig

func (*Agents) Lookup ¶ 

func (c *Agents) Lookup(name string) (AgentConfig, bool)

func (Agents) MarshalYAML ¶ 

func (c Agents) MarshalYAML() (any, error)

func (*Agents) UnmarshalYAML ¶ 

func (c *Agents) UnmarshalYAML(unmarshal func(any) error) error

func (*Agents) Update ¶ 

func (c *Agents) Update(name string, update func(a *AgentConfig)) bool

type AuthConfig ¶ added in v1.55.0 

type AuthConfig struct {
	// Type discriminates which authentication scheme to use.
	// Currently supported: "workload_identity_federation".
	Type string `json:"type" yaml:"type"`
	// Federation holds the parameters for the workload_identity_federation
	// scheme. Required when Type == "workload_identity_federation".
	Federation *FederationAuthConfig `json:"workload_identity_federation,omitempty" yaml:"workload_identity_federation,omitempty"`
}

AuthConfig configures a non-API-key authentication method for a model provider. The Type field is a discriminator: today only "workload_identity_federation" is supported (Anthropic), but the shape leaves room for future schemes.

AuthConfig may be set on a ProviderConfig (shared by every model that references the provider) or directly on a ModelConfig (model-level value always wins). It is mutually exclusive with the legacy `token_key` / `ANTHROPIC_API_KEY` env-var path.

func EffectiveAuth ¶ added in v1.55.0 

func EffectiveAuth(m ModelConfig, providers map[string]ProviderConfig) *AuthConfig

EffectiveAuth returns the auth that applies to a model: the model's own Auth wins, otherwise the referenced ProviderConfig's Auth.

func (*AuthConfig) EnvVars ¶ added in v1.55.0 

func (a *AuthConfig) EnvVars() []string

EnvVars returns the environment variables that the auth configuration references at runtime. Today this is only meaningful for Workload Identity Federation, whose identity-token source may either name an env var directly (env source) or reference one through ${VAR} expansion in URL or header values.

func (*AuthConfig) Validate ¶ added in v1.56.0 

func (a *AuthConfig) Validate(providerType string) error

Validate validates an AuthConfig. providerType, when non-empty, is used to enforce that the chosen scheme is supported by the underlying provider (today: WIF requires "anthropic"). Empty providerType skips that check, which is what we want when an AuthConfig sits on a ProviderConfig that doesn't declare an underlying provider — the per-model check picks it up later.

type BackoffConfig ¶ added in v1.54.0 

type BackoffConfig struct {
	Initial    Duration `json:"initial,omitzero" yaml:"initial,omitempty"`
	Max        Duration `json:"max,omitzero" yaml:"max,omitempty"`
	Multiplier float64  `json:"multiplier,omitempty" yaml:"multiplier,omitempty"`
	// Jitter is a 0..1 fraction of the computed delay applied as a
	// uniform random offset. 0 disables jitter (the default).
	Jitter float64 `json:"jitter,omitempty" yaml:"jitter,omitempty"`
}

BackoffConfig controls the exponential backoff used between restart attempts. Zero fields fall back to profile defaults (Initial=1s, Max=32s, Multiplier=2.0, Jitter=0).

type CacheConfig ¶ added in v1.53.0 

type CacheConfig struct {
	Enabled       bool   `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	CaseSensitive bool   `json:"case_sensitive,omitempty" yaml:"case_sensitive,omitempty"`
	TrimSpaces    bool   `json:"trim_spaces,omitempty" yaml:"trim_spaces,omitempty"`
	Path          string `json:"path,omitempty" yaml:"path,omitempty"`
}

CacheConfig configures the agent's response cache. When set and Enabled is true, the agent stores the assistant response produced for a given user question and replays it when the same question is asked again, skipping the model entirely.

Two normalization options control what "same question" means:

  • CaseSensitive: when false (the default), question matching is case-insensitive ("Hello" == "hello").
  • TrimSpaces: when true, leading and trailing whitespace is stripped before comparison (" hello " == "hello").

Storage is in-memory by default. Set Path to persist entries to a JSON file that is reloaded on startup.

type Config ¶ 

type Config struct {
	Version   string                    `json:"version,omitempty"`
	Agents    Agents                    `json:"agents,omitempty"`
	Providers map[string]ProviderConfig `json:"providers,omitempty"`
	Models    map[string]ModelConfig    `json:"models,omitempty"`
	MCPs      map[string]MCPToolset     `json:"mcps,omitempty"`
	RAG       map[string]RAGToolset     `json:"rag,omitempty"`
	// Commands and Skills are reusable, named groups shared across agents.
	// An agent opts into a group by listing its name in AgentConfig.UseCommands
	// or AgentConfig.UseSkills; the group is merged into the agent during config
	// resolution (see resolveCommandDefinitions / resolveSkillDefinitions). This
	// mirrors the top-level MCPs/RAG reference-by-name convention.
	Commands    map[string]types.Commands `json:"commands,omitempty"`
	Skills      map[string]SkillsConfig   `json:"skills,omitempty"`
	Metadata    Metadata                  `json:"metadata"`
	Permissions *PermissionsConfig        `json:"permissions,omitempty"`
	Runtime     *RuntimeDefaults          `json:"runtime,omitempty"`
}

Config represents the entire configuration file

func (*Config) UnmarshalYAML ¶ 

func (t *Config) UnmarshalYAML(unmarshal func(any) error) error

func (*Config) Validate ¶ added in v1.56.0 

func (t *Config) Validate() error

type DeferConfig ¶ 

type DeferConfig struct {
	// DeferAll is true when all tools should be deferred
	DeferAll bool `json:"-"`
	// Tools is the list of specific tool names to defer (empty if DeferAll is true)
	Tools []string `json:"-"`
}

DeferConfig represents the deferred loading configuration for a toolset. It can be either a boolean (true to defer all tools) or a slice of strings (list of tool names to defer).

func (DeferConfig) IsEmpty ¶ 

func (d DeferConfig) IsEmpty() bool

func (DeferConfig) MarshalYAML ¶ 

func (d DeferConfig) MarshalYAML() (any, error)

func (*DeferConfig) UnmarshalYAML ¶ 

func (d *DeferConfig) UnmarshalYAML(unmarshal func(any) error) error

type Duration ¶ 

type Duration struct {
	time.Duration
}

Duration is a wrapper around time.Duration that supports YAML/JSON unmarshaling from string format (e.g., "1m", "30s", "2h30m").

func (Duration) MarshalJSON ¶ 

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON implements custom marshaling for Duration to string format

func (Duration) MarshalYAML ¶ 

func (d Duration) MarshalYAML() (any, error)

MarshalYAML implements custom marshaling for Duration to string format

func (*Duration) UnmarshalJSON ¶ 

func (d *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling for Duration from string format

func (*Duration) UnmarshalYAML ¶ 

func (d *Duration) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling for Duration from string format

type FallbackConfig ¶ 

type FallbackConfig struct {
	// Models is a list of fallback models to try in order if the primary fails.
	// Each entry can be a model name from the models section or an inline provider/model format.
	Models []string `json:"models,omitempty"`
	// Retries is the number of retries per model with exponential backoff.
	// Default is 2 (giving 3 total attempts per model). Use -1 to disable retries entirely.
	// Retries only apply to retryable errors (5xx, timeouts); non-retryable errors (429, 4xx)
	// skip immediately to the next model.
	Retries int `json:"retries,omitempty"`
	// Cooldown is the duration to stick with a successful fallback model before
	// retrying the primary. Only applies after a non-retryable error (e.g., 429).
	// Default is 1 minute. Use Go duration format (e.g., "1m", "30s", "2m30s").
	Cooldown Duration `json:"cooldown"`
}

FallbackConfig represents fallback model configuration for an agent. Controls which models to try when the primary fails and how retries/cooldowns work. Most users only need to specify Models — the defaults handle common scenarios automatically.

type FederationAuthConfig ¶ added in v1.55.0 

type FederationAuthConfig struct {
	// FederationRuleID identifies the Anthropic OidcFederationRule that
	// governs token exchange. Required; must start with "fdrl_".
	FederationRuleID string `json:"federation_rule_id" yaml:"federation_rule_id"`
	// OrganizationID is the UUID of the Anthropic organization that owns
	// the federation rule. Required.
	OrganizationID string `json:"organization_id" yaml:"organization_id"`
	// ServiceAccountID is the optional expected-target check for federation
	// rules with target_type=SERVICE_ACCOUNT. Must start with "svac_". Omit
	// for target_type=USER rules where the principal is derived from the
	// JWT.
	ServiceAccountID string `json:"service_account_id,omitempty" yaml:"service_account_id,omitempty"`
	// IdentityToken describes how to obtain a fresh JWT for each exchange.
	// Required.
	IdentityToken *IdentityTokenSourceConfig `json:"identity_token" yaml:"identity_token"`
}

FederationAuthConfig describes an Anthropic OIDC Federation Rule and the source of the JWT identity token to be exchanged for a short-lived access token.

See https://platform.claude.com/docs/en/build-with-claude/workload-identity-federation for the underlying concepts (federation rules, organization IDs, service accounts, target_type=USER vs SERVICE_ACCOUNT).

type FlexibleModelConfig ¶ 

type FlexibleModelConfig struct {
	ModelConfig
}

FlexibleModelConfig wraps ModelConfig to support both shorthand and full syntax. It can be unmarshaled from either:

  • A shorthand string: "provider/model" (e.g., "anthropic/claude-sonnet-4-5")
  • A full model definition with all options

func (FlexibleModelConfig) MarshalYAML ¶ 

func (f FlexibleModelConfig) MarshalYAML() (any, error)

MarshalYAML outputs shorthand format if only provider/model are set

func (*FlexibleModelConfig) UnmarshalYAML ¶ 

func (f *FlexibleModelConfig) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling for flexible model config

type HarnessConfig ¶ added in v1.62.0 

type HarnessConfig struct {
	// Type identifies the external harness provider: claude-code, codex, pi, or opencode.
	Type string `json:"type,omitempty"`
	// Model is passed to harnesses that accept a model flag. When omitted,
	// docker-agent lets the external CLI use its own default model.
	Model string `json:"model,omitempty"`
	// Effort is forwarded to Claude Code's --effort flag.
	Effort string `json:"effort,omitempty"`
	// Agent is forwarded to opencode's --agent flag.
	Agent string `json:"agent,omitempty"`
	// Thinking enables opencode's --thinking flag.
	Thinking bool `json:"thinking,omitempty"`
}

HarnessConfig configures an agent that delegates execution to an external coding-agent CLI through github.com/rumpl/harness instead of using a docker-agent model provider.

type HookDefinition ¶ 

type HookDefinition struct {
	// Name gives the hook a friendly label for logs and runtime events.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Type specifies the hook type. Supported values:
	//   - "command":  run a shell command (default)
	//   - "builtin":  invoke a named, in-process Go function (the name
	//                 lives in Command). The set of registered builtins
	//                 is owned by the runtime; the docker-agent runtime
	//                 ships add_date, add_environment_info,
	//                 add_prompt_files, redact_secrets (see also the
	//                 redact_secrets agent flag), and several others
	//                 documented in pkg/hooks/builtins.
	//   - "model":    ask an LLM and translate its reply into the hook's
	//                 native output. See Model / Prompt / Schema. Used to
	//                 implement "LLM as a judge" pre_tool_use hooks,
	//                 turn-start summarizers, etc., with no Go code.
	Type string `json:"type" yaml:"type"`

	// Command is the shell command (Type==command) or the builtin name
	// (Type==builtin) to invoke.
	Command string `json:"command,omitempty" yaml:"command,omitempty"`

	// Args are arbitrary string arguments passed to the hook handler.
	// Builtin handlers receive them as the args parameter; future handler
	// kinds (http, mcp, ...) can adopt the same field. Empty for command
	// hooks today (the shell command stays self-contained).
	Args []string `json:"args,omitempty" yaml:"args,omitempty"`

	// Timeout is the execution timeout in seconds (default: 60)
	Timeout int `json:"timeout,omitempty" yaml:"timeout,omitempty"`

	// Env adds or overrides environment variables for this hook only.
	Env map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	// WorkingDir overrides the runtime working directory for this hook.
	WorkingDir string `json:"working_dir,omitempty" yaml:"working_dir,omitempty"`

	// OnError controls non-fail-closed hook failures: warn (default), ignore, or block.
	OnError string `json:"on_error,omitempty" yaml:"on_error,omitempty"`

	// Model is the model spec ("provider/model", e.g. "openai/gpt-4o-mini")
	// invoked by Type==model hooks. Required for that type, ignored
	// otherwise.
	Model string `json:"model,omitempty" yaml:"model,omitempty"`

	// Prompt is the user-message template rendered for each invocation
	// of a Type==model hook. It is parsed as a Go text/template with the
	// hook [Input] as the data context (so {{ .ToolName }},
	// {{ .ToolInput }}, etc. work). Required for Type==model.
	Prompt string `json:"prompt,omitempty" yaml:"prompt,omitempty"`

	// Schema selects a well-known response interpretation for Type==model
	// hooks. The empty value means "return the model's reply as
	// additional_context". Other values (registered by the runtime) ask
	// the provider for strict-JSON output and translate the result into
	// the right Output shape (e.g. "pre_tool_use_decision" produces a
	// permission_decision verdict).
	Schema string `json:"schema,omitempty" yaml:"schema,omitempty"`
}

HookDefinition represents a single hook configuration

func (*HookDefinition) DisplayName ¶ added in v1.53.0 

func (h *HookDefinition) DisplayName() string

DisplayName returns a human-friendly identifier for the hook: the configured Name when set, otherwise the Command, otherwise the Type.

func (*HookDefinition) GetTimeout ¶ added in v1.53.0 

func (h *HookDefinition) GetTimeout() time.Duration

GetTimeout returns the per-hook execution timeout, defaulting to 60 seconds when [HookDefinition.Timeout] is zero or negative.

type HookMatcherConfig ¶ 

type HookMatcherConfig struct {
	// Matcher is a regex pattern to match tool names (e.g., "shell|edit_file")
	// Use "*" to match all tools. Case-sensitive.
	Matcher string `json:"matcher,omitempty" yaml:"matcher,omitempty"`

	// Hooks are the hooks to execute when the matcher matches
	Hooks []HookDefinition `json:"hooks" yaml:"hooks"`
}

HookMatcherConfig represents a hook matcher with its hooks. Used for tool-related hooks (PreToolUse, PostToolUse).

type HooksConfig ¶ 

type HooksConfig struct {
	// PreToolUse hooks run before tool execution
	PreToolUse []HookMatcherConfig `json:"pre_tool_use,omitempty" yaml:"pre_tool_use,omitempty"`

	// PostToolUse hooks run after a tool completes — both success and
	// failure: a failed tool call still fires this event, with the
	// failure surfaced in tool_response (notably the is_error flag and
	// any error text). Use post_tool_use to react to either outcome
	// (logging, audits, circuit-breakers); branch on tool_response.is_error
	// in the handler when you only want to act on one of them.
	PostToolUse []HookMatcherConfig `json:"post_tool_use,omitempty" yaml:"post_tool_use,omitempty"`

	// PermissionRequest hooks run just before the runtime would prompt
	// the user to approve a tool call (i.e. when neither --yolo nor a
	// permissions rule short-circuited the decision). Hooks may auto-allow
	// or auto-deny via hook_specific_output.permission_decision so the
	// user is not prompted; otherwise the runtime falls through to the
	// usual interactive confirmation. Tool-matched, like pre_tool_use.
	PermissionRequest []HookMatcherConfig `json:"permission_request,omitempty" yaml:"permission_request,omitempty"`

	// SessionStart hooks run when a session begins
	SessionStart []HookDefinition `json:"session_start,omitempty" yaml:"session_start,omitempty"`

	// UserPromptSubmit hooks run once per user message, after the user
	// has submitted their prompt and before the first model call of the
	// turn. The submitted text is passed in the prompt field. Hooks can
	// block submission (decision="block" / continue=false / exit code 2)
	// or contribute additional_context that is spliced into the
	// conversation as a transient system message for that turn only.
	// Sub-sessions (transferred tasks, background agents) do not fire
	// this event because their kick-off message is synthesised by the
	// runtime, not authored by the user.
	UserPromptSubmit []HookDefinition `json:"user_prompt_submit,omitempty" yaml:"user_prompt_submit,omitempty"`

	// TurnStart hooks run at the start of every agent turn (each model
	// call). Their AdditionalContext is appended as transient system
	// messages for that turn only — it is NOT persisted to the session,
	// so per-turn signals (date, prompt files, ...) are recomputed every
	// turn instead of bloating the message history on every resume.
	TurnStart []HookDefinition `json:"turn_start,omitempty" yaml:"turn_start,omitempty"`

	// TurnEnd hooks run once per agent turn when the turn finishes —
	// the symmetric counterpart of TurnStart. Fires no matter why the
	// turn ended: a normal stop, an error, a hook-driven shutdown, the
	// loop detector, or context cancellation. The reason is reported
	// in the hook input's reason field ("normal", "continue",
	// "steered", "error", "canceled", "hook_blocked",
	// "loop_detected"). Observational; output is ignored.
	TurnEnd []HookDefinition `json:"turn_end,omitempty" yaml:"turn_end,omitempty"`

	// BeforeLLMCall hooks run just before each model call (after
	// turn_start). Use this for observability, cost guardrails, or
	// auditing without contributing system messages — turn_start is the
	// right event for the latter.
	BeforeLLMCall []HookDefinition `json:"before_llm_call,omitempty" yaml:"before_llm_call,omitempty"`

	// AfterLLMCall hooks run just after each successful model call,
	// before the response is recorded into the session and tool calls
	// are dispatched. Receives the assistant text content in
	// stop_response.
	AfterLLMCall []HookDefinition `json:"after_llm_call,omitempty" yaml:"after_llm_call,omitempty"`

	// SessionEnd hooks run when a session ends
	SessionEnd []HookDefinition `json:"session_end,omitempty" yaml:"session_end,omitempty"`

	// PreCompact hooks run just before the runtime compacts the session
	// transcript into a summary. The trigger is reported in the source
	// field: "manual" (user-initiated /compact), "auto" (proactive
	// threshold), "overflow" (context-overflow recovery), or
	// "tool_overflow" (proactive after tool results pushed past the
	// threshold). Hooks may block compaction (decision="block" /
	// continue=false / exit code 2) or contribute additional_context
	// that is appended to the compaction prompt — useful for steering
	// the summary without modifying the agent's instruction.
	PreCompact []HookDefinition `json:"pre_compact,omitempty" yaml:"pre_compact,omitempty"`

	// SubagentStop hooks run when a sub-agent (transferred task,
	// background agent, skill sub-session) finishes. The sub-agent's
	// name is passed in agent_name and its final assistant message in
	// stop_response. Useful for handoff auditing and per-sub-agent
	// metrics, separately from the parent's stop event.
	SubagentStop []HookDefinition `json:"subagent_stop,omitempty" yaml:"subagent_stop,omitempty"`

	// OnUserInput hooks run when the agent needs user input
	OnUserInput []HookDefinition `json:"on_user_input,omitempty" yaml:"on_user_input,omitempty"`

	// Stop hooks run when the model finishes responding and is about to hand control back to the user
	Stop []HookDefinition `json:"stop,omitempty" yaml:"stop,omitempty"`

	// Notification hooks run when the agent sends a notification (error, warning) to the user
	Notification []HookDefinition `json:"notification,omitempty" yaml:"notification,omitempty"`

	// OnError hooks run when the runtime hits an error during a turn
	// (model failures, repetitive tool-call loops). Fires alongside
	// Notification with level="error".
	OnError []HookDefinition `json:"on_error,omitempty" yaml:"on_error,omitempty"`

	// OnMaxIterations hooks run when the runtime reaches its configured
	// max_iterations limit. Fires alongside Notification with
	// level="warning".
	OnMaxIterations []HookDefinition `json:"on_max_iterations,omitempty" yaml:"on_max_iterations,omitempty"`

	// OnAgentSwitch hooks run whenever the runtime moves the active
	// agent to a new one — transfer_task, handoff, or the return
	// after a transferred task completes. Observational; useful for
	// audit, transcript, and metrics pipelines.
	OnAgentSwitch []HookDefinition `json:"on_agent_switch,omitempty" yaml:"on_agent_switch,omitempty"`

	// OnSessionResume hooks run when the user explicitly approves the
	// runtime to continue past its configured max_iterations limit.
	// Observational; useful for alerting on extended-runtime sessions.
	OnSessionResume []HookDefinition `json:"on_session_resume,omitempty" yaml:"on_session_resume,omitempty"`

	// OnToolApprovalDecision hooks run after the runtime's tool
	// approval chain resolves a verdict for a tool call. Observational;
	// gives audit pipelines a structured "who approved what" record
	// without re-implementing the chain.
	OnToolApprovalDecision []HookDefinition `json:"on_tool_approval_decision,omitempty" yaml:"on_tool_approval_decision,omitempty"`

	// BeforeCompaction hooks run immediately before a session compaction.
	// Hooks may veto compaction (Decision: "block") or supply a custom
	// summary via HookSpecificOutput.summary, in which case the runtime
	// applies that summary verbatim and skips the LLM call. Hooks receive
	// the current input/output token counts, the model context limit, and
	// a compaction_reason of "threshold", "overflow", or "manual".
	BeforeCompaction []HookDefinition `json:"before_compaction,omitempty" yaml:"before_compaction,omitempty"`

	// AfterCompaction hooks run after a successful compaction (a summary
	// was applied to the session). The Input.summary field carries the
	// produced summary text. AfterCompaction is purely observational.
	AfterCompaction []HookDefinition `json:"after_compaction,omitempty" yaml:"after_compaction,omitempty"`

	// ToolResponseTransform hooks run between a tool's exec and the
	// runtime's emission/record of the response. Hooks may rewrite the
	// tool's textual output by returning a non-empty
	// HookSpecificOutput.updated_tool_response — the runtime applies
	// the rewrite before the response fans out to event consumers, the
	// recorded chat message, and the post_tool_use hook input. This is
	// the third leg of the redact_secrets feature: pre_tool_use scrubs
	// arguments, before_llm_call scrubs outgoing chat content, and
	// tool_response_transform scrubs tool output. Tool-matched, like
	// pre_tool_use / post_tool_use.
	ToolResponseTransform []HookMatcherConfig `json:"tool_response_transform,omitempty" yaml:"tool_response_transform,omitempty"`

	// WorktreeCreate hooks run once, just after `docker agent run
	// --worktree` creates a git worktree and before the session starts.
	// They execute inside the new worktree (their working directory is
	// the fresh checkout) with the worktree path, branch, and source
	// repository root passed in worktree_path / worktree_branch /
	// worktree_source_dir. Use them to prepare the checkout — copy
	// untracked files like .env from the source dir, install
	// dependencies, warm caches. A hook may abort the run by blocking
	// (decision="block" / continue=false / exit code 2); stdout is added
	// as context.
	WorktreeCreate []HookDefinition `json:"worktree_create,omitempty" yaml:"worktree_create,omitempty"`
}

HooksConfig represents the hooks configuration for an agent. Hooks allow running shell commands at various points in the agent lifecycle.

func (*HooksConfig) IsEmpty ¶ 

func (h *HooksConfig) IsEmpty() bool

IsEmpty returns true if no hooks are configured

func (*HooksConfig) Validate ¶ added in v1.56.0 

func (h *HooksConfig) Validate() error

Validate validates the HooksConfig

type IdentityTokenSourceConfig ¶ added in v1.55.0 

type IdentityTokenSourceConfig struct {
	// File reads the token from a file path. The file is re-read on every
	// federation exchange (suitable for K8s projected SA tokens, SPIFFE
	// helpers, Vault sidecars and other rotating-on-disk credentials).
	// Surrounding whitespace is trimmed.
	File string `json:"file,omitempty" yaml:"file,omitempty"`

	// Env reads the token from the named environment variable. The variable
	// is resolved through the runtime environment.Provider, so it works
	// with the standard process env, .env files, and Docker Desktop secret
	// providers. Surrounding whitespace is trimmed.
	Env string `json:"env,omitempty" yaml:"env,omitempty"`

	// Command executes a subprocess and uses its stdout as the token.
	// The first element is the executable; the remainder are arguments.
	// The command is re-run on every federation exchange. Stderr is logged.
	// Surrounding whitespace is trimmed from stdout.
	Command []string `json:"command,omitempty" yaml:"command,omitempty"`

	// URL fetches the token from an HTTP(S) endpoint via GET. ${VAR}
	// references in the URL are expanded against the runtime environment.
	// Useful for cloud metadata servers (GCP, Azure IMDS) and the
	// GitHub Actions OIDC token endpoint.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
	// Headers are sent with the URL request. Values support ${VAR}
	// expansion against the runtime environment, which lets you inject a
	// short-lived bearer token (e.g. ACTIONS_ID_TOKEN_REQUEST_TOKEN) without
	// putting it in the YAML.
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
	// ResponseField, when set, parses the URL response as JSON and reads
	// the named top-level field. When empty, the entire response body
	// (with surrounding whitespace trimmed) is used as the token.
	// Examples: GitHub Actions returns {"value":"<jwt>"} → "value";
	// GCP metadata returns the raw JWT → leave empty.
	ResponseField string `json:"response_field,omitempty" yaml:"response_field,omitempty"`
}

IdentityTokenSourceConfig describes one of several ways to obtain a JWT identity token for OIDC federation. Exactly one of File, Env, Command, or URL must be set.

type InlineSkill ¶ added in v1.70.2 

type InlineSkill struct {
	// Name is the skill identifier used by read_skill / run_skill and the
	// /<name> slash command. Required.
	Name string `json:"name" yaml:"name"`
	// Description is injected into the system prompt so the model knows when
	// the skill applies. Required.
	Description string `json:"description" yaml:"description"`
	// Instructions is the skill body (equivalent to the Markdown content
	// below the SKILL.md frontmatter). Required.
	Instructions string `json:"instructions" yaml:"instructions"`
	// Context, when set to "fork", runs the skill as an isolated sub-agent
	// (exposed via run_skill) instead of inlining it in the conversation.
	Context string `json:"context,omitempty" yaml:"context,omitempty"`
	// Model optionally overrides the model used while a fork-mode skill runs.
	// Ignored for non-fork skills.
	Model string `json:"model,omitempty" yaml:"model,omitempty"`
	// AllowedTools optionally records the tools the skill expects. It mirrors
	// the SKILL.md `allowed-tools` field.
	AllowedTools []string `json:"allowed_tools,omitempty" yaml:"allowed_tools,omitempty"`
}

InlineSkill is a skill defined directly in the agent config rather than loaded from the filesystem or a remote URL. It supports the subset of the SKILL.md format that can be expressed in YAML; the skill body lives in Instructions instead of a Markdown file.

type LifecycleConfig ¶ added in v1.54.0 

type LifecycleConfig struct {
	// Profile is a shorthand that picks defaults for all the other fields.
	// Empty means "resilient". Explicit fields override the profile.
	Profile string `json:"profile,omitempty" yaml:"profile,omitempty"`

	// Required, when set, indicates the toolset is critical to the agent.
	//
	// NOTE: this field is currently informational — the runtime does NOT
	// yet block agent startup on it. The wiring lives behind a planned
	// eager-startup commit; until then, callers can read the effective
	// value via IsRequired() but the supervisor itself does not act on it.
	//
	// nil pointer means "use the profile default" (true under "strict",
	// false otherwise).
	Required *bool `json:"required,omitempty" yaml:"required,omitempty"`

	// StartupTimeout caps the duration of the initial Connect call.
	//
	// NOTE: this field is currently informational — the runtime does NOT
	// yet enforce it. The supervisor's Start uses the caller's context
	// for cancellation today; honouring StartupTimeout requires the same
	// eager-startup wiring as Required.
	//
	// Zero means "no timeout".
	StartupTimeout Duration `json:"startup_timeout,omitzero" yaml:"startup_timeout,omitempty"`

	// CallTimeout is informational; it documents the user's expectation
	// for individual tool calls. The runtime currently uses the caller's
	// context for cancellation.
	CallTimeout Duration `json:"call_timeout,omitzero" yaml:"call_timeout,omitempty"`

	// Restart controls how the supervisor reacts to an unexpected
	// disconnect: "never", "on_failure" (default), or "always".
	Restart string `json:"restart,omitempty" yaml:"restart,omitempty"`

	// MaxRestarts is the maximum number of consecutive restart attempts
	// after a disconnect. 0 = use profile default (5). -1 = unlimited.
	MaxRestarts int `json:"max_restarts,omitempty" yaml:"max_restarts,omitempty"`

	// Backoff controls the wait between restart attempts.
	Backoff *BackoffConfig `json:"backoff,omitempty" yaml:"backoff,omitempty"`
}

LifecycleConfig configures how the agent supervises a long-running toolset process (MCP server, remote MCP, LSP server).

All fields are optional. The simplest usage is to pick a Profile that matches your taste:

  • "resilient" (default): auto-restart on failure with exponential backoff, optional toolset (a missing MCP doesn't block the agent). This matches the historical docker-agent behaviour.
  • "strict": fail fast — Required=true, no auto-restart. Use this in CI/headless runs where you want the agent to refuse to start if a dependency is unavailable.
  • "best-effort": single attempt, no restart, optional. Use for experimental MCPs whose flakiness you don't want to amplify with restart loops.

Explicit fields override the profile's defaults, so a user can write: 

lifecycle:
  profile: resilient
  max_restarts: 10

to get resilient behaviour with a higher restart budget.

YAML example with all knobs: 

lifecycle:
  profile: resilient        # strict | resilient | best-effort
  required: false           # block agent startup if not Ready in startup_timeout
  startup_timeout: 30s      # max wait for initial Connect+initialize
  call_timeout: 60s         # default per-call timeout (informational)
  restart: on_failure       # never | on_failure | always
  max_restarts: 5           # consecutive attempts; 0 = profile default; -1 = unlimited
  backoff:
    initial: 1s
    max: 32s
    multiplier: 2.0
    jitter: 0.2             # 0..1, 0 disables (default)

func (*LifecycleConfig) EffectiveStartupTimeout ¶ added in v1.54.0 

func (l *LifecycleConfig) EffectiveStartupTimeout() time.Duration

EffectiveStartupTimeout returns StartupTimeout, falling back to a profile default when zero. Zero in the result means "no timeout".

func (*LifecycleConfig) IsRequired ¶ added in v1.54.0 

func (l *LifecycleConfig) IsRequired() bool

IsRequired returns the effective Required flag for the given profile + explicit override. nil pointer means "use profile default".

type MCPToolset ¶ 

type MCPToolset struct {
	Toolset `json:",inline" yaml:",inline"`
}

MCPToolset is a reusable MCP server definition stored in the top-level "mcps" section. It is identical to a Toolset but skips the normal Toolset.validate() call during YAML unmarshaling because the "type" field is implicit (always "mcp") and the source (command/remote/ref) is validated later during config resolution.

func (*MCPToolset) UnmarshalYAML ¶ 

func (m *MCPToolset) UnmarshalYAML(unmarshal func(any) error) error

type Metadata ¶ 

type Metadata struct {
	Author      string `json:"author,omitempty"`
	License     string `json:"license,omitempty"`
	Description string `json:"description,omitempty"`
	Readme      string `json:"readme,omitempty"`
	Version     string `json:"version,omitempty"`
}

type ModelConfig ¶ 

type ModelConfig struct {
	// Name is the manifest model name (map key), populated at runtime.
	// Not serialized — set by teamloader/model_switcher when resolving models.
	Name     string `json:"-"`
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	// DisplayModel holds the original model name from the YAML config, before alias resolution.
	// When set, provider.ID() returns Provider + "/" + DisplayModel instead of the resolved name.
	// This ensures the UI shows the user-configured name (e.g., "claude-haiku-4-5")
	// while the API uses the resolved name (e.g., "claude-haiku-4-5-20251001").
	DisplayModel      string   `json:"-"`
	Temperature       *float64 `json:"temperature,omitempty"`
	MaxTokens         *int64   `json:"max_tokens,omitempty"`
	TopP              *float64 `json:"top_p,omitempty"`
	FrequencyPenalty  *float64 `json:"frequency_penalty,omitempty"`
	PresencePenalty   *float64 `json:"presence_penalty,omitempty"`
	BaseURL           string   `json:"base_url,omitempty"`
	ParallelToolCalls *bool    `json:"parallel_tool_calls,omitempty"`
	TokenKey          string   `json:"token_key,omitempty"`
	// ProviderOpts allows provider-specific options.
	ProviderOpts map[string]any `json:"provider_opts,omitempty"`
	TrackUsage   *bool          `json:"track_usage,omitempty"`
	// ThinkingBudget controls reasoning effort/budget.
	// Accepts an integer token count or a string effort level.
	// See [effort.ValidNames] for the full list of accepted strings.
	// Provider-specific mappings are in the effort package.
	ThinkingBudget *ThinkingBudget `json:"thinking_budget,omitempty"`
	// TaskBudget caps the total tokens a model can spend across an agentic task.
	// Forwarded to Anthropic as `output_config.task_budget` for every Claude
	// model — docker-agent does not gate by model name. At the time of writing,
	// only Claude Opus 4.7 actually honors it; other models will reject the
	// field. Accepts an integer token count or a {type: tokens, total: N} object.
	TaskBudget *TaskBudget `json:"task_budget,omitempty"`
	// Auth selects a non-API-key authentication scheme for this model
	// (currently: Anthropic Workload Identity Federation). When set, it
	// takes precedence over both the provider's API-key path and any
	// auth defined on the referenced ProviderConfig.
	Auth *AuthConfig `json:"auth,omitempty"`
	// Routing defines rules for routing requests to different models.
	// When routing is configured, this model becomes a rule-based router:
	// - The provider/model fields define the fallback model
	// - Each routing rule maps to a different model based on examples
	Routing []RoutingRule `json:"routing,omitempty"`
}

ModelConfig represents the configuration for a model

func ParseModelRef ¶ added in v1.30.1 

func ParseModelRef(ref string) (ModelConfig, error)

ParseModelRef parses an inline "provider/model" reference into a ModelConfig. It returns an error when the string does not contain exactly one "/" separator or when either part is empty. 

cfg, err := ParseModelRef("openai/gpt-4o")
// cfg.Provider == "openai", cfg.Model == "gpt-4o"

func (*ModelConfig) Clone ¶ 

func (m *ModelConfig) Clone() *ModelConfig

Clone returns a deep copy of the ModelConfig.

func (*ModelConfig) DisplayOrModel ¶ 

func (m *ModelConfig) DisplayOrModel() string

DisplayOrModel returns DisplayModel if set (i.e., alias resolution preserved the original name), otherwise falls back to Model.

func (*ModelConfig) UnloadAPI ¶ added in v1.57.0 

func (m *ModelConfig) UnloadAPI() string

UnloadAPI returns the unload endpoint inherited from the model's provider config, or "" when no `unload_api` was set. Populated by the provider-config merge step from [ProviderConfig.UnloadAPI].

type PermissionsConfig ¶ 

type PermissionsConfig struct {
	// Allow lists tool name patterns that are auto-approved without user confirmation
	Allow []string `json:"allow,omitempty"`
	// Ask lists tool name patterns that always require user confirmation,
	// even for tools that are normally auto-approved (e.g. read-only tools)
	Ask []string `json:"ask,omitempty"`
	// Deny lists tool name patterns that are always rejected
	Deny []string `json:"deny,omitempty"`
}

PermissionsConfig represents tool permission configuration. Allow/Ask/Deny model. This controls tool call approval behavior: - Allow: Tools matching these patterns are auto-approved (like --yolo for specific tools) - Ask: Tools matching these patterns always require user approval, even if the tool is read-only - Deny: Tools matching these patterns are always rejected, even with --yolo

Patterns support glob-style matching (e.g., "shell", "read_*", "mcp:github:*") The evaluation order is: Deny (checked first), then Allow, then Ask (explicit), then default (read-only tools auto-approved, others ask)

type PostEditConfig ¶ 

type PostEditConfig struct {
	Path string `json:"path"`
	Cmd  string `json:"cmd"`
}

PostEditConfig represents a post-edit command configuration

type ProviderConfig ¶ 

type ProviderConfig struct {
	// Provider specifies the underlying provider type. Supported values include:
	// "openai", "anthropic", "google", "amazon-bedrock", "dmr", and any built-in alias.
	// Defaults to "openai" when not set, preserving backward compatibility.
	Provider string `json:"provider,omitempty"`
	// APIType specifies which API schema to use. Only applicable for OpenAI-compatible providers.
	// Supported values:
	// - "openai_chatcompletions" (default for openai): Use the OpenAI Chat Completions API
	// - "openai_responses": Use the OpenAI Responses API
	APIType string `json:"api_type,omitempty"`
	// BaseURL is the base URL for the provider's API endpoint
	BaseURL string `json:"base_url,omitempty"`
	// UnloadAPI is the path (or absolute URL) to the provider's
	// model-unload endpoint. When the agent wires the [unload] builtin
	// into its `on_agent_switch` hook chain, the previous agent's
	// models are POSTed `{"model": "<id>"}` here at every switch.
	// Cloud providers should leave this unset.
	//
	// [unload]: https://pkg.go.dev/github.com/docker/docker-agent/pkg/hooks/builtins#Unload
	UnloadAPI string `json:"unload_api,omitempty"`
	// TokenKey is the environment variable name containing the API token
	TokenKey string `json:"token_key,omitempty"`
	// Temperature is the default sampling temperature for models using this provider
	Temperature *float64 `json:"temperature,omitempty"`
	// MaxTokens is the default maximum number of tokens for models using this provider
	MaxTokens *int64 `json:"max_tokens,omitempty"`
	// TopP is the default top-p sampling parameter
	TopP *float64 `json:"top_p,omitempty"`
	// FrequencyPenalty is the default frequency penalty
	FrequencyPenalty *float64 `json:"frequency_penalty,omitempty"`
	// PresencePenalty is the default presence penalty
	PresencePenalty *float64 `json:"presence_penalty,omitempty"`
	// ParallelToolCalls controls whether parallel tool calls are enabled by default
	ParallelToolCalls *bool `json:"parallel_tool_calls,omitempty"`
	// ProviderOpts allows provider-specific options
	ProviderOpts map[string]any `json:"provider_opts,omitempty"`
	// TrackUsage controls whether token usage tracking is enabled by default
	TrackUsage *bool `json:"track_usage,omitempty"`
	// ThinkingBudget controls reasoning effort/budget for models using this provider
	ThinkingBudget *ThinkingBudget `json:"thinking_budget,omitempty"`
	// TaskBudget caps the total tokens a model can spend across an agentic task.
	// Forwarded to Anthropic as `output_config.task_budget` for every Claude
	// model — docker-agent does not gate by model name. At the time of writing,
	// only Claude Opus 4.7 actually honors it; other models will reject the
	// field. Accepts an integer token count or a {type: tokens, total: N} object.
	TaskBudget *TaskBudget `json:"task_budget,omitempty"`
	// Auth selects a non-API-key authentication scheme for this provider
	// (currently: Anthropic Workload Identity Federation). When set, the
	// provider's regular API-key path is bypassed.
	Auth *AuthConfig `json:"auth,omitempty"`
}

ProviderConfig represents a reusable provider definition. It allows users to define providers with default settings that models can inherit. Models referencing a provider by name will inherit any settings not explicitly overridden.

The Provider field specifies the underlying provider type (e.g., "openai", "anthropic", "google", "amazon-bedrock"). When not set, it defaults to "openai" for backward compatibility.

type RAGChunkingConfig ¶ 

type RAGChunkingConfig struct {
	Size                  int  `json:"size,omitempty"`
	Overlap               int  `json:"overlap,omitempty"`
	RespectWordBoundaries bool `json:"respect_word_boundaries,omitempty"`
	// CodeAware enables code-aware chunking for source files. When true, the
	// chunking strategy uses tree-sitter for AST-based chunking, producing
	// semantically aligned chunks (e.g., whole functions). Falls back to
	// plain text chunking for unsupported languages.
	CodeAware bool `json:"code_aware,omitempty"`
}

RAGChunkingConfig represents text chunking configuration

func (*RAGChunkingConfig) UnmarshalYAML ¶ 

func (c *RAGChunkingConfig) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling to apply sensible defaults for chunking

type RAGConfig ¶ 

type RAGConfig struct {
	Tool       RAGToolConfig       `json:"tool"`                  // Tool configuration
	Docs       []string            `json:"docs,omitempty"`        // Shared documents across all strategies
	RespectVCS *bool               `json:"respect_vcs,omitempty"` // Whether to respect VCS ignore files like .gitignore (default: true)
	Strategies []RAGStrategyConfig `json:"strategies,omitempty"`  // Array of strategy configurations
	Results    RAGResultsConfig    `json:"results"`
}

RAGConfig represents a RAG (Retrieval-Augmented Generation) configuration Uses a unified strategies array for flexible, extensible configuration

func (*RAGConfig) GetRespectVCS ¶ 

func (c *RAGConfig) GetRespectVCS() bool

GetRespectVCS returns whether VCS ignore files should be respected, defaulting to true

func (*RAGConfig) UnmarshalYAML ¶ 

func (c *RAGConfig) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML for RAGConfig ensures that the Results field is always initialized with defaults, even when the `results` block is omitted.

type RAGDatabaseConfig ¶ 

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

RAGDatabaseConfig represents database configuration for RAG strategies. Currently it only supports a single string value which is interpreted as the path to a SQLite database file.

func (*RAGDatabaseConfig) AsString ¶ 

func (d *RAGDatabaseConfig) AsString() (string, error)

AsString returns the database config as a connection string For simple string configs, returns as-is For structured configs, builds connection string based on type

func (*RAGDatabaseConfig) IsEmpty ¶ 

func (d *RAGDatabaseConfig) IsEmpty() bool

IsEmpty returns true if no database is configured

func (*RAGDatabaseConfig) UnmarshalYAML ¶ 

func (d *RAGDatabaseConfig) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling for DatabaseConfig

type RAGFusionConfig ¶ 

type RAGFusionConfig struct {
	Strategy string             `json:"strategy,omitempty"` // Fusion strategy: "rrf" (Reciprocal Rank Fusion), "weighted", "max"
	K        int                `json:"k,omitempty"`        // RRF parameter k (default: 60)
	Weights  map[string]float64 `json:"weights,omitempty"`  // Strategy weights for weighted fusion
}

RAGFusionConfig represents configuration for combining multi-strategy results

type RAGRerankingConfig ¶ 

type RAGRerankingConfig struct {
	Model     string  `json:"model"`               // Model reference for reranking (e.g., "hf.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF")
	TopK      int     `json:"top_k,omitempty"`     // Optional: only rerank top K results (0 = rerank all)
	Threshold float64 `json:"threshold,omitempty"` // Optional: minimum score threshold after reranking (default: 0.5)
	Criteria  string  `json:"criteria,omitempty"`  // Optional: domain-specific relevance criteria to guide scoring
}

RAGRerankingConfig represents reranking configuration

func (*RAGRerankingConfig) UnmarshalYAML ¶ 

func (r *RAGRerankingConfig) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling to apply sensible defaults for reranking

type RAGResultsConfig ¶ 

type RAGResultsConfig struct {
	Limit             int                 `json:"limit,omitempty"`               // Maximum number of results to return (top K)
	Fusion            *RAGFusionConfig    `json:"fusion,omitempty"`              // How to combine results from multiple strategies
	Reranking         *RAGRerankingConfig `json:"reranking,omitempty"`           // Optional reranking configuration
	Deduplicate       bool                `json:"deduplicate,omitempty"`         // Remove duplicate documents across strategies
	IncludeScore      bool                `json:"include_score,omitempty"`       // Include relevance scores in results
	ReturnFullContent bool                `json:"return_full_content,omitempty"` // Return full document content instead of just matched chunks
}

RAGResultsConfig represents result post-processing configuration (common across strategies)

func (*RAGResultsConfig) UnmarshalYAML ¶ 

func (r *RAGResultsConfig) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling so we can apply sensible defaults

type RAGStrategyConfig ¶ 

type RAGStrategyConfig struct {
	Type     string            `json:"type"`            // Strategy type: "chunked-embeddings", "bm25", etc.
	Docs     []string          `json:"docs,omitempty"`  // Strategy-specific documents (augments shared docs)
	Database RAGDatabaseConfig `json:"database"`        // Database configuration
	Chunking RAGChunkingConfig `json:"chunking"`        // Chunking configuration
	Limit    int               `json:"limit,omitempty"` // Max results from this strategy (for fusion input)

	// Strategy-specific parameters (arbitrary key-value pairs)
	// Examples:
	// - chunked-embeddings: embedding_model, similarity_metric, threshold, vector_dimensions
	// - bm25: k1, b, threshold
	Params map[string]any // Flattened into parent JSON
}

RAGStrategyConfig represents a single retrieval strategy configuration Strategy-specific fields are stored in Params (validated by strategy implementation)

func (RAGStrategyConfig) MarshalJSON ¶ 

func (s RAGStrategyConfig) MarshalJSON() ([]byte, error)

MarshalJSON implements custom marshaling to flatten Params into parent level This ensures JSON and YAML have the same flattened format for consistency

func (RAGStrategyConfig) MarshalYAML ¶ 

func (s RAGStrategyConfig) MarshalYAML() (any, error)

MarshalYAML implements custom marshaling to flatten Params into parent level

func (*RAGStrategyConfig) UnmarshalJSON ¶ 

func (s *RAGStrategyConfig) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling to capture all extra fields into Params This ensures JSON and YAML have the same flattened format for consistency

func (*RAGStrategyConfig) UnmarshalYAML ¶ 

func (s *RAGStrategyConfig) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML implements custom unmarshaling to capture all extra fields into Params This allows strategies to have flexible, strategy-specific configuration parameters without requiring changes to the core config schema

type RAGToolConfig ¶ 

type RAGToolConfig struct {
	Name        string `json:"name,omitempty"`        // Custom name for the tool (defaults to RAG source name if empty)
	Description string `json:"description,omitempty"` // Tool description (what the tool does)
	Instruction string `json:"instruction,omitempty"` // Tool instruction (how to use the tool effectively)
}

RAGToolConfig represents tool-specific configuration for a RAG source

type RAGToolset ¶ added in v1.37.0 

type RAGToolset struct {
	Toolset `json:",inline" yaml:",inline"`
}

RAGToolset is a reusable RAG source definition stored in the top-level "rag" section. It is identical to a Toolset but skips the normal Toolset.validate() call during YAML unmarshaling because the "type" field is implicit (always "rag") and the RAG config is validated during config resolution.

func (RAGToolset) MarshalYAML ¶ added in v1.37.0 

func (r RAGToolset) MarshalYAML() (any, error)

func (*RAGToolset) UnmarshalYAML ¶ added in v1.37.0 

func (r *RAGToolset) UnmarshalYAML(unmarshal func(any) error) error

type Remote ¶ 

type Remote struct {
	URL           string             `json:"url"`
	TransportType string             `json:"transport_type,omitempty"`
	Headers       map[string]string  `json:"headers,omitempty"`
	OAuth         *RemoteOAuthConfig `json:"oauth,omitempty"`
}

type RemoteOAuthConfig ¶ added in v1.46.0 

type RemoteOAuthConfig struct {
	ClientID     string   `json:"clientId"`
	ClientSecret string   `json:"clientSecret,omitempty"`
	CallbackPort int      `json:"callbackPort,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
	// CallbackRedirectURL, when set, is used as the OAuth redirect URI
	// instead of the default http://127.0.0.1:{callbackPort}/callback.
	// This allows inserting a public-facing proxy (e.g. a URL shortener or
	// a pre-registered static redirect) in front of the local callback
	// server — useful for authorization servers that require the redirect
	// URI to be HTTPS or pre-registered.
	//
	// The literal placeholder ${callbackPort} is replaced with the actual
	// port the local callback server is listening on (either CallbackPort
	// when set, or a random free port otherwise). The external URL is
	// expected to redirect the browser back to
	// http://127.0.0.1:{callbackPort}/callback preserving the OAuth query
	// parameters.
	CallbackRedirectURL string `json:"callbackRedirectURL,omitempty"`
}

RemoteOAuthConfig holds explicit OAuth credentials for remote MCP servers that do not support Dynamic Client Registration (RFC 7591).

type RoutingRule ¶ 

type RoutingRule struct {
	// Model is a reference to another model in the models section or an inline model spec (e.g., "openai/gpt-4o")
	Model string `json:"model"`
	// Examples are phrases that should trigger routing to this model
	Examples []string `json:"examples"`
}

RoutingRule defines a single routing rule for model selection. Each rule maps example phrases to a target model.

type RuntimeDefaults ¶ added in v1.66.0 

type RuntimeDefaults struct {
	// Sandbox, when true, runs the agent inside a Docker sandbox by
	// default — equivalent to passing --sandbox on the command line.
	// Useful for agents that always need filesystem/network isolation.
	Sandbox bool `json:"sandbox,omitempty" yaml:"sandbox,omitempty"`

	// NetworkAllowlist is the list of hosts that should be added to
	// the sandbox's default-deny network proxy when this agent runs in
	// a sandbox. Each entry is a hostname with an optional ":port"
	// suffix (e.g. "api.example.com", "registry.npmjs.org:443"). The
	// list is unioned with the gateway and tool-install hosts the
	// runner already opens automatically; commas and whitespace are
	// rejected to keep a single entry from smuggling several rules
	// into the policy engine.
	//
	// Use this when an agent's tools call hosts the auto-installer
	// can't infer (custom MCP endpoints, third-party APIs, registries
	// not covered by the aqua resolver, etc.) instead of relying on
	// the wider fallback host set the kit uses on resolution failures.
	NetworkAllowlist []string `json:"network_allowlist,omitempty" yaml:"network_allowlist,omitempty"`
}

RuntimeDefaults captures execution-time defaults the agent author wants applied when this config is run. The values act as defaults only: an explicit CLI flag or user-config setting always wins.

type ScriptShellToolConfig ¶ 

type ScriptShellToolConfig struct {
	Cmd         string `json:"cmd"`
	Description string `json:"description"`

	// Args is directly passed as "properties" in the JSON schema
	Args map[string]any `json:"args,omitempty"`

	// Required is directly passed as "required" in the JSON schema
	Required []string `json:"required"`

	Env        map[string]string `json:"env,omitempty"`
	WorkingDir string            `json:"working_dir,omitempty"`
}

ScriptShellToolConfig represents a custom shell tool configuration

type SkillsConfig ¶ 

type SkillsConfig struct {
	// Sources lists where to load skills from: "local" and/or HTTP/HTTPS URLs.
	Sources []string
	// Include optionally filters loaded skills by name. When non-empty, only
	// skills whose Name matches an entry in this list are exposed to the agent.
	Include []string
	// Inline holds skills defined directly in the agent config. They are
	// always exposed (never subject to the Include filter) and are not
	// affected by Sources.
	Inline []InlineSkill
}

SkillsConfig controls skill discovery sources, filtering, and inline definitions for an agent. Supports these YAML formats:

  • Boolean: `skills: true` (equivalent to ["local"]) or `skills: false` (disabled)
  • List: `skills: ["local", "http://example.com"]` — sources to load from
  • List: `skills: ["git", "docker"]` — names of skills to include
  • List: `skills: ["local", "git"]` — mix of sources and names
  • List: a list may also contain mapping items, each an inline skill definition (see InlineSkill), freely mixed with the string items above.

String items in the list are classified automatically:

  • "local" or any HTTP/HTTPS URL → a skill source (added to Sources)
  • any other string → a skill name filter (added to Include)

Mapping items are decoded as inline skills (added to Inline).

When Include is non-empty but no explicit sources are provided, Sources defaults to ["local"] so that `skills: ["git"]` loads local skills and keeps only "git". Inline skills on their own do not pull in any sources: a list containing only inline definitions enables skills without loading local or remote ones.

The special source "local" loads skills from the filesystem (standard locations). HTTP/HTTPS URLs load skills from remote servers per the well-known skills discovery spec.

func (SkillsConfig) Enabled ¶ 

func (s SkillsConfig) Enabled() bool

func (SkillsConfig) HasLocal ¶ 

func (s SkillsConfig) HasLocal() bool

func (SkillsConfig) MarshalJSON ¶ 

func (s SkillsConfig) MarshalJSON() ([]byte, error)

func (SkillsConfig) MarshalYAML ¶ 

func (s SkillsConfig) MarshalYAML() (any, error)

func (SkillsConfig) RemoteURLs ¶ 

func (s SkillsConfig) RemoteURLs() []string

func (*SkillsConfig) UnmarshalJSON ¶ 

func (s *SkillsConfig) UnmarshalJSON(data []byte) error

func (*SkillsConfig) UnmarshalYAML ¶ 

func (s *SkillsConfig) UnmarshalYAML(unmarshal func(any) error) error

type StructuredOutput ¶ 

type StructuredOutput struct {
	// Name is the name of the response format
	Name string `json:"name"`
	// Description is optional description of the response format
	Description string `json:"description,omitempty"`
	// Schema is a JSON schema object defining the structure
	Schema map[string]any `json:"schema"`
	// Strict enables strict schema adherence (OpenAI only)
	Strict bool `json:"strict,omitempty"`
}

StructuredOutput defines a JSON schema for structured output

type TaskBudget ¶ added in v1.46.0 

type TaskBudget struct {
	// Type is the budget kind. Only "tokens" is supported today; defaults to
	// "tokens" when Total is set via the integer shorthand.
	Type string `json:"type,omitempty"`
	// Total is the total budget value (token count for Type == "tokens").
	Total int `json:"total,omitempty"`
}

TaskBudget caps the total tokens a model can spend across an agentic task (combined thinking, tool calls, and final output). It is forwarded to Anthropic as `output_config.task_budget` and docker-agent automatically attaches the required `task-budgets-2026-03-13` beta header when set.

docker-agent does not gate by model name — any Claude model accepts the configuration, though at the time of writing only Claude Opus 4.7 actually honors it; other models will reject requests containing the field. See: https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7

Accepted YAML/JSON forms:

  • Integer shorthand ("tokens" budget): task_budget: 128000
  • Full object: task_budget: {type: tokens, total: 128000}

A value of 0 (or an empty object) disables the feature.

func (*TaskBudget) AsMap ¶ added in v1.46.0 

func (t *TaskBudget) AsMap() map[string]any

AsMap returns the API representation, or nil when the budget is zero.

func (*TaskBudget) IsZero ¶ added in v1.46.0 

func (t *TaskBudget) IsZero() bool

IsZero reports whether the task budget is effectively unset.

A budget is considered unset when Total <= 0 (there is no meaningful "zero-token" budget, and validate() already rejects negative totals for explicit object forms). This is what lets users disable the feature with the shorthand `task_budget: 0`, which otherwise unmarshals to a non-empty {Type: "tokens", Total: 0} struct.

func (TaskBudget) MarshalJSON ¶ added in v1.46.0 

func (t TaskBudget) MarshalJSON() ([]byte, error)

MarshalJSON emits the integer shorthand for a plain token budget.

func (TaskBudget) MarshalYAML ¶ added in v1.46.0 

func (t TaskBudget) MarshalYAML() (any, error)

MarshalYAML emits the integer shorthand for a plain token budget, otherwise the full {type, total} object.

func (*TaskBudget) UnmarshalJSON ¶ added in v1.46.0 

func (t *TaskBudget) UnmarshalJSON(data []byte) error

UnmarshalJSON mirrors UnmarshalYAML: accepts int shorthand or full object.

func (*TaskBudget) UnmarshalYAML ¶ added in v1.46.0 

func (t *TaskBudget) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML accepts either an integer shorthand (tokens) or a full object.

type ThinkingBudget ¶ 

type ThinkingBudget struct {
	// Effort stores string-based reasoning effort levels
	Effort string `json:"effort,omitempty"`
	// Tokens stores integer-based token budgets
	Tokens int `json:"tokens,omitempty"`
}

ThinkingBudget represents reasoning budget configuration. It accepts either a string effort level (see effort.ValidNames) or an integer token budget.

func (*ThinkingBudget) AdaptiveEffort ¶ added in v1.35.0 

func (t *ThinkingBudget) AdaptiveEffort() (string, bool)

AdaptiveEffort returns the effort level for adaptive thinking. For "adaptive" it returns the default ("high"). For "adaptive/<effort>" it returns the specified effort. Returns ("", false) if the budget is not adaptive.

func (*ThinkingBudget) EffortLevel ¶ added in v1.35.0 

func (t *ThinkingBudget) EffortLevel() (effort.Level, bool)

EffortLevel parses the Effort field into an effort.Level. Returns ("", false) when the budget is nil, uses token counts, or has an unrecognised effort string.

func (*ThinkingBudget) EffortTokens ¶ added in v1.32.5 

func (t *ThinkingBudget) EffortTokens() (int, bool)

EffortTokens maps a string effort level to a token budget for providers that only support token-based thinking (e.g. Bedrock Claude). Delegates to effort.BedrockTokens.

Returns (tokens, true) when a mapping exists, or (0, false) when the budget uses an explicit token count or an unrecognised effort string.

func (*ThinkingBudget) IsAdaptive ¶ added in v1.32.5 

func (t *ThinkingBudget) IsAdaptive() bool

IsAdaptive returns true if the thinking budget is set to adaptive mode. Adaptive thinking lets the model decide how much thinking to do. Matches both "adaptive" and "adaptive/<effort>" formats.

func (*ThinkingBudget) IsDisabled ¶ added in v1.30.1 

func (t *ThinkingBudget) IsDisabled() bool

IsDisabled returns true if the thinking budget is explicitly disabled. A nil receiver is treated as "not configured" (not disabled).

Disabled when:

  • Tokens == 0 with no Effort (thinking_budget: 0)
  • Effort == "none" (thinking_budget: none)

NOT disabled when:

  • Tokens > 0 or Tokens == -1 (explicit token budget)
  • Effort is a real level like "medium" or "high"
  • Effort is "adaptive"

func (ThinkingBudget) MarshalJSON ¶ 

func (t ThinkingBudget) MarshalJSON() ([]byte, error)

MarshalJSON implements custom marshaling to output simple string or int format This ensures JSON and YAML have the same flattened format for consistency

func (ThinkingBudget) MarshalYAML ¶ 

func (t ThinkingBudget) MarshalYAML() (any, error)

MarshalYAML implements custom marshaling to output simple string or int format

func (*ThinkingBudget) UnmarshalJSON ¶ 

func (t *ThinkingBudget) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom unmarshaling to accept simple string or int format This ensures JSON and YAML have the same flattened format for consistency

func (*ThinkingBudget) UnmarshalYAML ¶ 

func (t *ThinkingBudget) UnmarshalYAML(unmarshal func(any) error) error

type Toolset ¶ 

type Toolset struct {
	Type        string   `json:"type,omitempty"`
	Tools       []string `json:"tools,omitempty"`
	Instruction string   `json:"instruction,omitempty"`
	Toon        string   `json:"toon,omitempty"`

	// Model overrides the LLM used for the turn that processes tool results
	// from this toolset, enabling per-toolset model routing. Value can be a
	// model name from the models section or "provider/model" (e.g. "openai/gpt-4o-mini").
	Model string `json:"model,omitempty"`

	Defer DeferConfig `json:"defer,omitzero" yaml:"defer,omitempty"`

	// For the `mcp` tool
	Command string   `json:"command,omitempty"`
	Args    []string `json:"args,omitempty"`
	Ref     string   `json:"ref,omitempty"`
	Remote  Remote   `json:"remote"`
	Config  any      `json:"config,omitempty"`

	// For `mcp` and `lsp` tools - version/package reference for auto-installation.
	// Format: "owner/repo" or "owner/repo@version"
	// When empty and auto-install is enabled, docker agent auto-detects from the command name.
	// Set to "false" or "off" to disable auto-install for this toolset.
	Version string `json:"version,omitempty"`

	// For the `a2a`, `api`, `openapi` and `fetch` tools
	Name    string            `json:"name,omitempty"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`

	// For `shell`, `script`, `mcp` or `lsp` tools
	Env map[string]string `json:"env,omitempty"`

	// For the `todo` tool
	Shared bool `json:"shared,omitempty"`

	// For the `memory` and `tasks` tools
	Path string `json:"path,omitempty"`

	// For the `script` tool
	Shell map[string]ScriptShellToolConfig `json:"shell,omitempty"`

	// For the `filesystem` tool - post-edit commands
	PostEdit []PostEditConfig `json:"post_edit,omitempty"`

	APIConfig APIToolConfig `json:"api_config"`

	// For the `filesystem` tool - VCS integration
	IgnoreVCS *bool `json:"ignore_vcs,omitempty"`

	// For the `filesystem` tool - allow-list of directories the tools are
	// permitted to access. Each entry may be "." (the agent's working
	// directory), "~" or "~/..." (the user's home directory), an absolute
	// path, or a relative path (anchored at the working directory). When
	// non-empty, every read/write operation is rejected unless its target
	// resolves under one of the listed roots. Symlinks are followed before
	// the containment check so they cannot be used to escape the allow-list.
	// An empty or omitted list preserves the default behaviour (any path
	// reachable by the process is allowed).
	AllowList []string `json:"allow_list,omitempty" yaml:"allow_list,omitempty"`

	// For the `filesystem` tool - deny-list of directories the tools are
	// forbidden to access. Same expansion and matching rules as `allow_list`.
	// The deny-list takes precedence over `allow_list`: a path that matches
	// both is rejected. An empty or omitted list disables the deny-list.
	DenyList []string `json:"deny_list,omitempty" yaml:"deny_list,omitempty"`

	// For the `mcp_catalog` tool - allow-list of catalog server ids that
	// are offered by default. When non-empty, only these servers are
	// searchable and enableable; every other catalog entry is hidden. An
	// empty or omitted list offers the full catalog. Combine with
	// `blocked_servers` to subtract individual ids from the allowed set
	// (block takes precedence).
	AllowedServers []string `json:"allowed_servers,omitempty" yaml:"allowed_servers,omitempty"`

	// For the `mcp_catalog` tool - block-list of catalog server ids that
	// are removed from the offered set. Applied after `allowed_servers`,
	// so a server listed in both is blocked. An empty or omitted list
	// disables the block-list.
	BlockedServers []string `json:"blocked_servers,omitempty" yaml:"blocked_servers,omitempty"`

	// For the `lsp` tool
	FileTypes []string `json:"file_types,omitempty"`

	// HTTP timeout in seconds for `fetch`, `api`, `openapi`, and `a2a` toolsets.
	// Defaults to 30 seconds when omitted.
	Timeout int `json:"timeout,omitempty"`

	// For the `fetch` tool - allow-list of domains the tool is permitted to fetch.
	// A pattern matches the host exactly (case-insensitive) and any of its subdomains;
	// e.g. "example.com" matches "example.com" and "docs.example.com" but not
	// "badexample.com". A leading dot (".example.com") restricts the match to
	// strict subdomains. Mutually exclusive with `blocked_domains`.
	AllowedDomains []string `json:"allowed_domains,omitempty" yaml:"allowed_domains,omitempty"`

	// For the `fetch` tool - deny-list of domains the tool is forbidden to fetch.
	// Uses the same matching rules as `allowed_domains`. Mutually exclusive with
	// `allowed_domains`.
	BlockedDomains []string `json:"blocked_domains,omitempty" yaml:"blocked_domains,omitempty"`

	// For the `fetch`, `api`, `openapi`, `a2a` and remote `mcp` toolsets — opt in
	// to dialling non-public IP addresses.
	//
	// By default, protected HTTP clients refuse connections (after DNS
	// resolution, so DNS rebinding is also blocked) to loopback (127/8,
	// ::1), RFC1918 private ranges, link-local — including the cloud
	// metadata endpoint at 169.254.169.254 — multicast and the unspecified
	// address. Set this to true to permit those addresses, which is required
	// when an agent legitimately needs to call internal services.
	//
	// For `fetch`, `allowed_domains` and `blocked_domains` are evaluated
	// independently of this flag: even with `allow_private_ips: true`, an
	// entry in `blocked_domains` (or absence from `allowed_domains`) still
	// rejects the request before any network call.
	// nil means the field was omitted and may inherit from a referenced definition.
	AllowPrivateIPs *bool `json:"allow_private_ips,omitempty" yaml:"allow_private_ips,omitempty"`

	// For the `rag` tool
	RAGConfig *RAGConfig `json:"rag_config,omitempty" yaml:"rag_config,omitempty"`

	// For the `model_picker` tool
	Models []string `json:"models,omitempty"`

	// For `mcp` and `lsp` tools - optional working directory override.
	// When set, the toolset process is started from this directory.
	// Relative paths are resolved relative to the agent's working directory.
	WorkingDir string `json:"working_dir,omitempty"`

	// For `mcp` and `lsp` tools — lifecycle policy controlling startup,
	// restart, and backoff behaviour. nil means "use the resilient defaults"
	// (auto-restart on failure, 5 attempts, 1s..32s exponential backoff).
	Lifecycle *LifecycleConfig `json:"lifecycle,omitempty"`
}

Toolset represents a tool configuration

func (*Toolset) AllowPrivateIPsEnabled ¶ added in v1.63.0 

func (t *Toolset) AllowPrivateIPsEnabled() bool

AllowPrivateIPsEnabled reports the effective boolean value for allow_private_ips.

func (*Toolset) UnmarshalYAML ¶ 

func (t *Toolset) UnmarshalYAML(unmarshal func(any) error) error

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.