Serverless-Agents-Laufzeitreferenz

Dieser Artikel liefert die Konfigurationsreferenz für die Serverless-Agents-Laufzeit von Azure Functions. Für einen Überblick über die Laufzeit und Anleitungen, wann sie verwendet werden sollte, siehe Serverless agents runtime in Azure Functions.

Important

Die Serverless-Agents-Laufzeit befindet sich derzeit in der Vorschau. Features, Konfigurationsnamen und unterstützte Connectors können sich vor der allgemeinen Verfügbarkeit ändern.

Agent-Dateireferenz

Eine Agentendatei (.agent.md) verwendet YAML-Frontmaterial, um den Agenten zu konfigurieren, gefolgt von Markdown-Anweisungen.

Frontmateriefelder

Verwenden Sie diese Front-Matter-Felder, um einen Agent zu konfigurieren:

Feld Erforderlich Beschreibung
name Ja Anzeigename für den Agenten.
description Ja Kurze Beschreibung, was der Agent tut und wann es verwendet werden soll.
trigger Ja (außer builtin_endpoints aktiviert) Definiert, wie der Agent aufgerufen wird. Pro Agentdatei ist nur ein Trigger zulässig.
builtin_endpoints No Aktiviert integrierte Debug- und Kompositionsendpunkte. Verwenden Sie true, um alle integrierten Endpunkte zu aktivieren, oder konfigurieren Sie debug_chat_ui, chat_api und mcp einzeln. debug_chat_ui: true außerdem ermöglicht es die Backing- chat und chatstreamEndpunktrouten , da die integrierte Benutzeroberfläche diese APIs aufruft.
input_schema No JSON-Schema zur Validierung von HTTP-Anforderungstexten für HTTP-ausgelöste Agenten.
logger No Steuert, ob die Laufzeitprotokollierung für den Agent aktiviert ist. Wird standardmäßig auf true festgelegt.
mcp No Steuert den Zugriff auf MCP-Server, die von mcp.json erkannt werden. Verwenden Sie false, um MCP-Server für diesen Agenten zu deaktivieren, oder verwenden Sie exclude, um bestimmte Server zu entfernen.
metadata No Benutzerdefinierte Metadaten für Ihre Organisation oder Werkzeuge.
model No Überschreibt das in agents.config.yaml oder in den App-Einstellungen konfigurierte Standardmodell.
response_example No Beispiel-Antwortschema, das zur Steuerung strukturierter Antworten von HTTP-ausgelösten Agenten verwendet wird.
response_schema No JSON-Schema, das verwendet wird, um strukturierte Antworten zu überprüfen, die von HTTP-ausgelösten Agents zurückgegeben werden.
skills No Kontrolliert den Zugang zu entdeckten Fähigkeiten. Verwenden Sie false, um Fähigkeiten für diesen Agenten zu deaktivieren, oder verwenden Sie exclude, um bestimmte Fähigkeiten zu entfernen.
substitute_variables No Kontrolliert, ob die Substitution von Umweltvariablen auf die Frontmaterie und die Anweisungen angewendet wird. Wird standardmäßig auf true festgelegt.
system_tools No Ermöglicht es einem Agenten, sich von konfigurierten Systemwerkzeugen wie Sandbox-Ausführung abzumelden.
timeout No Überschreibt das standardmäßige Ausführungszeitlimit in Sekunden.
tools No Kontrolliert den Zugriff auf entdeckte benutzerdefinierte Python-Tools. Verwenden Sie false, um benutzerdefinierte Tools für diesen Agent zu deaktivieren, oder exclude, um bestimmte Tools zu entfernen.

Triggerkonfiguration

Jede Agentendatei unterstützt einen Trigger, der im trigger Objekt im Front-Matter definiert ist.

Feld Erforderlich Beschreibung
type Ja Der Abzugsbindungstyp. Siehe die Tabelle der unterstützten Typen für erlaubte Werte.
args Abhängig vom Typ Trigger-spezifische Einstellungen, die konfigurieren, welches Ereignis den Agenten startet.

Unterstützte Triggertypen

