Agent file keys

Every key of the agent file at schema version 16, grouped by block, with its type, default, requirement, and meaning from agent-schema.json at v1.149.0.

The schema is titled Docker Agent Configuration, and the pinned copy is the file at tag v1.149.0, commit bf4169cdd31229d52385410c52c3dcc59b497858 {{schema Docker Agent Configuration}}. Its version enum runs from "0" to "16", so "16" is the current form {{schema version}}. The top level and every block below set additionalProperties to false, so an unknown key fails the load. The only required top-level key is agents {{schema agents}}. Required says whether the schema lists the key under required. Default is the schema default value, and none means the schema states none.

Top-level keys

All 16 keys come from the root properties object {{schema properties}}. The docs page configuration/overview explains the reusable blocks mcps, rag, commands, skills, and toolsets.

Keys under agents

Every key of one agent comes from AgentConfig {{schema AgentConfig}}. The docs page configuration/agents explains them, configuration/structured-output covers structured_output, and features/harnesses covers harness.

An inline skill under skills has name, description, and instructions as required keys, plus context: fork, model, allowed_tools, and toolsets {{schema InlineSkill}}. A command under commands is a string, or an object with description, instruction, agent, and url {{schema CommandConfig}}.

Keys under models

Every key comes from ModelConfig {{schema ModelConfig}}. The docs page configuration/models explains them, and configuration/routing covers routing.

Keys under providers

Every key comes from ProviderConfig {{schema ProviderConfig}}. The docs page providers/custom explains them.

The federation block under auth requires federation_rule_id (prefix fdrl_), organization_id, and identity_token, and accepts service_account_id {{schema FederationAuthConfig}}. The token source has file, env, command, url, headers, and response_field {{schema IdentityTokenSourceConfig}}.

Keys under toolsets

Every key of one toolset entry comes from Toolset {{schema Toolset}}. The docs page configuration/tools explains the shared keys, and R.5 says which type uses which.

A reusable entry under mcps has command, args, ref, remote, config, version, env, tools, instruction, name, defer, working_dir, and lifecycle {{schema MCPToolset}}. An OAuth block under remote has clientId, clientSecret, callbackPort, scopes, and callbackRedirectURL {{schema RemoteOAuthConfig}}.

Keys under permissions

The three keys come from PermissionsConfig {{schema PermissionsConfig}}, and the docs page configuration/permissions gives the pattern grammar.

Keys under hooks

The events come from HooksConfig {{schema HooksConfig}}, and the docs page configuration/hooks explains each one. Every event holds an array. Matcher events hold HookMatcherConfig entries with matcher, hooks (required), and preempt_yolo {{schema HookMatcherConfig}}. The other events hold hook definitions directly.

A hook definition comes from HookDefinition {{schema HookDefinition}}.

The type description names 17 builtins {{schema HookDefinition}}. They are add_context, add_date, add_environment_info, add_prompt_files, add_git_status, add_git_diff, add_directory_listing, add_user_info, add_recent_commits, max_iterations, redact_secrets, transform_json, limit_large_tool_results, safer_shell, http_post, snapshot, and unload.

Keys under runtime, budget, metadata, and evaluators

The docs pages configuration/budget and configuration/flavors explain budget and flavors with examples.

Sources: research/sources/agent-schema.json at tag v1.149.0 (root properties, and the definitions AgentConfig, ModelConfig, ProviderConfig, AuthConfig, FederationAuthConfig, IdentityTokenSourceConfig, Toolset, MCPToolset, Remote, RemoteOAuthConfig, PostEditConfig, ApiConfig, WebhookConfig, RAGConfig, Lifecycle, PermissionsConfig, HooksConfig, HookMatcherConfig, HookDefinition, RuntimeDefaults, BudgetConfig, Metadata, EvaluatorConfig, EvaluatorPolicy, AgentRouting, RoutingPolicy, RoutingRule, FallbackConfig, CacheConfig, CapabilitiesConfig, OutputCapabilitiesConfig, CostConfig, HarnessConfig, InlineSkill, CommandConfig); research/sources/docs-docker-agent.md (pages configuration/overview, configuration/agents, configuration/models, providers/custom, configuration/tools, configuration/permissions, configuration/hooks, configuration/budget, configuration/flavors, configuration/routing); research/sources/README.md (the pin of the schema copy)