Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Importante
Os itens assinalados como (pré-visualização) neste artigo estão atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para trabalhos em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.
Um adaptador de protocolo é um wrapper SDK leve que permite ao código do seu agente falar com um dos protocolos de agente alojados pela Microsoft Foundry. Neste artigo, instala o pacote do adaptador do SDK, configura um processador, declara o protocolo em azure.yaml e volta a implementar. Adiciona um adaptador quando trouxeres o teu próprio código que ainda não implemente o contrato de execução do agente alojado.
Pré-requisitos
- Um projeto de agente alojado. Para criar uma, veja Inicializar um projeto de agente hospedado com a CLI do Azure Developer.
- Python 3.10 ou posterior, ou .NET 8 ou posterior.
- A lógica do teu agente é uma função que podes chamar a partir de um handler.
Escolha um protocolo
| Protocolo | Quando utilizar |
|---|---|
responses |
Agentes conversacionais. Obtém histórico automático de conversas, streaming e compatibilidade com a API OpenAI Responses. |
invocations |
Cargas de trabalho não conversacionais ou personalizadas. Defines a forma do pedido e da resposta. |
Para consultar os detalhes completos do contrato, consulte Contrato de execução do agente hospedado.
Instalar o pacote SDK
# For the Responses protocol
pip install azure-ai-agentserver-responses
# For the Invocations protocol
pip install azure-ai-agentserver-invocations
Implementar um handler
Os padrões abaixo são versões abreviadas dos exemplos «bring-your-own» no repositório foundry-samples. Usa-os como ponto de partida e copia o exemplo completo para código de produção.
Protocolo de Respostas
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()
Protocolo de invocações
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()
Declare o protocolo no ficheiro azure.yaml
Adicione ou atualize o campo protocols no serviço azure.ai.agent no seu azure.yaml:
services:
my-agent:
host: azure.ai.agent
project: src/my-agent
kind: hosted
protocols:
- protocol: responses
version: 2.0.0
Para invocações, use o seguinte protocolo:
services:
my-agent:
host: azure.ai.agent
project: src/my-agent
kind: hosted
protocols:
- protocol: invocations
version: 1.0.0
Atualize o comando de arranque
Certifique-se de que o startupCommand no azure.ai.agent serviço aponta para o ponto de entrada que inicia o servidor:
services:
my-agent:
host: azure.ai.agent
startupCommand: python main.py
Testar localmente e reimplementar
# Test locally
azd ai agent run
# In another terminal
azd ai agent invoke --local "Hello!"
# Deploy
azd deploy
Para o protocolo invocations, use --input-file para enviar a sua carga útil personalizada:
azd ai agent invoke --local -f request.json
Adicionar um segundo protocolo
Um agente pode suportar múltiplos protocolos. Para adicionar um segundo, instale o pacote SDK adicional, registe ambos os handlers no seu ponto de entrada e adicione ambos os protocolos ao azure.ai.agent serviço em azure.yaml:
services:
my-agent:
host: azure.ai.agent
protocols:
- protocol: responses
version: 2.0.0
- protocol: invocations
version: 1.0.0
Note
Quando um agente suporta múltiplos protocolos, azd ai agent invoke utiliza o responses protocolo por defeito. Passe -p/--protocol para selecionar responses ou invocations explicitamente.