Die folgende Tabelle listet die unterstützten trigger.type Werte, deren erforderliche argsWerte und Links zur vollständigen Referenz pro Typ auf:

trigger.type Erforderlich args Reference
http_trigger route HTTP-Trigger
timer_trigger schedule Timertrigger
queue_trigger queue_name, connection Warteschlangentrigger
blob_trigger path, connection Blobtrigger
event_grid_trigger (kein) Event Grid-Trigger
event_hub_message_trigger event_hub_name, connection Event Hub Trigger
service_bus_queue_trigger queue_name, connection Service Bus Warteschlangen-Trigger
service_bus_topic_trigger topic_name, subscription_name, connection Service Bus-Themen-Trigger
cosmos_db_trigger connection, database_name, container_name Cosmos DB-Trigger
cosmos_db_trigger_v3 database_name, collection_name, connection_string_setting Cosmos DB Trigger v3
sql_trigger table_name, connection_string_setting SQL-Trigger
mysql_trigger table_name, connection_string_setting MySQL Trigger
kafka_trigger topic, broker_list Kafka-Auslöser
dapr_binding_trigger binding_name Dapr-Bindungstrigger
dapr_service_invocation_trigger method_name Dapr-Dienstaufruf-Trigger
dapr_topic_trigger pub_sub_name, topic Dapr-Thema-Auslöser
generic_trigger type (Bindungstypname) Generischer Auslöser
connector_trigger Konfiguriert im Connector-Namensraum. Steckverbinder-Trigger

Trigger-Beispiele

Die folgenden Beispiele zeigen gängige Auslöserkonfigurationen:

Timer-Auslöser (läuft täglich um 15:00 Uhr UTC):

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

HTTP-Trigger:

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

Warteschlangen-Auslöser:

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

Blob-Auslöser:

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

App-weite Konfiguration (agents.config.yaml)

Verwenden Sie agents.config.yaml für app-weite Standardwerte für die Laufzeit, die von jedem Agenten geerbt werden können. Die Laufzeit kann eine App ohne diese Datei laden. Fügen Sie sie hinzu, wenn Sie gemeinsame Einstellungen wie eine Modellbereitstellung, ein Timeout oder einen Sandbox-Ausführungsendpunkt benötigen.

Diese Datei ist eine Eingabe auf App-Ebene. Die Laufzeit erkennt außerdem MCP-Server von mcp.json, Skills von skills/ und benutzerdefinierte Python-Tools von tools/. Diese Funktionen sind standardmäßig für Agents aktiviert. Das Front Matter des Agent kann die Standardeinstellungen der Runtime überschreiben oder geerbte MCP-Server, Skills und Tools filtern.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Einzelne Agents können unterstützte Laufzeiteinstellungen in ihrer eigenen Front-Matter außer Kraft setzen.

Konfigurationsfelder

Verwenden Sie diese Felder auf oberster Ebene in agents.config.yaml:

Feld Erforderlich Beschreibung
model No Standardmodell oder Modellbereitstellung, die von Agents verwendet wird, die model nicht in ihrem eigenen Front Matter festlegen.
timeout No Standardausführungstimeout in Sekunden. Der Standardwert für die Laufzeit beträgt 900 Sekunden.
system_tools.dynamic_sessions_code_interpreter.endpoint Bei Verwendung der Sandkastenausführung Verwaltungsendpunkt für den dynamischen Sitzungspool Azure Container Apps, der von Sandkastentools verwendet wird.
system_tools.dynamic_sessions_code_interpreter.client_id No Client-ID der verwalteten Identität, die zum Aufrufen des Sitzungspools verwendet wird.
tools.exclude No Globale Ausschlussliste für benutzerdefinierte Python Tools, die aus dem Ordner tools/ ermittelt wurden.

Reihenfolge der Auflösung

Die Laufzeit löst Werte zuerst aus dem Frontmatter des Agents auf, dann aus agents.config.yaml sowie aus App-Einstellungen und den Standardwerten der Laufzeit. Zeichenfolgenwerte in agents.config.yaml können auf Appeinstellungen verweisen, wie $AZURE_OPENAI_DEPLOYMENT oder $ACA_SESSION_POOL_ENDPOINT.

