Azure Functions hosted skills reference

本文提供 Azure Functions 託管技能的設定參考。 關於執行時的概述及何時使用指引，請參閱 Azure Functions 託管技能。

代理程式檔案參考

代理檔（.agent.md）使用 YAML 前端設定代理，接著是 markdown 指令。

前置物質場

利用這些前置欄位來設定代理人：

觸發程式設定

每個代理檔案支援一個觸發器，該觸發器在 trigger 前置物件中定義。

支援的觸發器類型

下表列出支援 trigger.type 的值、所需 args值，以及完整每型別參考的連結：

觸發器範例

以下範例展示了常見的扳機配置：

• 計時器觸發（ 每日 UTC 下午 3：00 運行）

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

• HTTP 觸發器

trigger:
  type: http_trigger
  args:
    route: summarize
    auth_level: FUNCTION

• 佇列觸發程序

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

• Blob 觸發程序

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

應用程式範圍配置（agents.config.yaml）

使用 agents.config.yaml 作為整個應用程式的執行階段預設值，讓每個代理程式都可繼承。 執行時可以載入沒有這個檔案的應用程式。 當你需要共用設定，例如模型部署、逾時或沙盒執行端點時，可以加入它。

這個檔案是一個應用程式層級的輸入。 執行時也會發現來自 mcp.json 的 MCP 伺服器、來自 skills/ 的技能，以及來自 tools/ 的自訂Python工具。 這些功能預設在代理程式上啟用。 代理前端資料可以覆寫執行時預設值，或過濾繼承的 MCP 伺服器、技能與工具。

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

個別 Agent 可以在其自己的前置資料中覆寫支援的執行階段設定。

設定欄位

使用 agents.config.yaml 中的以下頂層欄位：

解決順序

執行時先解析代理前端的值，接著 agents.config.yaml是應用程式設定和執行時預設值。 agents.config.yaml 中的字串值可以參照應用程式設定，例如 $AZURE_OPENAI_DEPLOYMENT 或 $ACA_SESSION_POOL_ENDPOINT。

將模型、超時和系統工具預設值都放在 agents.config.yaml。 請將遠端 MCP 伺服器定義（包括來自連接器命名空間的 MCP 伺服器端點）保留在 mcp.json。

變數替換

執行時可以將應用程式設定和環境變數替換成代理前件、代理指令體agents.config.yamlmcp.json等的字串值。

代入時，請使用 $SETTING_NAME 或 %SETTING_NAME%。 執行時對這兩種格式的處理方式相同。 變數名稱必須以字母或底線開頭，且可包含字母、數字和底線。

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"
    }
  }
}

替換規則：

• 適用於字串值，包括巢狀於物件或清單中的字串。 這不適用於物件鍵。
• 代理指令主體中的圍欄式程式碼區塊不會被代換，因此範例可以包含字面上的 $VALUE 或 %VALUE% 文字。
• 在替代內容中使用 $$SETTING_NAME 或 %%SETTING_NAME%% 用於字面上的佔位符。
• 缺失的變數保持不變。 空值會解析為空字串。
• 替換是一次傳球。 ${SETTING_NAME}語法不被支援。
• 要停用某個代理的替換，請在代理檔中設定 substitute_variables: false 。 此設定不會停用 agents.config.yaml 或 mcp.json 中的替換。

MCP 伺服器配置（mcp.json）

當應用程式使用遠端 MCP 伺服器時，請在函式應用程式專案的根節點中加入 mcp.json 資料。 執行時會從此檔案中發現遠端 HTTP 或可串流的 HTTP MCP 伺服器，並將這些工具提供給代理，但須遵守每個代理的過濾機制。

伺服器輸入欄位

請在每個 servers 條目中使用以下欄位：

Authentication

當代理使用來自連接器命名空間的受控 MCP 伺服器時，請使用 Azure API Hub 範圍。 不要將使用者機密儲存在 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"
      }
    }
  }
}

該 auth.client_id 設定用來選擇哪個受管理身份要向 MCP 伺服器進行驗證。 將其設為使用者指派的受控識別的用戶端 ID。 省略它，改用 Azure 中功能應用程式系統指派的管理身份。 所選的身份，或在本地執行時的本地開發者身份，必須被允許呼叫 MCP 伺服器。

