Implementar um agente alojado

Este artigo mostra-lhe como implementar um agente containerizado para o Foundry Agent Service usando o SDK Python ou a API REST. Use estas abordagens quando quiser gerir implementações de agentes diretamente a partir das suas próprias aplicações ou serviços.

Se estás a implementar pela primeira vez ou queres o caminho mais rápido, usa o Quickstart: Criar e implementar um agente alojado . O quickstart utiliza a CLI de Desenvolvedor Azure (azd) ou a extensão VS Code, que gerem automaticamente a construção, o lançamento, a versão e a configuração RBAC.

Ciclo de vida de implementação

Cada implementação de agente hospedado segue esta sequência:

1. Construir e enviar — Empacote o código do seu agente numa imagem de contentor e envie-o para o Azure Container Registry.
2. Crie uma versão de agente — Registe a imagem no Foundry Agent Service. A plataforma fornece infraestrutura e cria uma identidade dedicada ao agente Entra.
3. Verificar estado — Aguardar que o estado da versão chegueactive.
4. Invocar — Enviar solicitações para o endpoint dedicado do agente.

Pré-requisitos

• Um projeto Microsoft Foundry.
• Código de agente usando um framework suportado.
• Docker Desktop instalado para desenvolvimento local de contentores.
• CLI do Azure versão 2.80 ou posterior.

Permissões necessárias

Precisa de Foundry Project Manager ao nível do projeto para criar e implementar agentes alojados. Esta função inclui tanto as permissões do plano de dados para criar agentes como a capacidade de atribuir a função Utilizador do Foundry à identidade do agente criada pela plataforma. A identidade do agente necessita do Utilizador Foundry no projeto para aceder a modelos e artefactos em tempo de execução.

Se usar azd ou a extensão VS Code, a ferramenta gere automaticamente a maioria das atribuições RBAC, incluindo:

• Leitor de Repositório do Registro de Contentores para a identidade gerida pelo projeto (transferência de imagens)
• Foundry User para a identidade do agente criado pela plataforma (modelo de execução e acesso à ferramenta)

Para mais informações, consulte Autenticação e autorização.

Requisitos de contentores

A sua imagem de contentor deve cumprir os seguintes requisitos para ser executada na plataforma de agente alojado.

Bibliotecas de protocolos

Os agentes alojados comunicam com o gateway Foundry através de bibliotecas de protocolos. Escolha o protocolo que corresponda ao padrão de interação do seu agente:

O protocolo WebSocket usa o identificador invocations_ws e é enviado no mesmo azure-ai-agentserver-invocations pacote da rota HTTP /invocations , pelo que um contentor pode servir ambos. Use-o quando precisar de streaming persistente e full-duplex — por exemplo, enviando PCM de microfone para o agente e recebendo áudio sintetizado de volta. Para cenários de voz, consulte Criar um agente de voz com agentes hospedados.

Um único contentor pode expor múltiplos protocolos simultaneamente , declarando-os quando se cria o agente — no agent.yaml ficheiro, chamada SDK ou pedido de API REST — e importando as bibliotecas necessárias. Use as bibliotecas de protocolos dentro do seu framework existente, seja o Microsoft Agent Framework, LangChain ou código personalizado.

Biblioteca de protocolos de respostas

As bibliotecas Python e .NET para o protocolo Responses implementam a API Azure AI Responses. Importa o pacote e implementa a IResponseHandler interface. A biblioteca gere o encaminhamento de rotas, o streaming com SSE (eventos enviados pelo servidor), a execução em segundo plano, o cancelamento, o cache e a gestão do ciclo de vida das respostas.

IResponseHandler

IResponseHandler é a abstração central que implementas. A biblioteca chama CreateAsync para cada pedido recebido e entrega o IAsyncEnumerable<ResponseStreamEvent> retornado aos clientes através de SSE.

public class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: async ct =>
            {
                var input = await context.GetInputTextAsync(cancellationToken: ct);
                return $"Echo: {input}";
            });
    }
}

ResponseEventStream

ResponseEventStream gere sequenceNumber, outputIndex, contentIndex, itemId e o ciclo de vida completo de Response automaticamente. Cada yield return corresponde diretamente a um evento SSE, por isso não é necessário acompanhar este estado.

Modos de streaming e em segundo plano

• Modo de streaming (predefinido): os eventos SSE são entregues em tempo real ao cliente ligado.
• Modo de fundo: O handler corre até à conclusão sem um cliente SSE ligado. Os eventos estão em buffer e disponíveis para rejogar através de GET /responses/{id}.

Ciclo de vida da resposta

A biblioteca orquestra todo o ciclo de vida da resposta: created → in_progress → completed (ou failed ou cancelled). A biblioteca também gere automaticamente garantias de cancelamento, tratamento de erros e eventos do terminal.

Segurança da rosca

Todas as instâncias de serviço registadas através de AddResponsesServer() são thread-safe. As instâncias de handler são definidas por requerimento.