Modell-, Timeout- und Standardwerte für Systemtools in agents.config.yaml beibehalten. Speichern Sie Definitionen für Remote-MCP-Server, einschließlich MCP-Serverendpunkten aus Connector-Namespaces, in mcp.json.

Variablenersetzung

Die Runtime kann App-Einstellungen und Umgebungsvariablen durch Zeichenfolgen im Front Matter, im Body der Agents, agents.config.yaml und mcp.json ersetzen.

Für Substitutionen kann man entweder $SETTING_NAME oder %SETTING_NAME%verwenden, die von der Laufzeit auf die gleiche Weise behandelt werden. Variablennamen müssen mit einem Buchstaben oder Unterstrich beginnen und können Buchstaben, Zahlen und Unterstriche enthalten.

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

Substitutionsregeln:

  • Gilt für String-Werte, einschließlich Strings, die in Objekten oder Listen verschachtelt sind. Gilt nicht für Objektschlüssel.
  • Abgegrenzte Codeblöcke in Anweisungstexten für Agenten werden nicht ersetzt, sodass Beispiele den Literaltext $VALUE oder %VALUE% enthalten können.
  • Verwendung $$SETTING_NAME oder %%SETTING_NAME%% für wörtliche Platzhalter in ersetzten Inhalten.
  • Fehlende Variablen bleiben unverändert. Leere Werte lösen sich auf leere Strings auf.
  • Die Auswechslung ist ein Einzelpass. Die ${SETTING_NAME} Syntax wird nicht unterstützt.
  • Um die Substitution für einen Agenten zu deaktivieren, setze substitute_variables: false sie in der Agent-Datei. Das schaltet die Substitution in agents.config.yaml oder mcp.jsonnicht aus.

MCP-Serverkonfiguration (mcp.json)

Wenn eine App Remote-MCP-Server verwendet, fügen Sie mcp.json dem Stammverzeichnis des Funktions-App-Projekts hinzu. Die Laufzeit erkennt entfernte HTTP- oder per HTTP streambare MCP-Server aus dieser Datei und stellt deren Werkzeuge Agenten zur Verfügung, vorbehaltlich etwaiger agentenspezifischer Filter.

Server-Eingabefelder

Verwenden Sie diese Felder in jedem servers Eintrag:

Feld Erforderlich Beschreibung
type Ja Verwenden Sie http oder streamable-http. Lokale stdio MCP-Server werden von der Laufzeit nicht unterstützt.
url Ja Remote-MCP-Serverendpunkt. Die Ersetzung von Umgebungsvariablen wird unterstützt.
headers No Statische Header für einen generischen Remote-MCP-Server. Speichern Sie keine statischen Geheimschlüssel in mcp.json.
auth.scope Bei Verwendung der Microsoft Entra-Authentifizierung Microsoft Entra Tokenbereich, der zum Authentifizieren von Aufrufen an den MCP-Server verwendet wird.
auth.client_id No Client-ID der verwalteten Identität, die beim Authentifizieren mit diesem MCP-Server verwendet werden soll. Lassen Sie dieses Feld aus, um die vom System zugewiesene verwaltete Identität der Funktions-App in Azure zu verwenden.

Authentication

Verwenden Sie den Azure API Hub-Bereich, wenn der Agent einen verwalteten MCP-Server aus einem Connectornamespace nutzt. Speichern Sie keine geheimen Benutzerschlüssel in 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"
      }
    }
  }
}

Die auth.client_id Einstellung wählt aus, welche verwaltete Identität beim MCP-Server authentifiziert wird. Legen Sie sie auf die Client-ID einer vom Benutzer zugewiesenen verwalteten Identität fest. Lassen Sie sie aus, um die vom System zugewiesene verwaltete Identität der Funktions-App in Azure zu verwenden. Die ausgewählte Identität oder Ihre lokale Entwickleridentität bei lokaler Ausführung müssen den MCP-Server aufrufen dürfen.

