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 `chatstream`Endpunktrouten , 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:

AZURE_OPENAI_ENDPOINTselects Azure OpenAI.
FOUNDRY_PROJECT_ENDPOINTwählt Azure AI Foundry .
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:

Das vom Agenten oder Runtime-Aufruf angeforderte Modell.
Anbieterspezifische Einstellungen, wie z. B. AZURE_OPENAI_DEPLOYMENT oder FOUNDRY_MODEL.
Das Modell setzt in AZURE_FUNCTIONS_AGENTS_MODEL.
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ückfall¹
Azure OpenAI model provider²	`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 Sitzungshistorie³	`AzureWebJobsStorage__clientId`	`AZURE_CLIENT_ID`, dann `DefaultAzureCredential`

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

Feedback

War diese Seite hilfreich?

Last updated on 2026-07-23