Para orientações detalhadas sobre implementação de handlers, consulte o guia de implementação handler. Para exemplos executáveis, consulte os exemplos do protocolo Responses.

Parâmetros de saúde

As bibliotecas de protocolos expõem automaticamente um /readiness endpoint para verificações do estado de saúde da plataforma. Não precisas de implementar isto tu próprio.

Porto

Contentores servem tráfego localmente no porto 8088. Em produção, o Foundry gateway trata do encaminhamento — o seu contentor não precisa de expor uma porta pública.

Variáveis ambientais injetadas pela plataforma

A plataforma de agente hospedado injeta automaticamente variáveis de ambiente no seu contentor em tempo de execução. O seu código pode ler estas sem as declarar em agent.yaml ou environment_variables. O FOUNDRY_* prefixo é reservado para uso em plataformas.

Não redeclares variáveis injetadas pela plataforma em agent.yaml— elas são definidas automaticamente.

Variáveis que declaras por ti próprio, como endpoints MCP da toolbox MODEL_DEPLOYMENT_NAME, vão para a secção environment_variables de agent.yaml ou a chamada SDK create_version.

Ligações de projetos de referência em variáveis ambientais

Em vez de incorporar segredos diretamente no código (chaves API, tokens, endpoints) em agent.yaml ou na sua imagem, obtenha-os a partir de uma conexão a um projeto Foundry no arranque da sandbox. Qualquer valor em environment_variables pode ser uma expressão provisória que a plataforma resolve antes do início do seu contentor.

Sintaxe de marcador de posição

Um marcador tem a forma ${{connections.<name>.<path>}}, em que <name> é o nome do recurso da ligação (visível no portal em Detalhes do projeto>Recursos ligados) e <path> é um dos seguintes:

O nome do campo a usar depende da categoria de ligação:

Exemplo

Primeiro, crie uma CustomKeys ligação no projeto que contém o segredo. Veja Adicionar uma nova ligação em Microsoft Foundry. Em seguida, faz referência ao mesmo a partir de agent.yaml:

environment_variables:
  - name: MODEL_DEPLOYMENT_NAME
    value: gpt-5-mini
  - name: GITHUB_TOKEN
    value: ${{connections.agent-secrets.credentials.github_token}}

No início do sandbox, o Foundry resolve o marcador e injeta o valor resolvido como uma variável de ambiente simples. O seu código lê isso como qualquer outra variável de ambiente:

import os
token = os.environ["GITHUB_TOKEN"]

Um GET na versão do agente devolve o texto literal ${{...}} — o segredo resolvido nunca é ecoado de volta através da API de gestão.

Considerations

• Cria a ligação antes de implementares a versão. Se a conexão ou o campo referenciado estiverem em falta ao iniciar a sandbox, o marcador de posição não é resolvido e a variável fica vazia.
• Os segredos são apenas para escrita. O GET numa conexão devolve credentials: null. Verifique a resolução lendo a variável de ambiente a partir do interior do contentor em execução, e não inspecionando a ligação.
• Regista CustomKeys manualmente os nomes dos campos. A API de gestão nunca os repete após a criação. Mantenha-os junto à origem do seu agente (por exemplo, em modelos IaC ou juntamente com agent.yaml) para que possa criar marcadores de posição mais tarde sem ter de adivinhar.
• Foundry gere o nome secreto de apoio. Quando crias a ligação, o Foundry armazena o valor no Key Vault sob um nome que escolhe — não podes referenciar um segredo pré-existente do Key Vault pelo nome. Para associar o seu próprio Key Vault como armazenamento subjacente, consulte Configurar uma ligação ao Key Vault.

Empacota e testa o teu agente localmente

Antes de implementar no Foundry, valide que o seu agente funciona localmente usando a biblioteca de protocolos. O contentor serve os mesmos endpoints localmente que em produção.

Teste o protocolo Respostas

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

Teste o protocolo de Invocações

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

Implementar usando o Azure Developer CLI ou VS Code

A Azure Developer CLI (azd) e a extensão VS Code automatizam todo o ciclo de vida da implementação. Para um guia passo a passo, consulte o Quickstart: Criar e implementar um agente alojado.

Implementar usando o SDK Python

Usa o SDK quando quiseres gerir implementações de agentes diretamente a partir de código Python.

Pré-requisitos adicionais

• Python 3.10 ou posterior

• Uma imagem de contentor em Azure Container Registry

• Papel de Escritor de Repositório do Registo de Contentores ou AcrPush no registo de contentores (para enviar imagens)

• Azure AI Projects SDK versão 2.1.0 ou posterior

  pip install "azure-ai-projects>=2.1.0"
  

Construa e carregue a sua imagem de container

1. Constrói a tua imagem no Docker:

   docker build --platform linux/amd64 -t myagent:v1 .
   

   Veja Dockerfiles de exemplo para Python e C#.