Azure-Konnektoren

Connectors ermöglichen Agents das Arbeiten mit externen Diensten ohne benutzerdefinierten API-Clientcode. Beispielsweise kann ein Microsoft 365 Outlook Connector E-Mails senden, ein Teams-Connector kann mit Nachrichten arbeiten, und andere Connectors können Aktionen in Systemen wie Salesforce, SAP oder SQL aufrufen. Ein Connectornamespace hostet die Verbindungen, Trigger und MCP-Server, die diese Integrationen für Ihre App verfügbar machen.

Um Connector-Fähigkeiten in einer serverlosen Agenten-App zu nutzen, erstellen Sie zunächst eine Connector Namespace-Ressource, stellen Sie eine Verbindung zum Service her und autorisieren Sie diese Verbindung. Wählen Sie dann aus, wie der Agent die Verbindung verwendet:

  • Connectorauslöser starten Agents, wenn in einem verbundenen Dienst etwas passiert, z. B. eine neue E-Mail, eine Teams-Nachricht oder ein Kalenderereignis. Um einen zu verwenden, erstellen Sie einen Trigger im Connector-Namespace, der die autorisierte Verbindung verwendet, und konfigurieren Sie dann den Agent mit dem Triggernamen und den Argumenten aus dieser Connectortriggerdefinition.
  • Connector MCP-Tools ermöglichen es Agenten, Dienstaktionen aufzurufen, beispielsweise E-Mails zu senden oder einen Datensatz zu aktualisieren. Um sie zu verwenden, erstellen Sie einen MCP-Server im Connector-Namespace, der die autorisierte Verbindung verwendet, und fügen Sie dann den MCP-Serverendpunkt hinzu mcp.json.

Weitere Informationen finden Sie unter Use Connectors in Azure Functions.

Fähigkeiten

Speichern wiederverwendbare Prompt-Assets unter skills/. Sie helfen dabei, die Basis-Agent-Anweisungen klein zu halten, während sie bei Bedarf domänenspezifische Anweisungen zur Verfügung stellen. Die Laufzeitumgebung verwendet das Agent Skills-Format.

Fertigkeitsformat

Die Laufzeit durchsucht skills/ im Stammverzeichnis des Function-App-Projekts und sucht rekursiv nach Ordnern, die SKILL.md enthalten.

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

Die SKILL.md Datei enthält YAML-Frontmaterial gefolgt von Markdown-Anweisungen.

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

Autorenregeln

Befolgen Sie diese Richtlinien beim Erstellen Ihrer Agentendateien und anderer Projektressourcen:

  • Jeder Qualifikationsordner muss eine SKILL.md Datei enthalten.
  • Die Felder name und description sind erforderlich.
  • Verwenden Sie Kleinbuchstaben, Zahlen und einzelne Bindestriche für Fertigkeitsnamen. Verwenden Sie keine Leerzeichen, Unterstriche, Großbuchstaben, führende Bindestriche, nachfolgende Bindestriche oder wiederholte Bindestriche.
  • Qualifikationsnamen müssen in der gesamten App eindeutig sein.
  • Die Beschreibung sollte sowohl erklären, was die Fähigkeit tut als auch wann der Agent es verwenden sollte. Die Laufzeit lädt zuerst Qualifikationsnamen und Beschreibungen, damit der Agent entscheiden kann, wann die volle Fähigkeit geladen werden soll.
  • Fähigkeiten können mehrere Markdowndateien im selben Qualifikationsordner enthalten. Verweisen Sie von SKILL.md aus mithilfe relativer Links auf zugehörige Markdown-Dateien.
  • Die Laufzeitumgebung für serverlose Agents unterstützt nur Markdown-Dateien als Inhalte für Skills. Wenn eine Fähigkeit ein ausführbares Verhalten benötigt, paketiere diesen Code als benutzerdefiniertes Python-Tool und beziehe dich auf das Tool mit Namen aus den Skill-Anweisungen.

Filterfähigkeiten pro Agent