Azure 連接器

連接器讓代理人員能在不需自訂 API 客戶端程式碼的情況下，直接處理外部服務。 例如，Microsoft 365 Outlook連接器可以發送電子郵件，Teams 連接器可以處理訊息，其他連接器則能呼叫 Salesforce、SAP 或 SQL 等系統中的動作。 連接器 命名空間 負責承載連接、觸發器和 MCP 伺服器，讓這些整合功能能提供給你的應用程式。

要在託管技能應用程式中使用連接器功能，首先建立連接器命名空間資源，建立與服務的連線，並授權該連線。 接著選擇任務如何使用該連線：

• 連接器觸發程序會在已連線的服務中發生某些事件時啟動代理，例如收到新電子郵件、Teams 訊息或行事曆事件。 要使用，請在連接器命名空間建立一個觸發器，使用授權連線，然後用該連接器觸發定義中的觸發器名稱和參數配置代理。
• 連接器 MCP 工具 允許代理呼叫服務動作，例如發送電子郵件或更新記錄。 要使用它們，請在連接器命名空間建立一台使用授權連線的 MCP 伺服器，然後將 MCP 伺服器端點加入 mcp.json。

欲了解更多資訊，請參閱 Use connectors in Azure Functions。

Skills

可重複使用的提示素材儲存在 skills/。 它們有助於保持基礎代理指令的規模較小，同時在需要時提供領域專屬指令。 執行時採用 Agent Skills 格式。

技能賽制

執行階段會在函式應用程式專案根目錄中掃描 skills/，並遞迴尋找包含 SKILL.md 的資料夾。

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

該 SKILL.md 檔案包含 YAML 前言，後接著 markdown 指令。

---
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).

撰寫規則

在建立經紀人檔案及其他專案資源時，請遵循以下指引：

• 每個技能資料夾都必須包含一個 SKILL.md 檔案。
• name欄位和description欄位為必填欄位。
• 技能名稱使用小寫字母、數字和單連字號。 不要使用空格、底線、大寫字母、前導連字號、後連字號或重複連字號。
• 技能名稱必須在整個應用程式中是唯一的。
• 描述應該說明技能的作用以及代理人應該何時使用。 執行時會先載入技能名稱和描述，讓代理決定何時載入完整技能。
• 技能可在同一個技能資料夾中包含多個 Markdown 檔案。 使用相對連結，從 SKILL.md 參照支援用的 Markdown 檔案。
• Azure Functions 託管的技能只支援 markdown 檔案作為技能內容。 如果某個技能需要執行行為，就把該程式碼打包成自訂的 Python 工具，並從技能說明中直接稱呼該工具名稱。

每位代理人的篩選技能

代理程式預設會繼承所有已發現的技能。 當特定代理人不應該使用技能時，請在代理人檔案中停用或排除該技能：

skills: false

skills:
  exclude:
    - incident-response

沙盒化執行

對於程式碼執行或瀏覽器自動化，執行時可以使用 Azure 容器應用程式動態會話。 動態會話提供與 會話池隔離的環境。 執行時使用 程式碼直譯器會話 為代理提供 execute_python 工具。

Configuration

在 agents.config.yaml 中設定沙箱執行：

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requirements

• 會話池必須是Python程式碼直譯器會話池，例如以 --container-type PythonLTS 建立的池。
• 這個 endpoint 值是會話池管理端點。
• 在 Azure 中，函式應用程式所使用的管理身份必須有執行會話池程式碼所需的角色指派。 Azure 容器應用程式程式碼解譯器工作階段需要工作階段集區上的 Azure ContainerApps Session Executor 和 Contributor 角色。
• 在本地執行時，你的開發者身份必須擁有相同的會話池存取權。
• 若要使用使用者指派的受管理身份進行沙盒執行，請設定 system_tools.dynamic_sessions_code_interpreter.client_id 為具有所需角色指派的身份的客戶端 ID。 如果未設定此項設定，執行階段會使用 AZURE_CLIENT_ID，然後使用預設認證鏈。

