Azure Functions hosted skills reference

This article provides the configuration reference for Azure Functions hosted skills. For an overview of the runtime and guidance on when to use it, see Azure Functions hosted skills.

This reference describes version 0.1.0b17 of the azurefunctions-agents-runtime package.

For development examples, see the Azure Functions hosted skills developer guide.

Agent file reference

An agent file (.agent.md) contains YAML front matter for configuration and Markdown instructions.

The runtime discovers agent files in the function app project root and in an agents/ or Agents/ folder. It recognizes *.agent.md and *.claude.md suffixes without regard to case. It also recognizes the bare names agent.md and CLAUDE.md as aliases for main.agent.md. It doesn't recursively scan nested agent folders.

The file name determines the agent's identity slug, function name, and built-in endpoint route segment; the display name doesn't. The runtime replaces characters other than letters, numbers, and underscores with underscores, trims leading and trailing underscores, and prefixes names that start with a number with fn_. For example, daily-report.agent.md becomes daily_report. Slugs must be unique across the app.

Front-matter fields

Use these front matter fields to configure an agent:

An agent can omit both trigger and builtin_endpoints. The runtime keeps the definition in the app's catalog but doesn't register an external invocation surface. You can use the definition through the Hosted Skill binding or a subagent reference.

The configuration schemas reject unknown fields. Put free-form content in metadata or the Markdown instruction body, not in additional front-matter configuration fields.

Agent execution configuration

Use agent_configuration in agents.config.yaml for shared settings, or in agent front matter for an override:

agent_configuration:
  max_output_tokens: 4096

If you omit agent-level agent_configuration, the agent inherits the global value. An empty object ({}) also inherits max_output_tokens. Set max_output_tokens: null to clear the inherited limit, or agent_configuration: null to clear the inherited configuration. The runtime currently supports only max_output_tokens in this configuration.

Subagent references

Each subagents entry must use object form:

subagents:
  - agent: incident_response
    when: Use for incident triage and escalation.

The runtime exposes a delegate_<slug> tool for each reference. Use object form and reference each specialist only once. The runtime rejects self-references, unknown slugs, duplicate references, and collisions with existing tool names. These references are separate from workflows.subagents, which grants access to specialists from dynamic workflows.

Trigger configuration

Each agent file supports one trigger. Define it in the trigger object in the front matter.

Supported trigger types

The following table lists the supported trigger.type values, their required args, and links to the full per-type reference:

Trigger examples

The following examples show common trigger configurations:

• Timer trigger (runs daily at 3:00 PM UTC)

trigger:
  type: timer_trigger
  args:
    schedule: "0 0 15 * * *"

• HTTP trigger

trigger:
  type: http_trigger
  args:
    route: summarize
    http_auth: function

• Queue trigger

trigger:
  type: queue_trigger
  args:
    queue_name: work-items
    connection: AzureWebJobsStorage

• Blob trigger

trigger:
  type: blob_trigger
  args:
    path: uploads/{name}
    connection: AzureWebJobsStorage

App-wide configuration (agents.config.yaml)

Use agents.config.yaml for app-wide runtime defaults that every agent can inherit. The runtime can load an app without this file. Add it when you need shared settings such as a model deployment, timeout, or sandbox execution endpoint.

The runtime also discovers MCP servers from mcp.json, skills from skills/, and custom Python tools from tools/. Agents enable these capabilities by default. Agent front matter can override runtime defaults or filter inherited MCP servers, skills, and tools.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Individual agents can override supported runtime settings in their own front matter.

Configuration fields

Use these top-level fields in agents.config.yaml:

Resolution order

For model selection, see Model precedence. For timeout, the order is agent front matter, agents.config.yaml, AZURE_FUNCTIONS_AGENTS_TIMEOUT_SECONDS, then the runtime default of 900 seconds. String values in agents.config.yaml can reference app settings, such as $AZURE_OPENAI_DEPLOYMENT or $ACA_SESSION_POOL_ENDPOINT.

System tool configuration is app-wide. Agents can opt out but can't supply their own sandbox endpoint or outbound HTTP limits. Setting an agent's system tool override to true doesn't enable a tool that's disabled or unconfigured globally.

Keep model, timeout, and system tool defaults in agents.config.yaml. Keep remote MCP server definitions, including MCP server endpoints from connector namespaces, in mcp.json.

HTTP authentication

The runtime uses the same authentication policy shape for explicitly HTTP-triggered agents and built-in HTTP endpoints:

Use a string such as http_auth: function, or an object with these fields:

For example, this app-wide policy applies to built-in HTTP APIs unless an agent overrides it:

http_auth:
  mode: entra
  entra:
    tenant_id: $AZURE_TENANT_ID
    allowed_audiences:
      - $API_AUDIENCE
    allowed_client_ids:
      - $CALLER_CLIENT_ID

Entra mode requires App Service Authentication in front of the app. The runtime doesn't validate JWTs itself. It checks the principal that the platform validates. If Easy Auth enforcement or a valid Entra principal is missing, the runtime returns 401. If the principal doesn't meet the configured claim restrictions, the runtime returns 403. If you omit an allowlist or leave it empty, the runtime skips only that additional claim check.

The runtime recognizes the platform's WEBSITE_AUTH_ENABLED signal. AZURE_FUNCTIONS_AGENTS_ENTRA_EASY_AUTH is an operator assertion for environments where that signal isn't available; set it only when Easy Auth is actually enforced. It doesn't enable authentication or make a caller-supplied principal header trustworthy on its own.

The debug chat HTML page is anonymous at the Functions key layer; its backing APIs enforce the selected policy. These policies don't change authentication for the MCP extension endpoint.

The legacy trigger.args.auth_level field is deprecated. The runtime accepts its function, admin, and anonymous values without regard to case and logs a warning. If you set both fields, http_auth takes precedence.

Variable substitution

The runtime can substitute app settings and environment variables into string values in agent front matter, agent instruction bodies, agents.config.yaml, and mcp.json.

For substitutions, use either $SETTING_NAME or %SETTING_NAME%. The runtime handles these two formats the same way. Variable names must start with a letter or underscore and can contain letters, numbers, and underscores.

model: $FOUNDRY_MODEL
system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: "%ACA_SESSION_POOL_ENDPOINT%"

Email the summary to $TO_EMAIL.

{
  "servers": {
    "office365": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL"
    }
  }
}

Substitution rules:

• The runtime substitutes variables in string values, including strings nested in objects or lists. It doesn't substitute object keys.
• The runtime doesn't substitute variables in fenced code blocks in agent instruction bodies. Examples can include literal $VALUE or %VALUE% text.
• Use $$SETTING_NAME or %%SETTING_NAME%% for literal placeholders in substituted content.
• The runtime leaves missing variables unchanged. Empty values resolve to empty strings.
• Substitution is a single pass. The runtime doesn't support ${SETTING_NAME} syntax.
• To disable substitution for one agent, set substitute_variables: false in the agent file. This setting doesn't disable substitution in agents.config.yaml or mcp.json.

MCP server configuration (mcp.json)

When an app uses remote MCP servers, add mcp.json to the root of the function app project. The runtime discovers remote HTTP or streamable HTTP MCP servers from this file and makes their tools available to agents, subject to any per-agent filters.

Server entry fields

Use these fields in each servers entry:

If an entry has a missing, empty, or unresolved url, the runtime skips it and logs a warning. Per-agent mcp.exclude filters server names, not individual tools. Use the server entry's tools field to select tools.

Authentication

Use the Azure API Hub scope when the agent consumes a managed MCP server from a connector namespace. Don't store user secrets in mcp.json.

{
  "servers": {
    "office365-outlook": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL",
      "auth": {
        "scope": "https://apihub.azure.com/.default",
        "client_id": "$O365_MCP_CLIENT_ID"
      }
    }
  }
}

The auth.client_id setting selects which managed identity authenticates with the MCP server. Set it to the client ID of a user-assigned managed identity, or omit it to use the identity fallback. The selected identity, or your local developer identity when you run locally, must be allowed to call the MCP server.

Azure connectors

A Connector Namespace hosts connections, triggers, and MCP servers. Use trigger.type: connector_trigger for connector-triggered agents, and add connector MCP server URLs and authentication settings to mcp.json for outbound actions.

For provisioning, authorization, and development examples, see Use connectors in Azure Functions and the hosted skills developer guide.

Skills

Store reusable prompt assets under skills/. They help keep the base agent instructions small while making domain-specific instructions available when needed. The runtime uses the Agent Skills format.

Skill format

The runtime scans skills/ or Skills/ in the function app project root through two child directory levels. It checks the root itself, direct child folders, and their child folders for SKILL.md. Scanning stops at each skill root: a nested SKILL.md beneath an already discovered skill is supporting content, not a separate selectable skill.

skills/
  incident-response/
    SKILL.md
    triage-checklist.md
    escalation-policy.md

The SKILL.md file contains YAML front matter and Markdown instructions.

