Front Matter Reference¶

API reference for Azure Functions agent configuration properties. For examples and detailed usage patterns, see front-matter-spec.md.

Global Configuration (`agents.config.yaml`)¶

Optional file in the root directory. All properties are optional.

Property	Type	Required	Default	Description
`system_tools`	object	No	`{}`	System-level tools configuration. Details
`model`	string	No	Resolved from env/provider	Default LLM model identifier for all agents
`timeout`	number	No	`900`	Default execution timeout in seconds
`tools`	object	No	`{}`	Global tool filtering configuration. Details
`http_auth`	object	No	`function` (per-agent default)	App-wide default inbound HTTP authentication policy inherited by every agent's built-in HTTP endpoints; a per-agent `builtin_endpoints.http_auth` overrides it. Applies only to HTTP endpoints and does not affect MCP. Modes: `function` (default), `admin`, `anonymous`, `entra`.

Global: `system_tools`¶

Property	Type	Required	Default	Description
`dynamic_sessions_code_interpreter`	object	No	`{}`	ACA Dynamic Sessions code interpreter configuration. Details
`web_request`	WebRequestConfig \| boolean	No	`null`	Outbound HTTP request tool configuration. Enabled by default; set to `false` to disable app-wide. Details

Global: `system_tools.dynamic_sessions_code_interpreter`¶

Property	Type	Required	Default	Description
`endpoint`	string	Yes	N/A	ACA session pool endpoint URL. Supports env var substitution.
`client_id`	string	No	`null`	Optional managed identity client ID for multi-identity Function Apps

Global: `system_tools.web_request`¶

Property	Type	Required	Default	Description
`allowed_hosts`	string[]	No	`null`	Exact-match allowlist of hostnames the tool may call. Omit to allow any public host (still subject to the SSRF floor).
`require_https`	boolean	No	`true`	Require `https://` URLs. Set to `false` to also allow `http://`.
`timeout_seconds`	number	No	`null`	Per-request timeout in seconds, clamped to a runtime-defined ceiling (120 s).
`max_response_bytes`	integer	No	`null`	Maximum response body size read before truncating, clamped to a runtime-defined ceiling (10 MB).
`max_request_bytes`	integer	No	`null`	Maximum request body size accepted, clamped to a runtime-defined ceiling (10 MB).

Global: `tools`¶

Property	Type	Required	Default	Description
`exclude`	string[]	No	`[]`	Tool names to exclude globally from all agents

See: Front Matter Spec - Global Configuration

Agent Front Matter (`.agent.md`)¶

YAML front matter at the top of each agent markdown file.

Required Properties¶

Property	Type	Required	Default	Description
`name`	string	Yes	N/A	Display name for the agent. Does not control function name or route.
`description`	string	Yes	N/A	Brief description of the agent's purpose
`trigger`	object	Conditional	N/A	Required unless at least one `builtin_endpoints` value is enabled. Details

Optional Properties¶

Property	Type	Required	Default	Description
`builtin_endpoints`	boolean \| object	No	`false`	Enable built-in chat UI, chat API, and/or MCP tool endpoints. Details
`model`	string	No	Inherited from global	Override LLM model for this agent
`timeout`	number	No	Inherited from global	Override execution timeout (seconds) for this agent
`logger`	boolean	No	`true`	Enable/disable response logging for triggered agents
`substitute_variables`	boolean	No	`true`	Enable/disable environment variable substitution
`system_tools`	object	No	Inherited	Opt out of system tools. Details
`mcp`	boolean \| object	No	`true` (inherit all)	MCP server filtering. Details
`skills`	boolean \| object	No	Inherit all	Skill filtering. Details
`tools`	boolean \| object	No	Inherit all	Custom tool filtering. Details
`workflows`	object	No	`null`	Dynamic Workflow enablement, tool filtering, and Sub Agent grants. Details
`subagents`	list[SubagentRef]	No	`null`	Specialist agents this agent can delegate to as `delegate_<slug>` tools. Details
`input_schema`	object	No	`null`	JSON Schema for HTTP request validation
`response_schema`	object	No	`null`	JSON Schema for response validation
`response_example`	string	No	`null`	Example response structure (multiline string)
`metadata`	object	No	`{}`	Additional metadata for organization. Free-form.

