サーバーレスエージェントのランタイム参照

この記事では、Azure Functionsのサーバーレスエージェントランタイムの設定リファレンスを提供します。 ランタイムの概要と使用時期のガイダンスについては、Azure FunctionsのServerless agents runtimeを参照してください。

エージェント ファイル リファレンス

エージェントファイル(.agent.md)はYAMLフロントマターを使ってエージェントを設定し、その後マークダウン命令を付けます。

フロントマター場

エージェントを構成するには、次のフロント マター フィールドを使用します。

トリガーの構成

各エージェントファイルは、フロントマターの trigger オブジェクトで定義された1つのトリガーをサポートします。

サポートされているトリガーの種類

以下の表は、サポートされる trigger.type 値、必要な args、および型ごとの参照へのリンクを示しています。

トリガーの例

以下の例は一般的なトリガー構成を示しています:

タイマートリガー( 毎日15:00 UTCに実行):

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

ブロブトリガー:

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

アプリ全体の構成(agents.config.yaml)

すべてのエージェントが継承できるアプリ全体のランタイムの既定値には、 agents.config.yaml を使用します。 ランタイムは、このファイルなしでアプリを読み込むことができます。 モデルのデプロイ、タイムアウト、サンドボックス実行エンドポイントなどの共有設定が必要な場合に追加します。

このファイルは、1 つのアプリ レベルの入力です。 ランタイムは、mcp.json から MCP サーバー、skills/ のスキル、および tools/ のカスタム Python ツールも検出します。 これらの機能は、エージェントで既定で有効になっています。 エージェントのフロントマターは、ランタイムの既定値をオーバーライドしたり、継承された MCP サーバー、スキル、ツールをフィルター処理したりできます。

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

個々のエージェントは、サポートされているランタイム設定を独自のフロント マターでオーバーライドできます。

構成フィールド

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.yaml、および mcp.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}構文はサポートされていません。
• 1つのエージェントの置換を無効にするには、エージェントファイルで substitute_variables: false を設定します。 これで置換が agents.config.yaml や mcp.jsonで無効になるわけではありません。

MCPサーバー構成(mcp.json)

アプリでリモート MCP サーバーを使用する場合は、関数アプリ プロジェクトのルートに mcp.json を追加します。 ランタイムは、このファイルからリモート HTTP またはストリーミング可能な HTTP MCP サーバーを検出し、エージェントごとにフィルターを適用して、それらのツールをエージェントで使用できるようにします。

サーバーエントリフィールド

各 servers エントリで次のフィールドを使用します。

認証

エージェントがコネクタ名前空間からマネージド 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 を選択します。 ユーザー割り当てマネージド ID のクライアント ID に設定します。 関数アプリのシステム割り当てマネージド ID をAzureで使用するには省略します。 選択した ID、またはローカルで実行する際のローカル開発者 ID は、MCP サーバーの呼び出しを許可する必要があります。

Azure コネクタ

コネクタを使用すると、エージェントはカスタム API クライアント コードなしで外部サービスを操作できます。 たとえば、Microsoft 365 Outlook コネクタは電子メールを送信でき、Teams コネクタはメッセージを操作でき、他のコネクタは Salesforce、SAP、SQL などのシステムでアクションを呼び出すことができます。 コネクタ名前空間は、それらの統合をアプリで使用できるようにする接続、トリガー、および MCP サーバーをホストします。

サーバーレスエージェントアプリでコネクタ機能を使用するには、まずコネクタネームスペースリソースを作成し、サービスへの接続を作成し、その接続を承認します。 次に、エージェントが接続を使用する方法を選択します。

• コネクタは、 接続されたサービス (新しいメール、Teams メッセージ、予定表イベントなど) で何かが発生したときにエージェントを開始します。 これを使用するには、承認された接続を使用するトリガーをコネクタ名前空間に作成し、そのコネクタ トリガー定義のトリガー名と引数を使用してエージェントを構成します。
• コネクタ MCP ツール を使用すると、エージェントはメールの送信やレコードの更新などのサービス アクションを呼び出すことができます。 それらを使用するには、承認された接続を使用する MCP サーバーをコネクタ名前空間に作成し、MCP サーバー エンドポイントを mcp.jsonに追加します。

詳細については、「Use connectors in Azure Functions」をご覧ください。

スキル

再利用可能なプロンプトアセットを skills/に保存してください。 これらは、必要に応じてドメイン固有の命令を使用できるようにしながら、ベース エージェントの命令を小さく保つのに役立ちます。 ランタイムでは 、エージェント スキル 形式が使用されます。

