Azure Functions がホストするスキルの開発者ガイド

Azure Functions でホストされるスキルは、Azure Functions Python ランタイム上で Markdown ファーストのプログラミング モデルを使用しています。 各ホステッド スキルを .agent.md ファイルで定義します。 YAML フロント マターで構成を設定します。 Markdownのボディはモデルに指示を与えます。

ほとんどの開発作業は、これらの定義とそれらに関連するツールや設定ファイルを変更します。 通常、生成された関数のスタートアップコードを変更する必要はありません。 しかし、アプリは正しいホスト設定、Python依存関係、モデルアクセス、サービス権限が必要です。

Important

Azure Functions Hosted Skillsは現在プレビュー中です。 機能、構成名、およびサポートされているコネクタは、一般公開前に変更される可能性があります。

このガイドはパブリックプレビューパッケージ azurefunctions-agents-runtimeを使用しています。 完全なローカルセットアップをしたいなら、 まずはCanvasのクイックスタートから始めましょう。 Azureリソースを作成しサンプルをデプロイするには、Azure Developer CLIクイックスタートをご利用ください。

Note

.agent.md ファイルは、ホストされているスキルを定義し、これは、イベント発生時に実行されます。 SKILL.mdファイルは再利用可能なスキルを定義し、ホストされたスキルに指示や参考資料を提供します。 これらのファイルには異なる目的があります。

プロジェクト構造

関数アプリのプロジェクトルートには以下の構造を用いてください。 オプションファイルはアプリが必要な時だけ追加してください。

<project_root>/
├── function_app.py
├── host.json
├── requirements.txt
├── local.settings.json
├── summarize.agent.md
├── agents.config.yaml
├── mcp.json
├── skills/
│   └── report-writing/
│       ├── SKILL.md
│       ├── references/
│       │   └── report-format.md
│       └── assets/
│           └── example-report.md
└── tools/
    └── get_policy.py
ファイルまたはフォルダー Purpose
function_app.py Functionsアプリを作成し、ランタイムのディスカバリーを開始します。
host.json 拡張バンドルや関数のタイムアウトなどのAzure Functionsホストオプションを設定します。
requirements.txt ホストされているスキルランタイムやその他のPython依存関係を一覧にしています。
local.settings.json ローカルアプリの設定を保持します。 このファイルにシークレットをコミットしないでください。
summarize.agent.md ホストされたスキル、そのトリガー、指示を定義します。
agents.config.yaml アプリ全体に適用される任意のランタイム既定値。
mcp.json オプションのリモートMCPサーバー定義
skills/ オプションの再利用可能なスキルとMarkdownリソース。
tools/ オプションのカスタムPythonツール。

function_app.pyのスタートアップコードは以下のように非常に小さくできます:

from azure_functions_agents import create_function_app

app = create_function_app()

Functionsホストがアプリを読み込む際に、ランタイムはホストされたスキルとその構成済みの機能を発見します。 スタータープロジェクトのホストファイルと依存ファイルは保持してください。 標準のPythonアプリファイルについては、Python開発者ガイドをご覧ください。

ホストスキルを定義する

プロジェクトのルートに summarize.agent.md を作成してください:

---
name: Request summary
description: Summarize a request and identify missing information.
trigger:
  type: http_trigger
  args:
    route: summarize
    methods: [POST]
    http_auth: function
builtin_endpoints:
  debug_chat_ui: true
  http_auth: function
---

Summarize the request supplied in the HTTP request body.

Return these sections:

- Summary: State the purpose of the request.
- Missing information: List the facts needed to complete the request.
- Questions: Ask specific questions for the missing facts.

Use only the supplied facts. Do not invent names, dates, or approvals.
If the request is empty or unclear, explain what information is needed.

この定義は summarize ルート上のHTTP POSTリクエストを受け入れます。 Azureでは、http_auth: functionは関数キーまたはホストキーを必要とします。 標準的なFunctionsルートプレフィックスは apiなので、通常は /api/summarizeルートです。 デプロイ済みの認証を確認するためにローカルテストを使わないでください。 詳細については、 HTTPトリガー認可を参照してください。