Agents erben standardmäßig alle ermittelten Fähigkeiten. Deaktivieren oder Ausschließen von Fähigkeiten in einer Agentdatei, wenn ein bestimmter Agent sie nicht verwenden sollte:

skills: false
skills:
  exclude:
    - incident-response

Ausführung in einer Sandbox

Für die Codeausführung oder Browserautomatisierung kann die Laufzeit Azure Container Apps dynamische Sitzungen verwenden. Dynamische Sitzungen stellen isolierte Umgebungen aus Sitzungspools bereit. Die Laufzeit verwendet Code-Interpreter-Sitzungen, um Agenten ein execute_python-Tool bereitzustellen.

Konfiguration

Konfigurieren der Sandkastenausführung in agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Anforderungen

  • Der Sitzungspool muss ein Sitzungspool für den Python-Code-Interpreter sein, beispielsweise ein mit --container-type PythonLTS erstellter Pool.
  • Der endpoint Wert ist der Sitzungspoolverwaltungsendpunkt.
  • In Azure muss die verwaltete Identität, die von der Funktionsanwendung verwendet wird, die Rollenzuweisungen haben, die erforderlich sind, um Code im Session Pool auszuführen. Azure Container Apps Code-Interpreter-Sitzungen erfordern die Rollen Azure ContainerApps Session Executor und Contributor für den Sitzungspool.
  • Wenn Sie lokal ausgeführt werden, muss Ihre Entwickleridentität über den gleichen erforderlichen Zugriff auf den Sitzungspool verfügen.
  • Wenn Sie eine vom Benutzer zugewiesene verwaltete Identität für die Sandkastenausführung verwenden möchten, legen Sie diese auf die Client-ID der Identität fest system_tools.dynamic_sessions_code_interpreter.client_id , die über die erforderlichen Rollenzuweisungen verfügt. Wenn diese Einstellung nicht festgelegt ist, verwendet die Laufzeit AZURE_CLIENT_ID, dann die Standard-Anmeldeinformationskette.

Das Sandbox-Tool führt Python in einer isolierten Sitzung aus. Variablen, Importe und Dateien können über Toolaufrufe in derselben Agentsitzung hinweg beibehalten werden. Wenn keine Agenten-Sitzungs-ID verfügbar ist, verwendet die Laufzeit eine neue Sandbox-Sitzung, damit unabhängige Ausführungen keinen Zustand gemeinsam nutzen.

Deaktivierung pro Agent

Agenten erben die Ausführung in einer Sandbox, wenn diese global konfiguriert ist. Du kannst die Ausführung für einen bestimmten Agenten deaktivieren, indem du in der Agentendatei einstellst dynamic_sessions_code_interpreterfalse .

system_tools:
  dynamic_sessions_code_interpreter: false

Benutzerdefinierte Python-Tools

Nutze benutzerdefinierte Python-Tools, wenn du app-spezifische Logik brauchst, die die eingebauten Funktionen der Laufzeit nicht abdecken. Benutzerdefinierte Tools laufen im Funktions-App-Prozess, nicht in einer Sandbox-Sitzung.

Werkzeugentdeckung

Hinzufügen von Tooldateien zum tools/ Ordner im Stammverzeichnis des Funktions-App-Projekts:

tools/
  submit_ticket.py
  lookup_customer.py

Die Laufzeit findet die .py Dateien in tools/, deren Dateinamen nicht mit _ beginnen. In der aktuellen Vorschau registriert die Laufzeit das erste unterstützte Tool aus jeder Datei. Verwenden Sie ein Tool pro Datei, um die Ermittlung vorhersagbar zu halten.

Definition von Werkzeugen

Definiere ein Werkzeug, indem du eine Funktion mit @tool aus dem Laufzeitpaket dekorierst:

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

Verwenden Sie für umfangreichere Parameterbeschreibungen und Validierung ein Pydantisches Modell als Toolschema:

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

Sie können auch eine einfache Python-Funktion ohne den Dekorator definieren. Die Laufzeit umschließt die erste einfache Funktion, die sie in der Datei findet, verwendet den Funktionsnamen als Toolnamen und verwendet die Docstring als Toolbeschreibung.

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