沙盒工具會在隔離的工作階段中執行 Python。 變數、匯入和檔案可以在同一個代理會話中跨工具呼叫持續存在。 當沒有代理會話 ID 可用時，執行時會使用新的沙盒會話，避免無關執行共享狀態。

每個代理者停用

當已全域設定時，代理程式會繼承沙盒執行環境。 你可以在代理檔案中設定 dynamic_sessions_code_interpreter 為 來 false 停用特定代理的執行。

system_tools:
  dynamic_sessions_code_interpreter: false

自訂 Python 工具

當你需要執行時內建功能無法涵蓋的應用程式專用邏輯時，使用自訂的 Python 工具。 自訂工具會執行在函式應用程式的流程中，而不是沙 盒會話中。

工具探索

將工具檔案加入函式應用程式專案根目錄的 tools/ 資料夾：

tools/
  submit_ticket.py
  lookup_customer.py

執行階段會在 .py 中探索檔名不是以 tools/ 開頭的 _ 檔案。 執行時會從每個檔案註冊第一個支援的工具。 每個檔案只用一個工具，讓發現過程可預測。

定義工具

透過使用執行階段套件中的 @tool 裝飾函式來定義工具：

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}"

為了更豐富的參數描述與驗證，請使用Pydantic模型作為工具架構：

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}"

你也可以定義一個簡單的 Python 函式，不用裝飾器。 執行時會將檔案中第一個純函式包裝，使用函式名稱作為工具名稱，並以文件字串作為工具描述。

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

工具名稱、描述、類型提示與皮丹特場描述，幫助模型決定何時以及如何呼叫該工具。 將自訂工具所使用的任何套件相依性新增至 requirements.txt，如同您為 Azure Functions 應用程式中的其他 Python 程式碼所做的那樣。

每個代理的過濾工具

Agent 預設會繼承探索到的自訂工具。 當特定代理不應該使用時，請在代理檔中停用或排除自訂工具：

tools: false

tools:
  exclude:
    - submit_ticket

模型提供者配置

執行環境支援這些模型提供者，包括 Azure OpenAI、Azure AI Foundry 與 OpenAI。

提供者選擇

你必須在執行時設定至少一個提供者訊號，才能建立聊天客戶端。 你可以用設定 AZURE_FUNCTIONS_AGENTS_PROVIDER 明確設定提供者，或讓執行時從其他應用程式設定推斷提供者。

請使用以下提供者設定：

當你未設定 AZURE_FUNCTIONS_AGENTS_PROVIDER時，執行時會自動依照以下順序偵測提供者：

1. AZURE_OPENAI_ENDPOINT選擇 Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINT選擇 Azure AI Foundry。
3. OPENAI_API_KEY 選擇 OpenAI。

當你依賴自動偵測時，識別提供者的醫療提供者特定設定仍需配合該提供者所需的模型設定。 例如，仍然FOUNDRY_PROJECT_ENDPOINT需要 ，且FOUNDRY_MODEL仍然需要 AZURE_OPENAI_ENDPOINTAZURE_OPENAI_DEPLOYMENT。

AZURE_FUNCTIONS_AGENTS_MODEL 是一個執行時範圍的備援模型設定。 其有效值取決於主動提供者：

• 對於 Azure AI Foundry，請使用 Foundry 專案中存在的模型部署名稱，例如 gpt-5.4。
• 對於 Azure OpenAI，只有在你有意想要全執行時的備援時，才使用部署名稱。 大多數應用程式建議改用設定 AZURE_OPENAI_DEPLOYMENT 。
• 對於 OpenAI，請使用 OpenAI API 接受的模型名稱，例如 gpt-4o-mini。

模型優先順序

模型選擇遵循以下一般優先順序：

1. 由代理程式或執行時呼叫所請求的模型。
2. 特定提供者的設定，例如 AZURE_OPENAI_DEPLOYMENT 或 FOUNDRY_MODEL。
3. 模型在 AZURE_FUNCTIONS_AGENTS_MODEL中 集合。
4. 主動提供者內建的預設模式。

受控識別組態

