Help us improve
Share bugs, ideas, or general feedback.
Build, scaffold, extend, deploy, and troubleshoot event-driven AI agents and scheduled serverless agent apps on Azure Functions using azurefunctions-agents-runtime. Use when the user wants a scheduled agent, morning briefing, daily digest, timer agent, inbox summary, email or Teams briefing, background AI workflow, connector-triggered agent, event-driven AI automation, HTTP/chat agent, webhook-style agent, or Azure Functions hosted agent.
npx claudepluginhub azure/azure-functions-skills --plugin azure-functions-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/azure-functions-skills:azure-functions-agents Describe the agent, trigger, tools, model needs, and deployment targetDescribe the agent, trigger, tools, model needs, and deployment targetThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to build event-driven AI agents on Azure Functions with the Azure Functions
Guides technical evaluation of code review feedback: read fully, restate for understanding, verify against codebase, respond with reasoning or pushback before implementing.
Share bugs, ideas, or general feedback.
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.
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.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.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.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.Microsoft.Web/connectorGateways resources in Bicep.src/local.settings.json, not only a template.requirements.txt must use the official PyPI package: azurefunctions-agents-runtime.Load only the files needed for the task:
| Need | Reference |
|---|---|
| Required files and scaffold contents | project-files.md |
| Agent frontmatter, triggers, built-in endpoints | agent-files.md |
| Trigger schemas, connector triggers, built-in endpoint routes | triggers.md |
| Built-in chat APIs, session IDs, built-in MCP tools | built-in-endpoints.md |
| Local/deployed testing recipes by trigger type | testing.md |
| Foundry model defaults, upgrades, reasoning settings | models.md |
| Dynamic sessions for code execution and web browsing | sessions.md |
| Connector Namespace overview, naming, and safety boundaries | connectors.md |
Remote MCP server entries, headers/auth, Connector MCP server configs, authorization, mcp.json, and inspection | connector-mcp.md |
| Connector operation IDs, schemas, and dynamic parameters | connector-schemas.md |
| Microsoft Teams connector targets, links, schemas, and troubleshooting smoke tests | connector-teams.md |
| Connector side-effect smoke tests for Teams, Outlook, and MCP tools | connector-smoke-tests.md |
| Connector-triggered agents and trigger config deployment | connector-triggers.md |
| Custom Python tools and Agent Skills | tools-and-skills.md |
| Writing robust agent instructions | agent-authoring.md |
| Bicep, azd, deployment, local development | infra-and-deployment.md |
| Azure resource naming abbreviations used by the Bicep assets | abbreviations.json |
| Diagnostics and common failures | troubleshooting.md |
| Full quickstart app copied into this skill | quickstart-reference.md |
Before editing, inspect the app. Look for:
src/function_app.py importing create_function_app()src/*.agent.mdsrc/agents.config.yamlsrc/mcp.jsonsrc/tools/ and src/skills/src/local.settings.jsoninfra/main.bicep, infra/app/*.bicep, infra/main.parameters.jsonazure.yaml.azure/*/config.json for existing azd environmentsFor 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/<gateway>/connections, MCP
server configs are connectorGateways/<gateway>/mcpserverconfigs, and trigger configs are
connectorGateways/<gateway>/triggerconfigs. Do not search for legacy top-level
Microsoft.Web/connections to find Connector Namespace connections.
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:
AZURE_LOCATION.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.
Use the complete reference sample at 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:
<project-root>/
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-name>.agent.md
mcp.json
Default scaffold choices:
gpt-4.1 in template defaults only as a safe fallback.azd provision or azd up, run the model and quota checks in
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.TO_EMAIL is set.main.agent.md to a scheduled-only/background-only app
unless the user asked for that surface.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_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.
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:
azd)AzureWebJobsStorage=UseDevelopmentStorage=trueWhen 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:
azd initazd provisionazd env get-values into src/local.settings.json.azurite --skipApiVersionCheck.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.
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 before adding less common frontmatter fields.
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 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.
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 <subscription-id> 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 relevant app URL,
show the user how to get the default function key only when built-in chat UI/API endpoints are
present, open Connector Namespace authorization links when connectors are present, check
connection status, and run a smoke test when practical. For timer or other non-HTTP agents,
manually trigger the function with the admin endpoint after deployment, then query Application
Insights requests, traces, and exceptions for that run. For built-in chat agents, open or provide
the /agents/<slug>/ URL and call the chat API if useful. Do not rely on az functionapp log tail
for Flex Consumption agent diagnostics.
When a manual trigger starts a timer/background agent, tell the user what to expect before waiting:
the admin endpoint often returns 202 Accepted, the agent may run for several minutes, and
Application Insights can lag. Give short progress updates while checking telemetry, especially for
runs that take 5-10 minutes. If telemetry does not appear after a reasonable wait, or the function
appears stuck past its expected duration, say so and switch to troubleshooting instead of silently
waiting or repeatedly triggering the function.
For connector actions with visible side effects, such as Teams posts or Outlook messages, verify the downstream side effect after the first run. If the user reports it is missing, do not keep triggering the agent. Inspect the recorded tool result/session and run a focused connector smoke test with the same arguments before changing model settings or rerunning the full workflow.
Be hands-on after scaffolding. Do not stop at a command list when the next command is safe and the
user already approved the direction. Run azd up, open authorization URLs, run azd env get-values, test deployed endpoints, and report the results. Stop only for user-only actions such
as signing in to authorize a connector, selecting an ambiguous option, or entering secrets.
When creating backing Azure resources beyond this skill's bundled Bicep, use Azure docs. If the
agent needs searchable docs context, ask the user to connect the Microsoft Learn MCP server at
https://learn.microsoft.com/api/mcp.
Useful endpoints:
/agents/<agent-file-stem>/POST /agents/<agent-file-stem>/chatPOST /agents/<agent-file-stem>/chatstream/runtime/webhooks/mcpPOST /admin/functions/<agent-file-stem>