2. Enviar para o Azure Container Registry:

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

Configurar permissões de registo de contentores

Conceda à identidade gerida do seu projeto acesso para extrair imagens:

1. No portal Azure, aceda ao recurso do seu projeto Foundry.

2. Selecione Identidade e copie o ID do Objeto (principal) em Sistema atribuído.

3. Atribui o papel de Leitor de Repositório do Registo de Contentores a esta identidade no teu registo de contentores. Veja Azure Container Registry funções e permissões.

Criar uma versão de agente hospedada

Criar uma versão faz com que a plataforma faça provisionar automaticamente o agente. Não existe uma etapa inicial separada — a plataforma constrói um snapshot de contentor e torna o agente pronto para atender pedidos.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol
from azure.identity import DefaultAzureCredential

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

Para expor múltiplos protocolos, passe cada um em container_protocol_versions:

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentProtocol.INVOCATIONS_WS, version="1.0.0"),
],

Parâmetros-chave:

Inquérito para o estado da versão

Depois de criar uma versão, verifique até que o estado esteja active antes de invocar o agente. O provisionamento normalmente demora menos de um minuto, dependendo do tamanho da imagem.

import time

# Poll until the agent version is active
while True:
    version_info = project.agents.get_version(
        agent_name="my-agent",
        agent_version=agent.version
    )
    status = version_info["status"]
    print(f"Status: {status}")

    if status == "active":
        print("Agent is ready!")
        break
    elif status == "failed":
        print(f"Provisioning failed: {version_info['error']}")
        break

    time.sleep(5)

Valores de estado da versão:

Invocar o agente

Depois de a versão atingir active o estado, use get_openai_client para criar um cliente OpenAI ligado ao endpoint do agente.

Para o protocolo Respostas :

# Create an OpenAI client bound to the agent endpoint
openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Hello! What can you do?",
)

print(response.output_text)

Para o protocolo Invocations , chame diretamente o endpoint das invocações:

import requests

token = credential.get_token("https://ai.azure.com/.default").token
url = f"{PROJECT_ENDPOINT}/agents/my-agent/endpoint/protocols/invocations"

response = requests.post(url, headers={
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    "Foundry-Features": "HostedAgents=V1Preview"
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

Para exemplos mais completos, consulte os exemplos de agentes hospedados.

Implementar usando a API REST

Use a API REST para implementações diretas baseadas em HTTP ou ao integrar com ferramentas personalizadas.

Antes de começar, constrói e divulga a imagem do teu contentor e configura permissões de registo de contentores.

Configurar variáveis

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

Criar um agente

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v1",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Criar um agente também cria versões 1 e desencadeia o provisionamento.

Inquérito para o estado da versão

Verifica continuamente o endpoint de versão até que status seja active:

while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
    -H "Authorization: Bearer $TOKEN" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "active" ] && echo "Ready!" && break
  [ "$STATUS" = "failed" ] && echo "Provisioning failed." && exit 1
  sleep 5
done

Invocar o agente

Utilize o endpoint dedicado do agente para enviar requisições. Definir "stream": true para receber eventos enviados pelo servidor.

Protocolo de respostas:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! What can you do?",
    "store": true
  }'

Protocolo de invocações:

curl -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/invocations?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Foundry-Features: HostedAgents=V1Preview" \
  -d '{
    "message": "Process this task"
  }'

Criar uma nova versão

Implemente código ou configuração atualizada criando uma nova versão:

curl -X POST "$BASE_URL/agents/my-agent/versions?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "kind": "hosted",
      "image": "myacr.azurecr.io/my-agent:v2",
      "cpu": "1",
      "memory": "2Gi",
      "container_protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

Recursos de limpeza

Para evitar cobranças, limpe os recursos quando terminar. A computação do agente é desprovisionada após 15 minutos de inatividade, por isso não existe custo quando um agente não está a processar pedidos.

Limpeza do Azure Developer CLI

azd down

Limpeza do SDK

Apague uma única versão:

project.agents.delete_version(agent_name="my-agent", agent_version=agent.version)

Ou apagar o agente inteiro e todas as suas versões:

project.agents.delete(agent_name="my-agent")

Limpeza da API REST

Apague uma única versão:

curl -X DELETE "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Ou apagar o agente inteiro:

curl -X DELETE "$BASE_URL/agents/my-agent?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN"

Resolução de problemas

Erros de provisionamento surgem nos campos error.code e error.message do objeto de versão. Verifique o estado da versão após a criação para identificar problemas.

Para erros 5xx, contacte o suporte da Microsoft.

Para requisitos detalhados de RBAC e resolução de problemas de permissões, consulte Referência de permissões de agente hospedado.

Próximos passos

Conteúdo relacionado

• O que são agentes alojados?
• Conceitos de identidade do agente
• Aplicações para agentes

• Documentação do Azure Container Registry