Toolnamen, Beschreibungen, Typhinweise und Pydantische Feldbeschreibungen helfen dem Modell zu entscheiden, wann und wie das Tool aufgerufen werden soll. Fügen Sie alle Paketabhängigkeiten, die von benutzerdefinierten Tools verwendet werden, zu requirements.txt hinzu, so wie bei anderem Python-Code in einer Azure Functions-App.

Filterwerkzeuge pro Agent

Agents übernehmen standardmäßig erkannte benutzerdefinierte Tools. Deaktivieren oder Ausschließen von benutzerdefinierten Tools in einer Agentdatei, wenn ein bestimmter Agent sie nicht verwenden sollte:

tools: false
tools:
  exclude:
    - submit_ticket

Konfiguration des Modellanbieters

Die Laufzeit verwendet Microsoft Agent Framework zum Aufruf von Modellanbietern. Die Vorschauunterstützung umfasst Azure OpenAI, Azure AI Foundry und OpenAI.

Anbieterauswahl

Sie müssen mindestens ein Provider-Signal für die Laufzeit konfigurieren, um einen Chat-Client zu erstellen. Du kannst den Anbieter explizit mit der Einstellung AZURE_FUNCTIONS_AGENTS_PROVIDER festlegen oder die Laufzeit den Anbieter aus deinen anderen App-Einstellungen ableiten lassen.

Verwenden Sie diese Anbieter-Einstellungen:

Provider AZURE_FUNCTIONS_AGENTS_PROVIDER Wert Erforderliche Einstellungen Optionale Einstellungen Verhalten der Modellsetzung
Azure AI Foundry foundry FOUNDRY_PROJECT_ENDPOINT AZURE_CLIENT_ID Wenn du eine benutzerdefinierte verwaltete Identität möchtest Setze FOUNDRY_MODEL den Modell-Deployment-Namen, den das Foundry-Projekt verwenden sollte.
Azure OpenAI azure_openai AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT AZURE_OPENAI_API_KEY, AZURE_OPENAI_API_VERSION, AZURE_CLIENT_ID wenn man eine benutzerdefinierte verwaltete Identität möchte Setzen AZURE_OPENAI_DEPLOYMENT Sie auf den Azure OpenAI Deployment-Namen.
OpenAI openai OPENAI_API_KEY None Setze AZURE_FUNCTIONS_AGENTS_MODEL auf den OpenAI-Modellnamen, wenn du ein Modell nicht in der Agenten- oder Laufzeitkonfiguration passierst.

Wenn Sie nicht setzen AZURE_FUNCTIONS_AGENTS_PROVIDER, erkennt die Laufzeit den Anbieter automatisch in folgender Reihenfolge:

  1. AZURE_OPENAI_ENDPOINTselects Azure OpenAI.
  2. FOUNDRY_PROJECT_ENDPOINTwählt Azure AI Foundry .
  3. OPENAI_API_KEY wählt OpenAI aus.

Wenn Sie sich auf die automatische Erkennung verlassen, muss die anbieterspezifische Einstellung, die den Anbieter identifiziert hat, weiterhin von der vom Anbieter benötigten Modelleinstellung begleitet werden. Zum Beispiel braucht FOUNDRY_PROJECT_ENDPOINTFOUNDRY_MODELnoch , und AZURE_OPENAI_ENDPOINT braucht AZURE_OPENAI_DEPLOYMENTweiterhin .

AZURE_FUNCTIONS_AGENTS_MODEL ist ein runtime-weites Fallback-Modellsetting. Seine gültigen Werte hängen vom aktiven Anbieter ab:

  • Für Azure AI Foundry verwenden Sie einen Modell-Deployment-Namen, der im Foundry-Projekt existiert, zum Beispiel gpt-5.4.
  • Für Azure OpenAI verwenden Sie den Bereitstellungsnamen nur, wenn Sie absichtlich das Runtime-weite Fallback wollen. In den meisten Apps setzen Sie AZURE_OPENAI_DEPLOYMENT stattdessen ein.
  • Für OpenAI verwenden Sie den Modellnamen, der von der OpenAI-API akzeptiert wird, wie zum Beispiel gpt-4o-mini.