Agent: `trigger`¶

Required unless at least one builtin_endpoints value is enabled. Only one trigger per agent file.

Structure:

trigger:
  type: <trigger_type>
  args: <type_specific_configuration>

Property	Type	Required	Default	Description
`type`	string	Yes	N/A	Trigger type identifier. See Supported Trigger Types
`args`	object	No	`{}`	Type-specific configuration. See Supported Trigger Types

See: Front Matter Spec - trigger, Triggers Reference

Agent: `builtin_endpoints`¶

Enable built-in endpoints for interactive testing, programmatic access, and agent composition.

When set to true: Enables all built-in endpoints (debug_chat_ui, chat_api, mcp)

When set to false: Disables all built-in endpoints (default)

When set to object:

Property	Type	Required	Default	Description
`debug_chat_ui`	boolean	No	`false`	Enable browser-based chat UI at `/agents/{slug}/` plus backing chat APIs
`chat_api`	boolean	No	`false`	Enable REST API endpoints (`/agents/{slug}/chat`, `/agents/{slug}/chatstream`)
`mcp`	boolean	No	`false`	Expose agent as MCP tool on shared runtime MCP transport
`http_auth`	object	No	`{}`	Inbound authentication policy for the HTTP chat API endpoints (chat_api / debug_chat_ui). Applies only to HTTP endpoints and does not affect the MCP endpoint. Modes: function (API key, default), admin (master key), anonymous, entra (Entra ID).

Note: debug_chat_ui: true automatically enables chat_api: true

See: Front Matter Spec - builtin_endpoints

Agent: `system_tools`¶

Opt out of system-level tools configured globally.

Property	Type	Required	Default	Description
`dynamic_sessions_code_interpreter`	boolean	No	`null`	Set to `false` to opt out of code execution capabilities
`web_request`	boolean	No	`null`	Set to `false` to opt out of the default-on `web_request` tool for this agent

See: Front Matter Spec - system_tools

Agent: `mcp`¶

Filter MCP servers discovered from mcp.json.

When set to true or omitted: Inherit all discovered MCP servers (default)

When set to false: Disable all MCP servers for this agent

When set to object:

Property	Type	Required	Default	Description
`exclude`	string[]	No	`[]`	MCP server names to exclude. Must match servers in `mcp.json`.

See: Front Matter Spec - mcp

Agent: `skills`¶

Filter skills auto-discovered from skills/ directory.

When omitted: Inherit all discovered skills (default)

When set to false: Disable all skills for this agent

When set to object:

Property	Type	Required	Default	Description
`exclude`	string[]	No	`[]`	Skill names to exclude. Matched against `SKILL.md` `name` field.

See: Front Matter Spec - skills

Agent: `tools`¶

Filter custom tools auto-discovered from tools/ directory.

When omitted: Inherit all discovered tools (default)

When set to false: Disable all custom tools for this agent

When set to object:

Property	Type	Required	Default	Description
`exclude`	string[]	No	`[]`	Tool names to exclude (in addition to global excludes)

See: Front Matter Spec - tools

Agent: `workflows`¶

Enable Dynamic Workflows, filter workflow tools, and grant leaf specialists.

Property	Type	Required	Default	Description
`enabled`	boolean	No	`false`	Enable Dynamic Workflows for this agent. In v1, only `main.agent.md` is honored.
`exclude`	string[]	No	`[]`	Discovered `@workflow_tool` names to withhold from workflow plans.
`subagents`	object[]	No	`[]`	Independent, deny-by-default leaf-specialist grants. Details

Agent: `workflows.subagents`¶