スキルフォーマット

ランタイムは関数アプリのプロジェクトルート内の skills/ をスキャンし、 SKILL.mdを含むフォルダを再帰的に検出します。

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

SKILL.mdファイルにはYAMLの前面部分とマークダウン命令が続きます。

---
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 フィールドが必要です。
• スキル名は小文字、数字、ハイフンを使いましょう。 スペース、アンダースコア、大文字、先頭のハイフン、末尾のハイフン、繰り返しのハイフンは使用しないでください。
• スキル名は、アプリ全体で一意である必要があります。
• この説明では、スキルの動作と、エージェントがスキルを使用するタイミングの両方について説明する必要があります。 ランタイムは、スキル名と説明を最初に読み込んで、エージェントがスキル全体を読み込むタイミングを決定できるようにします。
• スキルには、同じスキル フォルダーに複数のマークダウン ファイルを含めることができます。 相対リンクを使用して、SKILL.md から補助的なMarkdownファイルを参照します。
• サーバーレスエージェントのランタイムは、スキルコンテンツとしてマークダウンファイルのみをサポートします。 スキルに実行可能な動作が必要な場合は、そのコードをカスタムPythonツールとしてパッケージし、スキルの指示からツール名で参照してください。

エージェントごとのフィルタリングスキル

エージェントは、検出されたすべてのスキルを既定で継承します。 特定のエージェントがスキルを使用しない場合に、エージェント ファイルのスキルを無効または除外します。

skills: false

skills:
  exclude:
    - incident-response

サンドボックス実行

コードの実行またはブラウザーの自動化では、ランタイムは Azure Container Apps 動的セッションを使用できます。 動的セッションは、 セッション プールから分離された環境を提供します。 ランタイムは 、コード インタープリター セッション を使用して、エージェントに execute_python ツールを提供します。

構成

agents.config.yamlでサンドボックス実行を構成します。

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requirements

• セッション プールは、--container-type PythonLTS で作成されたプールなど、Python コード インタープリター セッション プールである必要があります。
• endpoint値は、セッション プール管理エンドポイントです。
• Azureでは、関数アプリが使用する管理IDにはセッションプール内のコードを実行するために必要な役割割り当てが必要です。 Azure Container Apps のコード インタープリター セッションでは、セッション プールに対して Azure ContainerApps Session Executor ロールと Contributor ロールが必要です。
• ローカルで実行する場合、開発者 ID にはセッション プールへの同じ必要なアクセス権が必要です。
• ユーザー割り当てマネージド ID をサンドボックス実行に使用するには、必要なロールの割り当てを持つ ID のクライアント ID に system_tools.dynamic_sessions_code_interpreter.client_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/内の_ファイルを検出します。 現在のプレビューでは、ランタイムは各ファイルからサポートされている最初のツールを登録します。 ファイルごとに 1 つのツールを使用して、検出を予測可能な状態に保ちます。

定義ツール

実行時パッケージの @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関数を定義することもできます。 ランタイムは、ファイル内で見つけた最初のプレーン関数をラップし、関数名をツール名として使用し、ツールの説明として docstring を使用します。

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

ツール名、説明、型ヒント、Pydantic フィールドの説明は、モデルがツールを呼び出すタイミングと方法を決定するのに役立ちます。 Azure Functions アプリの他のPython コードの場合と同様に、カスタム ツールで使用されるパッケージの依存関係を requirements.txt に追加します。

エージェントごとのフィルタリングツール

エージェントは、検出されたカスタム ツールを既定で継承します。 特定のエージェントでカスタム ツールを使用しない場合は、エージェント ファイル内のカスタム ツールを無効または除外します。

tools: false

tools:
  exclude:
    - submit_ticket

モデルプロバイダー構成

ランタイムは、Microsoft Agent Framework を使用してモデル プロバイダーを呼び出します。 プレビュー サポートの対象には、Azure OpenAI、Azure AI Foundry、OpenAI が含まれます。

プロバイダーの選択

チャットクライアントを作成するには、ランタイムで少なくとも1つのプロバイダーシグナルを設定する必要があります。 AZURE_FUNCTIONS_AGENTS_PROVIDER設定を使って明示的にプロバイダーを設定するか、ランタイムで他のアプリ設定からプロバイダーを推測させることもできます。

以下のプロバイダー設定をご利用ください:

AZURE_FUNCTIONS_AGENTS_PROVIDERを設定しない場合、ランタイムは以下の順番でプロバイダーを自動検出します。