Modellrangfolge

Die Modellauswahl verwendet diese allgemeine Rangfolge:

  1. Das vom Agenten oder Runtime-Aufruf angeforderte Modell.
  2. Anbieterspezifische Einstellungen, wie z. B. AZURE_OPENAI_DEPLOYMENT oder FOUNDRY_MODEL.
  3. Das Modell setzt in AZURE_FUNCTIONS_AGENTS_MODEL.
  4. Das eingebaute Standardmodell des aktiven Anbieters.

Konfiguration der verwalteten Identität

Die Laufzeit verwendet verwaltete Identitäten, wenn sie sich mit Azure-Ressourcen verbindet, die Microsoft Entra-Authentifizierung unterstützen. Nutzen Sie AZURE_CLIENT_ID sie als Standard-Identitätswahl der App oder nutzen Sie funktionsspezifische Einstellungen für eine feinere Steuerung:

Laufzeitfunktion Identitätseinstellungen Rückfall1
Azure OpenAI model provider2 AZURE_CLIENT_ID DefaultAzureCredential
Azure AI Foundry Modellanbieter AZURE_CLIENT_ID DefaultAzureCredential
Azure Container Apps-Sandbox für dynamische Sitzungen system_tools.dynamic_sessions_code_interpreter.client_id AZURE_CLIENT_ID, dann DefaultAzureCredential
MCP-Server, die in Connectornamespaces gehostet werden Der auth.client_id Wert im Servereintrag in mcp.json AZURE_CLIENT_ID, dann DefaultAzureCredential
Blob-gestützte Sitzungshistorie3 AzureWebJobsStorage__clientId AZURE_CLIENT_ID, dann DefaultAzureCredential
  1. Wenn keine Identitätseinstellung konfiguriert ist, verwendet die Laufzeitumgebung DefaultAzureCredential, das sich auf die systemzugewiesene verwaltete Identität in Azure und Ihre Entwickleridentität (Azure CLI oder Visual Studio) lokal auflöst.
  2. Wenn ein API-Schlüssel in Azure OpenAI konfiguriert wird (mit AZURE_OPENAI_API_KEY), verwendet der Modellanbieter den Schlüssel anstelle einer verwalteten Identität. Weitere Informationen finden Sie unter Azure OpenAI Erweiterung für Azure Functions.
  3. Die Sitzungshistorie verwendet dieselbe Standardkonfiguration der Speicher-Identität des Hosts wie der Azure Functions-Host. Verwenden Sie AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri und AzureWebJobsStorage__clientId, um identitätsbasierten Speicher für den Blob-gestützten Verlauf zu konfigurieren. Die Laufzeit verwendet keine separate agentspezifische Identitätseinstellung für den Sitzungsverlauf. Weitere Informationen finden Sie unter Verbindungen definieren im Funktions-Entwicklerleitfaden.

Integrierte Endpunkte

Die Laufzeit stellt optionale eingebaute Endpunkte frei, wenn ein Agent sich über die builtin_endpoints Einstellungen in seinem Front-Matter anmeldet. Diese Endpunkte sind nützlich für Entwicklung, Tests und Diagnostik. Sie sind nicht als primäre Produktionsanwendungsschnittstelle konzipiert.

Aktivieren Sie eingebaute Endpunkte in der Frontmaterie des Agenten:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

Die Einstellung debug_chat_ui: true aktiviert auch die chat und chatstream APIs, weil die Benutzeroberfläche davon abhängt. Setzen chat_api: true Sie sich selbst, wenn Sie programmatischen Chatzugang ohne Debug-UI möchten.

Endpunktrouten

Das Routensegment <AGENT_NAME> stammt vom Dateinamen .agent.md, nicht vom Anzeigefeld name. Zum Beispiel verwendet main.agent.md/agents/main/.