Each entry is an object. Bare-string shorthand and unknown fields are rejected.

Property	Type	Required	Default	Description
`agent`	string	Yes	N/A	Required specialist identity slug.
`when`	string	No	`null`	Optional model-facing routing hint; defaults to the specialist description.

See: Front Matter Spec - workflows

Supported Trigger Types¶

Each trigger type has a required type field and an optional type-specific args object.

`http_trigger`¶

Property	Type	Required	Default	Description
`route`	string	Yes	N/A	URL path for the HTTP endpoint
`methods`	string[]	No	`["POST"]`	Array of HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
`auth_level`	string	No	`"function"`	One of: `anonymous`, `function`, `admin`

`timer_trigger`¶

Property	Type	Required	Default	Description
`schedule`	string	Yes	N/A	NCRONTAB expression (6 fields or 5 fields with seconds prepended)

`queue_trigger`¶

Property	Type	Required	Default	Description
`queue_name`	string	Yes	N/A	Azure Queue Storage queue name
`connection`	string	Yes	N/A	App setting or setting collection for connection

`blob_trigger`¶

Property	Type	Required	Default	Description
`path`	string	Yes	N/A	Blob path pattern (e.g., `"uploads/{name}.txt"`)
`connection`	string	No	`"AzureWebJobsStorage"`	App setting name for connection string

`event_grid_trigger`¶

No configuration properties. Receives Event Grid events.

`service_bus_queue_trigger`¶

Property	Type	Required	Default	Description
`queue_name`	string	Yes	N/A	Service Bus queue name
`connection`	string	Yes	N/A	App setting or setting collection for connection

`service_bus_topic_trigger`¶

Property	Type	Required	Default	Description
`topic_name`	string	Yes	N/A	Service Bus topic name
`subscription_name`	string	Yes	N/A	Service Bus subscription name
`connection`	string	Yes	N/A	App setting or setting collection for connection

`connector_trigger`¶

No configuration properties. Receives Connector events.

See: Front Matter Spec - trigger, Triggers Reference

Configuration Precedence¶

Runtime Settings (model, timeout)¶

Resolution order (first defined wins): 1. Agent front matter (explicit override) 2. Global agents.config.yaml 3. Environment variables (AZURE_FUNCTIONS_AGENTS_MODEL, AZURE_FUNCTIONS_AGENTS_TIMEOUT_SECONDS) 4. Provider-specific environment variables (for model only) 5. Framework defaults

Capabilities (MCP servers, skills, tools)¶

Discovery: Auto-discovered from mcp.json, skills/, and tools/ directories
Global filtering: Applied from agents.config.yaml (tools only)
Agent filtering: Applied per-agent using exclude lists in front matter

See: Front Matter Spec - Configuration Precedence

Environment Variable Substitution¶

Applies to all string values in agents.config.yaml, mcp.json, and agent .agent.md files (front matter and markdown body).

Supported syntaxes: - $IDENT — e.g., $API_KEY - %IDENT% — e.g., %API_KEY%

Escape sequences: - $$IDENT → literal $IDENT - %%IDENT%% → literal %IDENT%

Identifier rules: Must match [A-Za-z_][A-Za-z0-9_]*

Resolution: os.environ.get(IDENT, original_placeholder). Unset variables remain as literal placeholders.

Disable per-agent: Set substitute_variables: false in agent front matter.

See: Front Matter Spec - Environment Variable Substitution

Validation Rules¶

Required Properties¶

