Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Importante
Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.
Um adaptador de protocolo é um wrapper leve de SDK que permite que o código do seu agente se comunique usando um dos protocolos de agente hospedados do Microsoft Foundry. Neste artigo, você instala o pacote do adaptador do SDK, conecta um manipulador, declara o protocolo azure.yamle reimplanta. Adicione um adaptador ao usar código próprio que não implemente o contrato de tempo de execução do agente hospedado.
Pré-requisitos
- Um projeto de agente hospedado. Para criar um, consulte Inicializar um projeto de agente hospedado com a CLI do Desenvolvedor do Azure.
- Python 3.10 ou posterior ou .NET 8 ou posterior.
- A lógica do seu agente em uma função que você pode chamar de um manipulador.
Escolher um protocolo
| Protocol | Quando usar |
|---|---|
responses |
Agentes conversacionais. Você obtém compatibilidade automática de histórico de conversas, streaming e API de Respostas OpenAI. |
invocations |
Cargas de trabalho não conversacionais ou de carga útil personalizada. Você define a forma de solicitação e resposta. |
Para obter os detalhes completos do contrato, consulte o contrato de runtime do agente hospedado.
Instalar o pacote do SDK
# For the Responses protocol
pip install azure-ai-agentserver-responses
# For the Invocations protocol
pip install azure-ai-agentserver-invocations
Implemente um manipulador
Os padrões abaixo são adaptados dos exemplos do tipo “traga o seu próprio” no repositório foundry-samples. Use-os como ponto de partida e copie o exemplo completo para o 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()
Declarar o protocolo em 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
Atualizar o comando de inicialização
Verifique se o startupCommand no serviço azure.ai.agent aponta para o ponto de entrada que inicia o servidor:
services:
my-agent:
host: azure.ai.agent
startupCommand: python main.py
Testar localmente e reimplantar
# 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 seu payload personalizado:
azd ai agent invoke --local -f request.json
Adicionar um segundo protocolo
Um agente pode dar suporte a vários protocolos. Para adicionar um segundo, instale o pacote SDK adicional, registre ambos os manipuladores no seu ponto de entrada e adicione ambos os protocolos ao serviço azure.ai.agent 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 dá suporte a vários protocolos, azd ai agent invoke usa o responses protocolo por padrão. Passe -p/--protocol para selecionar responses ou invocations explicitamente.