Oberfläche Route Wichtige Anforderung
Chat-Benutzeroberfläche /agents/<AGENT_NAME>/ Funktionstaste (im Browser angezeigt).
HTTP-Chat-API POST /agents/<AGENT_NAME>/chat Funktionstaste.
Streaming-Chat-API POST /agents/<AGENT_NAME>/chatstream Funktionstaste.
MCP-Endpunkt /runtime/webhooks/mcp mcp_extension Systemschlüssel.

Schlüssel abrufen

Wenn du die Chat-UI in Azure hostest, wird vor dem Senden der Nachrichten nach einem Funktionsschlüssel gefragt. Du kannst den Schlüssel verwenden, wenn du die HTTP-Chat-APIs direkt aufrufst.

Verwenden Sie folgenden az functionapp keys list Befehl, um die Standard-Funktionstaste Ihrer App abzurufen:

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

In diesem Beispiel ersetze <RESOURCE_GROUP> und <FUNCTION_APP_NAME> durch deine Gruppen- und App-Namen. Sie können den zurückgegebenen Schlüssel in den x-functions-key Header oder einen code Abfragestring-Parameter in der HTTP-Anfrage an den Endpunkt einfügen.

Wenn Sie sich mit einem MCP-Client verbinden, fordern Sie stattdessen das MCP-Erweiterungssystem mit folgendem Befehl an:

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

Der MCP-Endpunkt benötigt diesen Systemschlüssel.

Chat-API-Anfragefluss

Beide eingebauten Chat-APIs erwarten einen JSON-Körper mit einem Feld prompt :

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

Benutze POST /agents/<AGENT_NAME>/chat , wenn du eine JSON-Antwort möchtest. Der Antwortkörper umfasst session_id, response, und tool_calls. Die Laufzeit spiegelt auch dieselbe Session-ID im x-ms-session-id Response-Header wider.

Benutze POST /agents/<AGENT_NAME>/chatstream Server-Sent Events (SSE), wenn du möchtest. Der Stream beginnt mit einem session Ereignis, das die aufgelöste Sitzungs-ID enthält, gefolgt von null oder mehr delta, intermediate, tool_start, und tool_end Ereignissen, und endet mit entweder done oder error.

Um eine Mehrrunden-Konstruktion fortzusetzen, senden Sie die Sitzungs-ID aus der früheren Antwort in den x-ms-session-id Anfrage-Header auf später chat oder chatstream Calls. Wenn du diesen Header weglässt, erstellt die Laufzeit automatisch eine neue Sitzung.

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

Sitzungen und Status

Mehrfache Agenteninteraktionen erfordern die Sitzungshistorie. Die Laufzeit verwaltet die Sitzungsspeicherung automatisch basierend auf der Umgebung:

Environment Storage Konfiguration
Azure Blob Storage im Standard-Host-Speicherkonto (AzureWebJobsStorage) Verbindungsstring oder identitätsbasiert (bevorzugt). Siehe Konfiguration der verwalteten Identität.
Lokale Entwicklung Dateibasiert im Konfigurationsverzeichnis der lokalen Agenten Keine Konfiguration erforderlich.

Die Laufzeit benötigt keine separate Sitzungsdatenbank. Sandbox-Ausführung ist zudem sitzungsbewusst: Wenn keine explizite Session-ID verfügbar ist, verwendet die Laufzeit eine frische, isolierte Sandbox-Sitzung, sodass nicht zusammenhängende Aufrufe keinen gemeinsamen Zustand erhalten.

Unterstützte Hosting-Pläne

Die Serverless-Agents-Laufzeit unterstützt diese Azure Functions-Hosting-Pläne:

Planen Serverlose Skalierung Hinweise
Flex-Verbrauch Ja Skalierung bis Null, pro Sekunde Abrechnung und automatische Skalierung. Empfohlen für die meisten Agenten-Workloads.
Dediziert (App Service) No Always-on-Instanzen mit manueller oder regelbasierter Skalierung. Nutzen Sie, wenn Sie bereits App Service Plan-Instanzen mit verfügbarer Kapazität haben.

Beide Pläne unterstützen Managed Identity, virtuelle Netzwerkintegration und Application Insights.