Azure Functions Agents

Azure Functions Agents

Use this skill to build event-driven AI agents on Azure Functions with the Azure Functions serverless agents runtime. This programming model is new, so prefer these patterns over older package README examples.

Current Defaults

• Scaffold with Microsoft Foundry as the model provider.
• Scaffold files may keep gpt-4.1 as the safe Bicep fallback, but before provisioning or

deploying, check the user's subscription/region for the best deployable GPT model and quota.

• Prefer the newest deployable GPT reasoning model with remaining quota when available, such as

gpt-5.4 or newer. Only configure reasoning settings for models known to support them. Older models can fail if AZURE_FUNCTIONS_AGENTS_REASONING_* settings are present.

• For gpt-5.x and other reasoning-capable models, use reasoning effort medium by default,

high when the task needs deeper reasoning or the agent is underthinking, xhigh only when the selected model supports it, and reasoning summary concise.

• If an agent needs web browsing, current public data, browser automation, data analysis, or code

execution, use Azure Container Apps dynamic sessions. Do not write custom web-fetch tools for those cases.

• Use remote HTTP MCP servers and connection MCP servers from mcp.json; local stdio MCP

servers are not supported by the runtime. When the user brings a stdio MCP server, convert the needed actions into Python custom tools or use a hosted remote MCP endpoint.

• Use Connector Namespaces, represented as Microsoft.Web/connectorGateways resources in Bicep.
• Generated apps should include a ready-to-edit src/local.settings.json, not only a template.
• Generated requirements.txt must use the official PyPI package: azurefunctions-agents-runtime.

Progressive References

Load only the files needed for the task:

| Need | Reference | | --- | --- | | Required files and scaffold contents | [project-files.md](./references/project-files.md) | | Agent frontmatter, triggers, built-in endpoints | [agent-files.md](./references/agent-files.md) | | Trigger schemas, connector triggers, built-in endpoint routes | [triggers.md](./references/triggers.md) | | Built-in chat APIs, session IDs, built-in MCP tools | [built-in-endpoints.md](./references/built-in-endpoints.md) | | Local/deployed testing recipes by trigger type | [testing.md](./references/testing.md) | | Foundry model defaults, upgrades, reasoning settings | [models.md](./references/models.md) | | Dynamic sessions for code execution and web browsing | [sessions.md](./references/sessions.md) | | Connector Namespace overview, naming, and safety boundaries | [connectors.md](./references/connectors.md) | | Remote MCP server entries, headers/auth, Connector MCP server configs, authorization, mcp.json, and inspection | [connector-mcp.md](./references/connector-mcp.md) | | Connector operation IDs, schemas, and dynamic parameters | [connector-schemas.md](./references/connector-schemas.md) | | Microsoft Teams connector targets, links, schemas, and troubleshooting smoke tests | [connector-teams.md](./references/connector-teams.md) | | Connector side-effect smoke tests for Teams, Outlook, and MCP tools | [connector-smoke-tests.md](./references/connector-smoke-tests.md) | | Connector-triggered agents and trigger config deployment | [connector-triggers.md](./references/connector-triggers.md) | | Custom Python tools and Agent Skills | [tools-and-skills.md](./references/tools-and-skills.md) | | Writing robust agent instructions | [agent-authoring.md](./references/agent-authoring.md) | | Bicep, azd, deployment, local development | [infra-and-deployment.md](./references/infra-and-deployment.md) | | Azure resource naming abbreviations used by the Bicep assets | [abbreviations.json](./references/abbreviations.json) | | Diagnostics and common failures | [troubleshooting.md](./references/troubleshooting.md) | | Full quickstart app copied into this skill | [quickstart-reference.md](./references/quickstart-reference.md) |

Assess the Workspace

Before editing, inspect the app. Look for:

• src/function_app.py importing create_function_app()
• src/*.agent.md
• src/agents.config.yaml
• src/mcp.json
• src/tools/ and src/skills/
• src/local.settings.json
• infra/main.bicep, infra/app/*.bicep, infra/main.parameters.json
• azure.yaml
• .azure/*/config.json for existing azd environments

For existing apps, read the current files and preserve the app's structure. Current apps should use explicit builtin_endpoints, trigger.args, Foundry provider settings, agents.config.yaml for shared runtime defaults, and Connector Namespace MCP entries in mcp.json.

When inspecting deployed connectors, remember that Connector Namespace resources live under Microsoft.Web/connectorGateways. Connections are connectorGateways//connections, MCP server configs are connectorGateways//mcpserverconfigs, and trigger configs are connectorGateways//triggerconfigs. Do not search for legacy top-level Microsoft.Web/connections to find Connector Namespace connections.