執行環境在連接支援 Microsoft Entra 認證的 Azure 資源時，會使用受管理身份。 可作為 AZURE_CLIENT_ID 應用程式的預設身份選擇器，或使用功能專屬設定以進行更細緻的控制：

1. 當你沒有設定身份設定時，執行時會使用 DefaultAzureCredential，該憑證會解析為 Azure 系統指派的管理身份，以及本地的開發者身份（Azure CLI 或 Visual Studio）。
2. 當你在 Azure OpenAI 中設定 API 金鑰（使用 AZURE_OPENAI_API_KEY），模型提供者會使用該金鑰而非管理身份。 欲了解更多資訊，請參閱 Azure OpenAI 擴充套件 for Azure Functions。
3. Session history 使用與 Azure Functions 主機相同的預設主機儲存身份設定。 使用 AzureWebJobsStorage、AzureWebJobsStorage__blobServiceUri 和 AzureWebJobsStorage__clientId 來設定以身分識別為基礎、適用於以 Blob 為後端之歷程記錄的儲存體。 執行時不會使用獨立的代理專用身份設定來記錄會話歷史。 欲了解更多資訊，請參閱函數開發指南中的 定義連接 。

內建端點

執行時會透過前置設定，當代理選擇加入 builtin_endpoints 時，會揭露可選的內建端點。 這些端點對於開發、測試和診斷都很有用。 它們並非設計為主要的生產應用介面。

在客服的前台啟用內建端點：

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

設定 debug_chat_ui: true 也會啟用 chat 和 chatstream API，因為 UI 依賴它們。 當你想要程式化聊天功能但沒有除錯介面時，可以自動設定 chat_api: true 。

端點路由

<AGENT_NAME>路由區段來自.agent.md檔名，而非顯示name欄位。 例如，main.agent.md 使用 /agents/main/。

取回鑰匙

當你在 Azure 上架聊天介面時，它會在發送訊息前提示輸入功能鍵。 你可以直接呼叫 HTTP 聊天 API 時使用這個金鑰。

請使用以下 az functionapp keys list 指令取得您應用程式的預設函式鍵：

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "functionKeys.default" \
  --output tsv

在這個例子中，將 and <RESOURCE_GROUP> 替換<FUNCTION_APP_NAME>成你的群組名稱和應用程式名稱。 你可以在標頭中包含回傳的金鑰 x-functions-key ，或 code 在 HTTP 請求中加入查詢字串參數。

連接 MCP 用戶端時，請使用以下指令請求 MCP 擴充系統：

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "systemKeys.mcp_extension" \
  --output tsv

MCP 端點需要這個系統金鑰。

聊天 API 請求流程

這兩個內建的聊天 API 都預期 JSON 主體包含以下 prompt 欄位：

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

當你想要一個 JSON 回應時就用 POST /agents/<AGENT_NAME>/chat 它。 回應體包含 session_id、 response、 tool_calls和 。 執行時也會在回應標頭中迴示相同的會話 ID x-ms-session-id 。

當你想要 Server-Sent 事件（SSE）時使用 POST /agents/<AGENT_NAME>/chatstream 。 串流以 session 包含已解析會話 ID 的事件開始，接著是零個或多個 delta、 intermediate、 tool_start和 tool_end 事件，最後以 done 或 error結尾。

若要繼續多回合對話，請將先前回應 x-ms-session-id 的會話 ID 在請求標頭中傳送至 later chat 或 chatstream calls。 如果你省略了那個標頭，執行時會自動建立一個新的工作階段。

POST /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."}

會期與狀態

多回合代理互動需要會話歷史。 執行時會根據環境自動管理會話儲存：

執行時不需另外的會話資料庫。 沙盒執行 同時具備會話感知：當沒有明確的會話 ID 時，執行時會使用一個全新且獨立的沙盒會話，避免無關的調用共享狀態。

支援的主機計畫

Azure Functions 託管技能支援以下 Azure Functions 託管計畫：

所有方案都支援管理身份、虛擬網路整合及應用程式洞察。

相關內容

• Azure Functions hosted skills
• 使用 Azure Functions 託管技能建立事件驅動 AI 應用程式
• 彈性用量方案託管