---
name: incident-response
description: Triage production incidents, summarize impact, and recommend next steps. Use when the task mentions incidents, outages, alerts, or severity levels.
---

Follow the incident response checklist in [triage-checklist.md](triage-checklist.md).

Authoring rules

The runtime discovers skill directories without parsing their front matter. The model SDK validates and loads their contents. For the default Microsoft Agent Framework SDK, follow these rules:

• Every skill folder must contain a SKILL.md file.
• The name and description fields are required.
• Use lowercase letters, numbers, and single hyphens for skill names. Don't use spaces, underscores, uppercase letters, leading hyphens, trailing hyphens, or repeated hyphens.
• The skill name must match its directory name. Use unique names across the app; duplicate-name handling belongs to the SDK, not runtime discovery.
• The description should explain what the skill does and when to use it. The SDK exposes skill metadata before loading full instructions.
• Skills can include supporting resources, assets, and scripts, not only Markdown. Reference supporting files from SKILL.md with relative paths. The default SDK provides helpers for loading skills, reading resources, and running skill scripts.

Only include trusted skill content. Skill script execution isn't the Azure Container Apps sandbox. Use sandboxed execution when code requires that isolation, and custom Python tools for app-specific logic.

Filtering skills per agent

Agents inherit all discovered skills by default. Exclusions match the basename of the directory containing SKILL.md, not a front-matter name parsed by the runtime. Disable or exclude skills in an agent file when a specific agent shouldn't use them:

skills: false

skills:
  exclude:
    - incident-response

Sandboxed execution

For Python code execution, the runtime can use Azure Container Apps dynamic sessions. Dynamic sessions provide isolated environments from session pools. The runtime uses code interpreter sessions to provide an fhs_execute_python tool to agents.

Configuration

Configure sandboxed execution in agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requirements

• The session pool must be a Python code interpreter session pool, such as a pool created with --container-type PythonLTS.
• Set endpoint to a resolved HTTPS session pool management URL with a hostname ending in .dynamicsessions.io. Don't include user credentials in the URL.
• In Azure, the managed identity used by the function app must have the role assignments required to execute code in the session pool. Azure Container Apps code interpreter sessions require the Azure ContainerApps Session Executor and Contributor roles on the session pool.
• When running locally, your developer identity must have the same required access to the session pool.
• To use a user-assigned managed identity for sandboxed execution, set system_tools.dynamic_sessions_code_interpreter.client_id to the client ID of the identity that has the required role assignments. If this setting isn't set, the runtime uses AZURE_CLIENT_ID, then the default credential chain.

The sandbox tool runs Python in an isolated session. Variables, imports, and files can persist across tool calls in the same agent session. When no agent session ID is available, the runtime uses a fresh sandbox session so unrelated executions don't share state.

Disabling per agent

Agents inherit sandboxed execution when it's configured globally. You can disable execution for a specific agent by setting dynamic_sessions_code_interpreter to false in the agent file.

system_tools:
  dynamic_sessions_code_interpreter: false

Setting tools: false also disables sandboxed execution and the web_request system tool.

Outbound HTTP requests

The runtime enables the web_request system tool by default. The tool makes outbound requests to public HTTP(S) hosts without generating sandbox code. Configure it app-wide in agents.config.yaml:

system_tools:
  web_request:
    allowed_hosts:
      - learn.microsoft.com
    require_https: true
    timeout_seconds: 30
    max_response_bytes: 5000000
    max_request_bytes: 1000000

Set system_tools.web_request: false in app-wide configuration to disable the tool for every agent, or in agent front matter to disable it for that agent. Agent front matter accepts only a Boolean override, not a limits object. tools: false also disables it.

Tool request and response

The tool returns a JSON-encoded result with status, url, content_type, redirect_count, response_headers, body, body_truncated, and body_omitted_reason. It parses JSON response bodies when possible and returns text as text. It doesn't return binary bodies; response_bytes reports their size. The tool removes sensitive response headers, including cookies and authentication headers.

The tool doesn't follow redirects. It returns HTTP error statuses and redirects as responses, not transport errors. If a request fails because of a blocked destination, a request-size limit, a timeout, or a transport failure, the result includes an error field. Public-address validation and DNS address pinning always apply, regardless of the configured allowlist.

Custom Python tools

Use custom Python tools when you need app-specific logic that the runtime's built-in capabilities don't cover. Custom tools run in the function app process, not in a sandboxed session.

Tool discovery

Add tool files to the tools/ folder in the function app project root:

tools/
  submit_ticket.py
  lookup_customer.py

The runtime discovers .py files in tools/ whose file names don't start with _. The runtime registers the first supported tool from each file. Use one tool per file to keep discovery predictable.

Defining tools

Define a tool by decorating a function with @tool from the runtime package:

from azure_functions_agents import tool


@tool(name="submit_ticket", description="Create a support ticket with a title and summary.")
async def submit_ticket(title: str, summary: str) -> str:
    return f"Created ticket for {title}: {summary}"

For richer parameter descriptions and validation, use a Pydantic model as the tool schema:

from pydantic import BaseModel, Field
from azure_functions_agents import tool


class LookupCustomerParams(BaseModel):
    customer_id: str = Field(description="Customer identifier from the CRM system.")


@tool(schema=LookupCustomerParams, description="Look up customer details by customer ID.")
async def lookup_customer(params: LookupCustomerParams) -> str:
    return f"Customer details for {params.customer_id}"

You can also define a plain Python function without the decorator. The runtime wraps the first plain function it finds in the file, uses the function name as the tool name, and uses the docstring as the tool description.

def summarize_order(order_id: str) -> str:
    """Summarize an order by order ID."""
    return f"Summary for order {order_id}"

Tool names, descriptions, type hints, and Pydantic field descriptions help the model decide when and how to call the tool. Add any package dependencies used by custom tools to requirements.txt, just as you would for other Python code in an Azure Functions app.

During discovery, the runtime selects decorated tools before plain functions. Define plain functions in the tool module rather than importing them from another module. The runtime loads files during discovery, so module-level code runs in the function app process. If an import fails, the runtime logs the failure and doesn't register the tool from that file.

Filtering tools per agent

Agents inherit discovered custom tools by default. Disable or exclude custom tools in an agent file when a specific agent shouldn't use them:

tools: false

tools:
  exclude:
    - submit_ticket

Model provider configuration

The runtime supports Azure OpenAI, Microsoft Foundry, and OpenAI model providers.

Provider selection

You must configure at least one provider signal for the runtime to create a chat client. You can explicitly set the provider by using the AZURE_FUNCTIONS_AGENTS_PROVIDER setting or let the runtime infer the provider from your other app settings.

Use these provider settings:

When you don't set AZURE_FUNCTIONS_AGENTS_PROVIDER, the runtime auto-detects the provider in this order:

1. AZURE_OPENAI_ENDPOINT selects Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINT selects Microsoft Foundry.
3. OPENAI_API_KEY selects OpenAI.

Provider selection and model selection are separate. Always supply a valid model or deployment name through one of the settings below; auto-detecting a provider doesn't verify that the selected deployment exists.

AZURE_FUNCTIONS_AGENTS_MODEL is a runtime-wide model setting. Its valid values depend on the active provider:

• For Microsoft Foundry, use a model deployment name that exists in the Foundry project.
• For Azure OpenAI, use an Azure OpenAI deployment name. This setting takes precedence over AZURE_OPENAI_DEPLOYMENT for agents loaded from configuration.
• For OpenAI, use the model name accepted by the OpenAI API, such as gpt-4o-mini.

Model precedence

For agents loaded from agent files, model selection follows this order:

1. model in agent front matter.
2. model in agents.config.yaml.
3. AZURE_FUNCTIONS_AGENTS_MODEL.
4. Provider-specific settings, such as AZURE_OPENAI_DEPLOYMENT or FOUNDRY_MODEL.
5. The built-in fallback, gpt-4o-mini.

For Azure providers, the selected value must identify an existing deployment. The fallback doesn't create a deployment, so explicitly configure the model rather than relying on it.

Runtime app settings

In addition to provider and identity settings, the runtime recognizes:

Reasoning settings don't enable reasoning on a model that doesn't support it. Execution timeout doesn't override Azure Functions hosting limits or the HTTP response timeout.

Managed identity configuration

The runtime uses managed identities when connecting to Azure resources that support Microsoft Entra authentication. Use AZURE_CLIENT_ID as the app's default identity selector, or use feature-specific settings for finer control:

1. When you don't configure an identity setting, the runtime uses DefaultAzureCredential, which resolves to the system-assigned managed identity in Azure and your developer identity (Azure CLI or Visual Studio) locally.
2. When you configure an API key in Azure OpenAI (using AZURE_OPENAI_API_KEY), the model provider uses the key instead of a managed identity. For more information about SDK authentication with API keys or Microsoft Entra ID, see Azure OpenAI v1 API authentication.
3. Session history uses the same default host storage identity configuration as the Azure Functions host. Use AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri, and AzureWebJobsStorage__clientId to configure identity-based storage for blob-backed history. The runtime doesn't use a separate agent-specific identity setting for session history. For more information, see Define connections in the Functions developer guide.