Discuss and Plan the Agent

When the user says they want to create an agent, do not jump straight to files unless the request already contains enough detail. First learn enough to shape the app and discuss a short plan.

Ask only the questions needed to move forward, usually covering:

• Goal: What should the agent accomplish, and what should a successful run produce?
• Invocation: Should it be chat/API-driven, scheduled, event-triggered, connector-triggered,

or some combination?

• Inputs and outputs: What data starts the run, and should the result be returned, logged,

emailed, posted, drafted, stored, or sent somewhere else?

• Interactive surfaces: Does the user want to chat with the agent, expose a chat/API surface,

stream responses, or expose the agent as a built-in MCP tool? Enable built-in endpoints only for those interactive scenarios.

• Tools and services: Does it need web/code execution, Microsoft Learn, Office 365, Teams,

Azure Resource Manager, storage, queues, databases, or custom APIs?

• Teams targets: If the agent needs a Teams team, channel, or chat target, ask the user to

paste a Teams link and parse IDs from it on their behalf. Do not ask them to manually find raw team IDs, channel IDs, or chat IDs. Load [connector-teams.md](./references/connector-teams.md) before wiring Teams posting or diagnosing a missing Teams message.

• Safety boundaries: For actions like email, Teams posts, ticket creation, or resource changes,

should the agent draft, ask for confirmation, or act automatically?

• Model selection: Which Azure subscription and region should be checked for GPT model access

and quota? If the user has not specified them, use the current Azure CLI subscription and the planned AZURE_LOCATION.

• Deployment preference: Default to building and deploying to Azure with azd up, but offer

to run locally first if the user wants a local iteration loop.

Do not ask the user to estimate runtime duration unless the workflow is obviously unusual or may run longer than the standard background-agent defaults. Set practical timeouts yourself: keep simple chat/API agents at the runtime default, set timer, connector-triggered, queue, and other background agents to 30 minutes, and align host.json functionTimeout to the longest agent timeout. For synchronous HTTP work that may take longer than about 230 seconds, choose a background/deferred pattern instead of relying on a longer HTTP response.

Do not add builtin_endpoints or a main.agent.md debug/chat agent just to test a scheduled, timer, connector-triggered, queue, or other background workflow. If the user asks for a chat bot, debug chat UI, chat API, streaming API, or says they want to talk to the agent, enable the appropriate built-in endpoints for that agent or add a separate interactive agent. Otherwise, verify background agents with the admin invoke endpoint and Application Insights.

After the discovery, summarize the plan before editing. Include the agent files, trigger or built-in endpoints, model choice, tools/MCP/connectors, infrastructure changes, and how it will be tested. If the user has already provided enough detail, make reasonable choices and proceed.

Scaffold a New App

Use the complete reference sample at [assets/quickstart-sample](./assets/quickstart-sample) as the safest starting point. Copy it into the target project, then tailor it to the user's agent instead of inventing a project structure from memory.

Baseline structure:

/
  azure.yaml
  infra/
    abbreviations.json
    main.bicep
    main.parameters.json
    app/
      api.bicep
      connector-gateway.bicep
      trigger-config.bicep        # if using connector triggers
      foundry.bicep
      rbac.bicep
      session-pool.bicep
      session-pool-rbac.bicep
  src/
    function_app.py
    host.json
    local.settings.json
    requirements.txt
    .funcignore
    agents.config.yaml
    main.agent.md              # only when the user wants chat/API/MCP endpoints
    .agent.md
    mcp.json

Default scaffold choices:

• Python 3.13 in Bicep.
• Foundry provider. Keep gpt-4.1 in template defaults only as a safe fallback.
• Before running azd provision or azd up, run the model and quota checks in

[models.md](./references/models.md), recommend the best deployable GPT model, and set the FOUNDRY_MODEL, FOUNDRY_MODEL_NAME, FOUNDRY_MODEL_VERSION, FOUNDRY_DEPLOYMENT_CAPACITY, and reasoning env vars when a better reasoning-capable model is selected.

• No reasoning app settings unless the app is explicitly upgraded to a reasoning-capable model.
• ACA dynamic session pool when any agent needs code execution or web browsing.
• Optional Office 365 Outlook connection MCP server when TO_EMAIL is set.
• Built-in endpoints only when the scenario is interactive. Do not add debug chat UI, chat API,

streaming API, built-in MCP, or a general main.agent.md to a scheduled-only/background-only app unless the user asked for that surface.

• Explicit timeout settings: use functionTimeout: "00:30:00" in host.json for background-capable

