Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Importante
Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.
Un adattatore di protocollo è un wrapper leggero dell'SDK che consente al codice del tuo agente di comunicare tramite uno dei protocolli per agenti ospitati di Microsoft Foundry. In questo articolo si installa il pacchetto dell'adattatore SDK, si collega un gestore, si dichiara il protocollo in azure.yamle si ridistribuisce. Aggiungere un adattatore quando si usa codice personalizzato che non implementa già il contratto di runtime dell'agente ospitato.
Prerequisiti
- Progetto con agente ospitato. Per crearne uno, vedere Inizializzare un progetto agente ospitato con l'interfaccia della riga di comando per sviluppatori di Azure.
- Python 3.10 o versione successiva o .NET 8 o versione successiva.
- La logica dell'agente in una funzione che è possibile chiamare da un gestore.
Scegliere un protocollo
| Protocol | Quando utilizzare |
|---|---|
responses |
Agenti di conversazione. Ottieni la cronologia automatica delle conversazioni, lo streaming e la compatibilità con l'API Responses di OpenAI. |
invocations |
Carichi di lavoro non conversazionali o con payload personalizzato. Definire la forma della richiesta e della risposta. |
Per dettagli completi sul contratto, vedere Contratto di runtime dell'agente ospitato.
Installare il pacchetto SDK
# For the Responses protocol
pip install azure-ai-agentserver-responses
# For the Invocations protocol
pip install azure-ai-agentserver-invocations
Implementa un gestore
I criteri seguenti sono una versione abbreviata dei propri esempi nel repository foundry-samples. Usarli come punto di partenza e copiare l'esempio completo per il codice di produzione.
Protocollo di risposte
import asyncio
import os
from azure.ai.agentserver.responses import (
CreateResponse,
ResponseContext,
ResponsesAgentServerHost,
ResponsesServerOptions,
TextResponse,
)
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
_model = os.environ["FOUNDRY_MODEL_NAME"]
_project_client = AIProjectClient(
endpoint=_endpoint, credential=DefaultAzureCredential()
)
_responses_client = _project_client.get_openai_client().responses
app = ResponsesAgentServerHost(
options=ResponsesServerOptions(default_fetch_history_count=20),
)
@app.response_handler
async def handler(
request: CreateResponse,
context: ResponseContext,
_cancellation_signal: asyncio.Event,
):
user_input = await context.get_input_text() or "Hello!"
# --- Your agent logic goes here ---
response = await asyncio.get_running_loop().run_in_executor(
None,
lambda: _responses_client.create(
model=_model,
instructions="You are a helpful AI assistant.",
input=[{"role": "user", "content": user_input}],
store=False,
),
)
# -----------------------------------
return TextResponse(context, request, text=response.output_text)
app.run()
Protocollo di Invocazioni
from starlette.requests import Request
from starlette.responses import Response, JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost
app = InvocationAgentServerHost()
@app.invoke_handler
async def handle_invoke(request: Request) -> Response:
data = await request.json()
# --- Your agent logic goes here ---
# The payload shape is entirely up to you
message = data.get("message", "Hello!")
return JSONResponse({"reply": message})
if __name__ == "__main__":
app.run()
Dichiarare il protocollo in azure.yaml
Aggiungi o aggiorna il campo protocols nel servizio azure.ai.agent nel tuo azure.yaml:
services:
my-agent:
host: azure.ai.agent
project: src/my-agent
kind: hosted
protocols:
- protocol: responses
version: 2.0.0
Per le chiamate, usare il protocollo seguente:
services:
my-agent:
host: azure.ai.agent
project: src/my-agent
kind: hosted
protocols:
- protocol: invocations
version: 1.0.0
Aggiornare il comando di avvio
Assicurarsi che startupCommand nel servizio azure.ai.agent punti al punto di accesso che avvia il server:
services:
my-agent:
host: azure.ai.agent
startupCommand: python main.py
Testare localmente e ridistribuire
# Test locally
azd ai agent run
# In another terminal
azd ai agent invoke --local "Hello!"
# Deploy
azd deploy
Per il invocations protocollo, usare --input-file per inviare il payload personalizzato:
azd ai agent invoke --local -f request.json
Aggiungere un secondo protocollo
Un agente può supportare più protocolli. Per aggiungere un secondo, installare il pacchetto SDK aggiuntivo, registrare entrambi i gestori nel punto di ingresso e aggiungere entrambi i protocolli al azure.ai.agent servizio in azure.yaml:
services:
my-agent:
host: azure.ai.agent
protocols:
- protocol: responses
version: 2.0.0
- protocol: invocations
version: 1.0.0
Annotazioni
Quando un agente supporta più protocolli, azd ai agent invoke usa il responses protocollo per impostazione predefinita. Passare -p/--protocol per selezionare responses o invocations in modo esplicito.