Agent Front Matter: - name (always required) - description (always required) - trigger (required unless at least one builtin_endpoints value is enabled, or the agent is referenced only as an internal specialist via another agent's subagents:)

Global Configuration: - No required properties (entire file is optional)

Key Constraints¶

One trigger per file — Only one trigger can be specified per .agent.md file
Trigger structure — Must have type field; args is optional for triggers with no configuration
CRON expressions — Timer schedules must be valid NCRONTAB (6-field or 5-field with seconds prepended)
HTTP methods — Must be valid HTTP verbs
Auth levels — Must be one of: anonymous, function, admin
JSON Schema validation — input_schema and response_schema must be valid JSON Schema
Exclude lists — MCP server names must match mcp.json entries; tool and skill names are best-effort validated
Subagent references — Every subagents[].agent must name a slug that exists in the app; duplicate and self-references are rejected; the derived delegate_<slug> tool name must not collide with any other tool available to the coordinator

See: Front Matter Spec - Validation Rules

File Naming Conventions¶

Global configuration: agents.config.yaml (root directory)
Agent files: {agent-name}.agent.md (root or agents/ folder)
Skills: skills/{skill-name}/SKILL.md
Custom tools: tools/{tool-name}.py

Function Name Resolution¶

Two identifiers are derived from the agent filename (not from the name field):

Azure Function name — Used for host indexing and admin APIs
Built-in endpoint slug — Used for /agents/{slug}/ routes and MCP tool names

Both identifiers are the same value: the agent's identity slug, also used as the delegate_<slug> tool name generated by another agent's subagents: reference (see subagents).

Sanitization rules: - Start with filename stem (remove .agent.md) - Replace characters outside [A-Za-z0-9_] with _ - Trim leading/trailing underscores - Prefix fn_ if result starts with a digit

Example: daily-report.agent.md → function name daily_report, endpoint slug daily_report

Slugs are globally unique across the app. If two agent files sanitize to the same slug (including a collision between the root directory and agents/), app startup now fails fast with an actionable rename error rather than silently auto-suffixing (_2, _3, ...).

Breaking change (FRD 0007): Earlier versions silently resolved duplicate slugs by appending _2, _3, etc. This is no longer the behavior — rename one of the colliding files (e.g. daily_report_v2.agent.md) so every agent slug is unique.

See: Front Matter Spec - File Naming Conventions

Additional Resources¶

Front Matter Specification — Complete guide with examples and patterns
Triggers Reference — Detailed trigger documentation
Architecture — System design and pipeline stages
Samples — Working examples

Front Matter Reference¶

Global Configuration (agents.config.yaml)¶

Global: system_tools¶

Global: system_tools.dynamic_sessions_code_interpreter¶

Global: system_tools.web_request¶

Global: tools¶

Agent Front Matter (.agent.md)¶

Required Properties¶

Optional Properties¶

Agent: trigger¶

Agent: builtin_endpoints¶

Agent: system_tools¶

Agent: mcp¶

Agent: skills¶

Agent: tools¶

Agent: workflows¶

Agent: workflows.subagents¶

Supported Trigger Types¶

http_trigger¶

timer_trigger¶

queue_trigger¶

blob_trigger¶

event_grid_trigger¶

service_bus_queue_trigger¶

service_bus_topic_trigger¶

connector_trigger¶

Configuration Precedence¶

Runtime Settings (model, timeout)¶

Capabilities (MCP servers, skills, tools)¶

Environment Variable Substitution¶

Validation Rules¶

Required Properties¶

Key Constraints¶

File Naming Conventions¶

Function Name Resolution¶

Additional Resources¶

Global Configuration (`agents.config.yaml`)¶

Global: `system_tools`¶

Global: `system_tools.dynamic_sessions_code_interpreter`¶

Global: `system_tools.web_request`¶

Global: `tools`¶

Agent Front Matter (`.agent.md`)¶

Agent: `trigger`¶

Agent: `builtin_endpoints`¶

Agent: `system_tools`¶

Agent: `mcp`¶

Agent: `skills`¶

Agent: `tools`¶

Agent: `workflows`¶

Agent: `workflows.subagents`¶

`http_trigger`¶

`timer_trigger`¶

`queue_trigger`¶

`blob_trigger`¶

`event_grid_trigger`¶

`service_bus_queue_trigger`¶

`service_bus_topic_trigger`¶

`connector_trigger`¶