Built-in endpoints

The runtime exposes optional built-in endpoints when an agent opts in through the builtin_endpoints settings in its front matter. These endpoints are useful for development, testing, and diagnostics. They're not designed as the primary production application interface.

Enable built-in endpoints in the agent's front matter:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

Setting debug_chat_ui: true also enables the chat and chatstream APIs because the UI depends on them. Set chat_api: true by itself when you want programmatic chat access without the debug UI.

Endpoint routes

The <AGENT_NAME> route segment is the agent's identity slug, not its display name. For example, main.agent.md uses agents/main/.

The following HTTP routes are relative to the extensions.http.routePrefix setting in host.json. The Functions default is api, so agents/main/chat is normally /api/agents/main/chat. Set routePrefix to an empty string to use /agents/main/chat. The MCP extension webhook isn't affected by that prefix.

Workflow-enabled agents also register workflow status routes when chat_api is enabled. For workflow behavior, see Dynamic workflows.

Retrieving keys

Use az functionapp keys list to retrieve host keys. functionKeys.default is the default host function key, masterKey is the master key for admin mode, and systemKeys.mcp_extension is the MCP extension's system key. Supply a key in the x-functions-key header or the code query parameter. Keys aren't a substitute for Entra authentication.

For key retrieval and local development steps, see the developer guide.

Chat API request flow

Both built-in chat APIs expect a JSON object with a prompt field. Set prompt to a string that isn't empty or only whitespace:

{
  "prompt": "Summarize today's failures."
}

Use POST agents/<AGENT_NAME>/chat for one JSON response. The response body includes session_id, response, model, and tool_calls. For a resumable session, the runtime also returns its ID in the x-ms-session-id response header.

The API returns 400 for invalid JSON or an invalid prompt. The prompt must be a string that isn't empty or only whitespace. Chat errors include an error field. Storage errors return 503, and other execution failures return 500.

Use POST agents/<AGENT_NAME>/chatstream for Server-Sent Events (SSE). Each event is a data: frame containing JSON with a type discriminator, not a named SSE event: frame:

data: {"type": "session", "session_id": "<SESSION_ID>"}

data: {"type": "delta", "content": "Summary text"}

data: {"type": "done"}

Event availability depends on the SDK and execution. Clients must handle error even before a session event, and shouldn't infer success from HTTP 200 alone.

To continue a multiturn conversation, send the returned session ID in the x-ms-session-id request header on later chat or chatstream calls. If you omit the header, the runtime starts a new session. Session IDs must match ^[A-Za-z0-9._-]{1,128}$. The runtime rejects invalid IDs rather than using them as storage paths.

POST /api/agents/main/chatstream HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
x-ms-session-id: <SESSION_ID_FROM_A_PREVIOUS_RESPONSE>

{"prompt":"Continue the last summary and add blockers."}

Session history API

Send GET agents/<AGENT_NAME>/history with the x-ms-session-id header to retrieve a stored transcript. The response contains messages and a truncated Boolean. If you omit the session ID, the API returns {"messages": [], "truncated": false}. If you supply an invalid ID, it returns 400. If the selected SDK doesn't support history retrieval, the endpoint returns 501. The API reports history-loading failures as errors, not as a successful empty transcript.

Sessions and state

Multi-turn agent interactions require session history. The default Microsoft Agent Framework SDK chooses storage from configuration, not from whether the app runs locally or in Azure:

Blob history uses the azure-functions-agents container by default. Override the container name with AZURE_FUNCTIONS_AGENTS_SESSION_CONTAINER. History is scoped by agent identity slug and session ID. If configured Blob storage fails, the runtime reports the failure rather than silently switching to local files.

The runtime doesn't require a separate session database. Sandboxed execution is also session-aware: when no explicit session ID is available, the runtime uses a fresh isolated sandbox session so unrelated invocations don't share state.

Supported hosting plans

Azure Functions hosted skills support these Azure Functions hosting plans:

• Flex Consumption
• Premium
• Dedicated (App Service)

For scaling, networking, and timeout limits, see Azure Functions hosting options. Runtime configuration doesn't override hosting-plan limits.

Related content

• Azure Functions hosted skills
• Build an event-driven AI app using Azure Functions hosted skills
• Flex Consumption plan hosting