ファイル名はホストされたスキルの識別情報を示します。 summarize.agent.mdでは、生成されたAzure関数名はsummarizeであり、組み込みのエンドポイントルートセグメントはsummarizeです。 nameフィールドは表示名です。 そのフィールドを変更しても関数の名前が変更されるわけではありません。 この例のように、明示的なHTTP route を指定すると、HTTP トリガー ルートを設定します。

builtin_endpointsブロックはチャットウィンドウとその関連するチャットAPIをローカルテストに利用できるようにします。 利用可能なエンドポイントや認証設定については、 組み込みエンドポイントを参照してください。

明確な指示を書き込む

目標、入力、使うべきツール、そして必要な出力を述べてください。 データが欠落したり、ツールが故障した場合にどうすればよいかを説明してください。 ホストされたスキルが取ってはいけない行動を指定します。

指示は認可制御ではありません。 コードやアクションを実行するサービスにおいて、正確なビジネスルール、権限、必要な承認を検証してください。 例えば、「承認済みのレポートのみを送信してください」というプロンプトは、レポートを送信するツールの承認チェックの代わりにはなりません。

共有デフォルトとオーバーライドの設定

agents.config.yaml で共有モデルとタイムアウトの既定値を設定します。

model: $FOUNDRY_MODEL
timeout: 900

FOUNDRY_MODEL を設定済みのプロバイダーで利用可能なモデル デプロイに設定してください。 Foundryアプリの完全な設定例については、「 ローカル設定の設定」を参照してください。 その他のプロバイダーについては、 モデルプロバイダー構成を参照してください。

ホストされたスキルが異なる設定を必要とする場合、agents.config.yaml で定義されたデフォルトに対するサポートされているオーバーライドをフロント マターに追加します:

timeout: 120
mcp:
  exclude:
    - office365-outlook
skills: false

この例では、ランタイムのタイムアウトを 120 秒に設定し、MCP サーバーを 1 つ削除し、このホストされたスキルの再利用可能なスキルを無効化します。 除外されたサーバー名は mcp.jsonのキーと一致しなければなりません。

$SETTING_NAME を使って、対応する文字列値にアプリの設定を挿入します。 例えば、model: $FOUNDRY_MODEL はモデル設定を読み取ります。 この構文はシェル式の完全な構文ではありません。 置換規則については 変数置換を参照してください。

トリガーをセットする

イベントで始まる各 .agent.md ファイルで、明示的なトリガーを 1 つ使用します。 HTTPリクエストの代わりにAzure Storageキューメッセージを処理するには、triggerブロックを置き換えてください:

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

また、手順をHTTPリクエスト本体の代わりにキューメッセージ入力を記述するように変更してください。

connection値はアプリ設定名またはアイデンティティベースの設定コレクションのプレフィックスであり、埋め込まれた秘密ではありません。 ストレージ接続と権限は別々に設定してください。 詳細については、 Queue trigger connectionsをご覧ください。

イベント ソースのトリガーを選択してください:

イベントソース Use
HTTP 要求 リクエストとレスポンスに対する http_trigger。
Schedule タイマー スケジュールが設定されている timer_trigger。
キューまたはサービス バス 作業項目のキューやメッセージトリガーです。
ブロブまたはデータベースの変更 ストレージやデータベースサービスのトリガーです。
外部サービス イベント コネクら イベント ソースが構成されている connector_trigger。

完全なリストと必要な引数については、サポートされているトリガータイプを参照してください。

オプションの内蔵チャットおよびMCPエンドポイントは明示的トリガーとは別です。 詳細は 組み込みエンドポイント をご覧ください。 mcp.json のリモート MCP サーバー定義は、ホストされているスキルを MCP サーバーとして公開しません。

MCPサーバーに接続してください

他のサービスが必要なツールをすでに提供している場合は、リモートMCPサーバーを使いましょう。 関数アプリのプロジェクトのルートに mcp.json を追加します:

{
  "servers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

ランタイムはリモート http および streamable-http トランスポートをサポートします。 ローカルstdio またはコマンドベースの MCP サーバーを起動しません。

ホストされたスキルは、除外しない限り発見されたMCPサーバーを継承します。 サーバーをホストスキルから除外するには、mcp.excludeファイル内で.agent.mdを定義してください。 サーバーを特定のツールに限定するには、tools内のそのエントリにmcp.json配列を追加します。 そのサーバーで公開されている正確なツール名を使ってください。 この選択はサーバーの定義にも適用されます。

Microsoft Entra認証の場合は、auth.scopeをサーバーのトークンスコープに設定してください。 また、ユーザー割り当てのマネージド ID を選択するように auth.client_id を設定することもできます。 選択したアイデンティティはサーバーを呼び出す権限を持っている必要があります。 mcp.json にシークレットを保存しないでください。 詳細は MCPサーバー設定をご覧ください。

ホスト実行は非インタラクティブです。 このアイデンティティベースの構成は、自動的にインタラクティブなユーザーOAuthフローを実行しません。 ビジネスサービスが委任されたユーザー認可を必要とする場合は、サポートされているコネクタとそのマネージド接続を検討してください。 コネクターがサービスの必要な認可モデルに対応しているか確認してください。 「Azure コネクタを使用する」を参照してください。

スキルに関する指示を再利用する

複数のホストされているスキルに必要なガイダンス、またはすべてのリクエストで必要ではない参考資料には、再利用可能なスキルを使用します。

skills/report-writing/SKILL.mdを作成します。

---
name: report-writing
description: Write a review report from supplied facts. Use when a task requests a review report.
---

Read [the report format](references/report-format.md) before you write.
Use [the example report](assets/example-report.md) as a format example,
not as a source of facts.

State the result, the supporting facts, and the questions that remain.
If required facts are missing, list them. Do not invent a result.

references/report-format.mdでは、必要なレポートセクションを定義します。 assets/example-report.md では、フォーマットを示すサンプル レポートを記載します。

スキルの name は、report-writing など、格納されているディレクトリに一致していなければなりません。 ランタイムは検索用にスキル名や説明を提供し、必要に応じて完全な命令やリソースを読み込みます。 ホストされるスキルが読み込みタイミングを把握できるように、SKILL.md でサポートするリソースを記載します。

各スキルは、skills/ 直下にある独自のフォルダに保存します。 執筆ガイドラインについては、「スキル」を参照してください。

スキルファイルは実行可能ツールを自動的に登録しません。 実行動作には設定済みのツールを使いましょう。 スキル内のスクリプトがモデルに許可や実行方法を与えると決めつけないでください。

ツールを追加する

まず、要件を満たす場合はリモートのMCPツールやランタイムシステムツールを使いましょう。 アプリ固有のロジック用にカスタムPythonツールを追加しましょう。

ランタイムシステムツール

ランタイムでは web_request システムツールがデフォルトで有効になっています。 パブリックウェブアドレスへのアウトバウンドリクエストを行います。 HTTPSはデフォルトで必須です。 リクエストを特定のホスト名に制限するには、以下の設定を agents.config.yaml に追加します:

system_tools:
  web_request:
    allowed_hosts:
      - example.com

system_tools.web_request: false を設定すると、アプリ全体または 1 つのホストされるスキルに対してツールを無効にできます。 許可リストは宛先を制限します。 サービスの利用や機密データの送信の許可を与えるものではありません。

孤立した Python 実行のために、Azure Container Apps dynamic sessions の Python コード インタープリター プールを構成してください:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

ACA_SESSION_POOL_ENDPOINTをプールの管理エンドポイントに設定してください。 使用前にアプリのアイデンティティに必要なプール権限を付与してください。 識別設定や要件については、 サンドボックス実行を参照してください。

カスタム Python ツール

tools/get_policy.pyを作成します。

from azure_functions_agents import tool


@tool
def get_policy_version() -> str:
    """Return the version of the sample review policy."""
    return "2026-10"

.py配下のtools/ファイルごとに、公開ツールを1つ使う。 ランタイムは各ファイル内で最初に見つけたサポート済みの通常ツールを登録します。 タイプヒントと明確なドキュメントストリングを使い、モデルがツールの目的や入力を理解できるようにします。 必要なパッケージをrequirements.txtに追加してください。

カスタムPythonツールはFunctions Pythonワーカーで動作します。 サンドボックス内で自動的に隔離されるわけではありません。 入力の検証、権限の適用、失敗の報告を明示的に行います。 外部状態を変えるツールについては、例えば冪等キーを使うなどして、繰り返し呼び出しを安全にします。

Durable ワークフロー ツールは別の @workflow_tool コントラクトを使用します。 そのモデルについては 「動的ワークフロー」を参照してください。

設定を管理

ローカル設定は自動的にAzureアプリの設定にコピーされません。 両方の環境を設定してください。 Gitに秘密情報を含めないでください。サポートされている場合はマネージド ID を使用し、引き続き必要な認証情報には適切なシークレット ストレージを使用しましょう。 ローカル設定を確認し、アプリ設定を管理してください。

ホストされたスキルの timeout と Functions ホストの functionTimeout は別々の制限です。 ワークロードに合わせて両方を設定しましょう。 ホストスキルのタイムアウトは、ホスティングプランの制限やHTTP応答の制限を上書きしません。 関数アプリのタイムアウト時間を参照してください。

Azure コネクタを使用する

Azureコネクターを使用すると、ホストされたスキルは、カスタム クライアントや認証コードを使用せずに、認可された外部操作を呼び出し、サービス イベントを受け取ることができます。 この節では、コネクタリソースがすでに存在することを前提としています。

MCPサーバーとその接続を設定するには、MCP サーバー コネクタを作成するをご覧ください。

既存の Microsoft 365 Outlook MCP サーバーについて、mcp.json にエントリを追加してください:

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

ローカルまたはAzureアプリの設定でO365_MCP_SERVER_URLをデプロイ済みサーバーエンドポイントに設定してください。 関数アプリのIDにそのMCPサーバーへのアクセス権を付与します。 ユーザー割り当ての管理 ID を選択するには、そのクライアント ID と共に auth.client_id を追加してください。

両方の認可境界を設定してください:

限界値 必要な構成
Function app to connector MCP server アプリのアイデンティティにはMCPサーバーを呼び出す権限が必要です。
外部サービスへのコネクタ接続 接続は、上流ユーザーまたはサービス、および必要な操作について承認されている必要があります。

一方の境界での許可は、もう一方の境界にも許可を与えるわけではありません。 接続の承認が自動的にホストされたスキルの各呼び出し元の ID になるわけではありません。

コネクタ イベントからホストされるスキルを開始するには、まず、接続を作成して認証します。 次に、このトリガー ブロックを .agent.md ファイルで使用します:

trigger:
  type: connector_trigger

また、上流イベント、コールバックルーティング、コールバック認証もコネクターネームスペースで設定する必要があります。 mcp.jsonのサーバー定義はイベントにサブスクライブしません。 拡張要件やイベント設定については、「Azure Functionsで管理コネクターを使う」をご覧ください。

ローカルで実行する

Azure Functions Core Toolsを使ってパソコンでアプリを起動してください。 また、Python 3.13以降の環境とモデル展開へのアクセスも必要です。

ローカル設定を構成する

関数アプリのプロジェクトのルートで local.settings.json を作成します。 FoundryモデルとローカルAzure Storageの場合は、以下の構造を用いてください:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "AZURE_FUNCTIONS_AGENTS_PROVIDER": "foundry",
    "FOUNDRY_PROJECT_ENDPOINT": "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
    "FOUNDRY_MODEL": "<model-deployment-name>"
  }
}