1. AZURE_OPENAI_ENDPOINTselects Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINTAzure AI Foundryを選びます。
3. OPENAI_API_KEY OpenAIを選択します。

自動検出に依存する場合、提供者を特定したプロバイダー固有の設定には、プロバイダーが要求するモデル設定を伴う必要があります。 例えば、 FOUNDRY_PROJECT_ENDPOINT はまだ FOUNDRY_MODELが必要で、 AZURE_OPENAI_ENDPOINT はまだまだ AZURE_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. アクティブプロバイダーの組み込みデフォルトモデルです。

マネージド ID の構成

ランタイムは、Microsoft Entra認証をサポートするAzureリソースに接続する際にマネージドIDを使用します。 AZURE_CLIENT_IDをアプリのデフォルトのアイデンティティセレクターとして使うか、機能固有の設定を使って細かい操作を行えます:

1. アイデンティティ設定が設定されていない場合、ランタイムはDefaultAzureCredentialを使い、これはAzureのシステム割り当て管理IDとローカルの開発者ID(Azure CLIまたはVisual Studio)に解決されます。
2. OpenAI Azure(AZURE_OPENAI_API_KEYを用いて)APIキーを設定する際、モデルプロバイダーはマネージドIDではなくキーを使用します。 詳細については、Azure OpenAI拡張 for Azure Functionsをご覧ください。
3. セッション履歴はAzure Functionsホストと同じデフォルトのホストストレージID設定を使用しています。 AzureWebJobsStorage、AzureWebJobsStorage__blobServiceUri、およびAzureWebJobsStorage__clientIdを使用して、BLOB ベースの履歴用に ID ベースのストレージを構成します。 ランタイムは、セッション履歴に個別のエージェント固有の ID 設定を使用しません。 詳細については、Functions開発者ガイドの 「Define connections 」をご覧ください。

組み込みのエンドポイント

ランタイムは、エージェントがフロントマターの builtin_endpoints 設定を通じてオプトインすると、オプションの組み込みエンドポイントを公開します。 これらのエンドポイントは開発、テスト、診断に役立ちます。 これらは主要な本来のアプリケーションインターフェースとして設計されていません。

エージェントのフロントマターで組み込みエンドポイントを有効にする:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

debug_chat_ui: true設定はAPIのAPIをchatとchatstreamも有効にします。なぜならUIはそれらに依存しているからです。 デバッグUIなしでプログラムチャットアクセスをしたいときは、単独で chat_api: true を設定しましょう。

エンドポイント ルート

<AGENT_NAME>ルートセグメントは表示.agent.mdフィールドではなく、nameファイル名から来ています。 たとえば、 main.agent.md は /agents/main/を使用します。

鍵の取得

AzureでチャットUIをホストすると、メッセージを送信する前にファンクションキーの入力を促されます。 HTTPチャットAPIを直接呼び出す際にこのキーを使うことができます。

アプリのデフォルトの関数キーを取得するには、以下の az functionapp keys list コマンドを使ってください:

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

この例では、 <RESOURCE_GROUP> と <FUNCTION_APP_NAME> をグループ名とアプリ名に置き換えます。 返された鍵を x-functions-key ヘッダーに含めたり、HTTPリクエストのエンドポイントに code クエリ文字列パラメータを含めることができます。

MCPクライアントに接続する際は、以下のコマンドを使ってMCP拡張システムにリクエストしてください。

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

MCPエンドポイントはこのシステムキーを必要とします。

チャットAPIリクエストフロー

両方の組み込みチャットAPIは、 prompt フィールド付きのJSONボディを期待しています:

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

JSONレスポンスを1つにしたいときは POST /agents/<AGENT_NAME>/chat を使いましょう。 対応機関には session_id、 response、 tool_callsが含まれます。 ランタイムは x-ms-session-id レスポンスヘッダーで同じセッションIDをエコーします。

Server-Sent イベント(SSE)を使いたいときは POST /agents/<AGENT_NAME>/chatstream を使います。 ストリームは解決されたセッションIDを含む session イベントから始まり、その後に0件以上の delta、 intermediate、 tool_start、 tool_end イベントが続き、最後に done または errorで終わります。

マルチターンの会話を続けるには、後のx-ms-session-idまたはchatコールでchatstreamリクエストヘッダーのセッションIDを送信します。 そのヘッダーを省略すると、ランタイムは自動的に新しいセッションを生成します。

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
• サーバーレスエージェントのランタイムを他のMicrosoftエージェントオプションと比較してください
• Flex 従量課金プランのホスティング