apps, keep simple chat/API agents at timeout: 900, and set timer, connector-triggered, queue, or other long-running background agents to timeout: 1800 unless the task clearly needs more.

• Connector-triggered apps use the preview extension bundle and a second-step trigger config

deployment after the connector_extension system key exists.

• local.settings.json includes local storage and Foundry/MCP placeholders.

After copying, remove or adjust sample-specific agents and instructions. Keep infrastructure modules only when the app needs them.

Local Development First Rule

Default to deploying new apps to Azure with azd up; these agents are designed for managed identity, Foundry, dynamic sessions, Connector Namespaces, Application Insights, and Functions hosting. Offer to run locally first when the user wants to iterate before deploying, and explain the local tools required.

Local prerequisites:

• Azure Developer CLI (azd)
• Azure Functions Core Tools v4
• Python 3.13+
• Azurite, when using AzureWebJobsStorage=UseDevelopmentStorage=true
• Azure CLI login for local managed-identity-equivalent access

When an app uses Foundry, dynamic sessions, or connector MCP servers, run azd provision before local development. Local func start still calls real Azure resources for model, session pool, and connector operations.

Local loop:

1. azd init
2. azd provision
3. Copy outputs from azd env get-values into src/local.settings.json.
4. Start Azurite with azurite --skipApiVersionCheck.
5. From src, create a venv, install requirements, and run func start.

The scaffolded Bicep grants the deployer/local user access to Foundry and the session pool, and connection access policies when optional connectors are enabled.

Build or Modify Agents

Each .agent.md file defines one agent. Use YAML frontmatter for runtime configuration and markdown for behavior. The file stem becomes the function name and built-in endpoint route segment.

Choose endpoints from the scenario, not from testing convenience. Scheduled-only, timer, connector-triggered, queue, and other background agents should omit builtin_endpoints unless the user asks to talk to that agent, expose it as an API, or expose it as a built-in MCP tool. Use the admin endpoint and Application Insights to test background agents.

Current trigger example:

---
name: Daily Report
description: Sends a daily report.

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

mcp: true
---

Current built-in endpoint example:

---
name: Chat Agent
description: Interactive agent for testing.

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

mcp: false
---

Load [agent-files.md](./references/agent-files.md) before adding less common frontmatter fields.

Model Selection Guidance

For new scaffolds, keep gpt-4.1 as the safe Bicep default, but actively try to select the best deployable GPT model before provisioning. Use az cognitiveservices model list and az cognitiveservices usage list to check the user's subscription, target region, model version, deployment SKU, and quota. See [models.md](./references/models.md) for copyable commands.

Do not silently deploy gpt-4.1 just because it is the template default. Either run the model and quota checks and choose/recommend a better deployable model, or state why the checks could not be run and then use gpt-4.1 without reasoning settings.

Recommend the newest deployable GPT reasoning model with remaining quota. Ask the user to choose when there are meaningful tradeoffs, such as newer/slower/costlier reasoning models versus smaller mini/nano models. If no reasoning-capable model has quota, or if availability/quota discovery cannot determine what the user can deploy, use gpt-4.1 without reasoning settings.

When selecting a reasoning-capable model, confirm reasoning support from the Azure OpenAI reasoning models documentation, then set model and reasoning values together. Use reasoning effort medium by default. Offer high and increased deployment capacity when the task needs deeper reasoning or the deployed agent is underthinking. Use xhigh only when the selected model supports it and the user wants maximum reasoning with possible latency/cost tradeoffs. Use reasoning summary concise.

Deploy and Verify

For new apps, use azd up from the project root. If the user has agreed to deploy, run the deployment commands yourself instead of stopping after printing them. Set required azd env vars, run azd init when needed, run model/quota checks before provisioning, confirm the active Azure subscription, then run azd up with a generous timeout. Pause only for information you genuinely need from the user, such as a missing recipient email, region choice, subscription confirmation, or portal-only connector authorization. Do not route secrets through chat.

Before azd provision or azd up, run az account show --query "{name:name,id:id,tenantId:tenantId}" and show the selected subscription to the user unless they already explicitly named the subscription for this deployment. If it is not the intended subscription, have the user choose or run az account set --subscription before provisioning. Do not deploy to whichever Azure CLI subscription happens to be active without making that choice visible.

Unless the user explicitly asks for continuous deployment, deploy from the local workspace with azd up. Do not create GitHub Actions workflows, CI/CD pipeline files, repository secrets, or run azd pipeline config for a normal app deployment request.

After deployment, verify outputs with azd env get-values, open or provide the rele

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Azure
• Source: Azure/azure-functions-skills
• License: MIT

Install and usage instructions live in the source repository linked above.