エンドポイントとモデルのプレースホルダーをデプロイメントの値に置き換えてください。 Foundryプロジェクトに存在するモデルデプロイメントを使い、ローカルの開発者IDにそのモデルデプロイメントへのアクセス権を与えましょう。 MCPサーバー、ツール、トリガーで使っている設定も追加してください。 ソース管理に local.settings.json を含めないでください。

互換性のあるエミュレーターが利用可能であれば、データソースとしてエミュレーターを使用してください。 たとえば、Azurite は、ローカル Blob、Queue、Table Storage を提供します。 UseDevelopmentStorage=trueを使うときは、Functionsホストの前にAzuriteを起動してください。 Service Busについては、Service Busエミュレーターを参照してください。

コネクターの名前空間、接続、コネクターMCPサーバーには実際のAzureリソースが必要です。 ローカル実行でもそれらのリソースを呼び出します。 モデルコールやAzure Container Appsの動的セッションも設定済みのサービスを利用し、料金が発生することがあります。

機能ホストを起動する

Pythonローカル開発ガイドに記載されている通り、Python仮想環境を作成・有効化してください。 関数アプリのプロジェクト ルートで、requirements.txt からパッケージをインストールします:

python -m pip install -r requirements.txt

Foundryでアイデンティティベースのアクセスがある場合は、モデルを使用する権限を持つアイデンティティでサインインしてください:

az login

同じディレクトリからホストを起動します:

func start

ホストは summarize 関数と例で有効化された組み込みエンドポイントを一覧にします。 デフォルトの api ルートプレフィックスとポート 7071の場合、出力は以下に似ています:

Functions:

    agent_summarize_builtin_chat: [POST] http://localhost:7071/api/agents/summarize/chat

    agent_summarize_builtin_chatstream: [POST] http://localhost:7071/api/agents/summarize/chatstream

    agent_summarize_builtin_chat_page: [GET] http://localhost:7071/api/agents/summarize/

    agent_summarize_builtin_history: [GET] http://localhost:7071/api/agents/summarize/history

    summarize: [POST] http://localhost:7071/api/summarize

テスト中はホストを稼働させ続けてください。 端末出力で設定エラーや登録された関数 URL を確認します。 詳細については、「ローカル関数を実行する」を参照してください。

チャットウィンドウでテストしてください

summarize.agent.md例はすでに内蔵のチャットウィンドウとそのバックエンドのチャットAPIを有効にしています。

host.json がデフォルトの http://localhost:7071/api/agents/summarize/ ルート プレフィックスを使用する場合は、ブラウザーで api を開いてください。 もしスタータープロジェクトが extensions.http.routePrefix を空文字列に設定しているなら、代わりに http://localhost:7071/agents/summarize/ を使いましょう。 7071と異なる場合は実際のホストポートを使ってください。

サンプルリクエストを入力し、送信し、応答とホストログを確認します。 例えば、ホストされたスキルに配達日が記載されていないリクエストを要約してもらうように頼みます。 回答が欠落した日付を特定しているか確認し、捏造していないか確認してください。 また、入力漏れやツールの故障もテストしてください。

ローカルコアツールの実行は通常、ファンクションキーチェックをスキップします。 定義にはhttp_auth: functionを残し、Azureで認証は別途テストしてください。 デプロイ済みチャット ウィンドウの場合、プロンプトが表示されたら Function キーを入力します。 デバッグエンドポイントは必要な場所のみ有効にしてください。 ルートとキー取得については、 組み込みエンドポイントを参照してください。

Azure にデプロイ

プロジェクトのデプロイ方法を選択してください:

Method Guidance
Bicepテンプレートを用いたサンプル ホストされたスキルサンプルリポジトリを使用してください。 そのインフラテンプレートが必要なリソースを作成します。 Azure Developer CLIクイックスタートに従って、azd upの設定と実行を行ってください。
Azure Functions Hosted Skills Canvas キャンバスを使ってアプリを作成・テストし、「Azureにデプロイ」を選択してください。 ホストされているスキルキャンバスのクイックスタートをご覧ください。
Azure Functions Skills Azure Functions Skills をインストールします。 azure-functions-hosted-skills作成用スキルを使用すると、コーディング エージェントがアプリを作成し、デプロイの準備を行うことができます。 コーディングエージェントにアプリのデプロイを依頼し、提案されたリソース、権限、コストを確認してからデプロイを承認してください。

展開後、Azureアプリの設定に必要な設定値が含まれていること、アプリの ID がモデルやツールにアクセスできること、各コネクタ接続が承認されていることを確認しましょう。 本番データを使う前に、デプロイ済みトリガーとその認証を制御されたリクエストでテストしてください。

エンドツーエンド サンプルを模索する

これらのサンプルを使って、ホストされたスキルがトリガー、ツール、Azure サービスを完全なアプリでどのように組み合わせるかを確認してください。 各リポジトリにはセットアップおよび展開手順が含まれています。

Sample それが示す内容
保険契約の確認 キューメッセージから永続ワークフローを開始し、文書を並列で確認し、レポートを Blob Storage に保存して人間が確認できるようにします。
経費処理プロセッサー キューから経費を処理し、コネクタMCPサーバーを通じてポリシー文書を読み取り、結果を出力キューにルーティングします。 モデルコールはAzure API Management AIゲートウェイを使用します。
日次ブログ概要 チャットトリガーやタイマートリガーを使って、Azure Container Appsの動的セッションのコード インタープリターでブログ記事を要約しましょう。 必要に応じて、Microsoft 365 Outlookコネクターを通じて要約を送信することも可能です。

関連するコンテンツ

  • 最終更新: