Implementar um agente alojado

Implementar usando o Azure Developer CLI ou VS Code

O Azure Developer CLI (azd) e o Microsoft Foundry Toolkit for Visual Studio Code automatizam todo o ciclo de vida da implementação: construir o contenteur, enviá-lo para o Azure Container Registry, criar a versão do agente e atribuir papéis RBAC. Para um guia de iniciação, consulte o Início rápido: Criar e implementar um agente alojado.

Implemente com um único comando

A partir do diretório de projetos do seu agente, provisione a infraestrutura e implemente num único passo:

azd up

azd up combina azd provision, que cria o projeto Foundry, a implementação do modelo, o registo de contentores, o Application Insights e a identidade gerida, com azd deploy. Usa-o para implementações iniciais ou sempre que mudares tanto o código da infraestrutura como o do agente.

Implemente apenas alterações ao código

Se já provisionaste os teus recursos do Azure e só precisas de lançar uma nova versão do agente:

azd deploy

Durante azd deploy, a CLI:

1. Constrói a imagem do teu contentor remotamente no Azure Container Registry, por isso não precisas do Docker local.
2. Envia a imagem para o registo.
3. Cria uma versão de agente alojada no Foundry Agent Service.
4. Cria uma identidade dedicada ao agente Microsoft Entra e atribui os papéis RBAC que o agente precisa para aceder a modelos e ferramentas.

Gerir as versões

Cada um azd deploy cria uma nova versão do agente. A CLI preserva versões anteriores, e a versão mais recente está ativa por defeito.

Verificar a implantação

azd ai agent show

A saída inclui o nome do agente, versão, protocolos, recursos do contentor, variáveis de ambiente e carimbo temporal de criação. Use --output table para uma vista resumida.

Criar imagens localmente

Por defeito, azd constrói imagens de contentores remotamente no Azure Container Registry. Para construir imagens localmente, defina remoteBuild: false em azure.yaml. Compilações locais requerem o Docker Desktop.

Para filtrar os prompts e respostas de acordo com uma política de segurança de conteúdos, adicione uma barreira de segurança de conteúdos ao seu agente.

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.3.0 ou posterior

  pip install "azure-ai-projects>=2.3.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

Quando crias uma versão, a plataforma provisiona automaticamente o agente. Não há uma etapa inicial separada. A plataforma constrói um snapshot do contentor e torna o agente pronto para atender pedidos.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointProtocol,
    ContainerConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
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,
)

# Create a hosted agent version
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0")
        ],
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(
            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 ambos os protocolos, passe ambos em protocol_versions:

protocol_versions=[
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS, version="1.0.0"),
    ProtocolVersionRecord(protocol=AgentEndpointProtocol.INVOCATIONS_WS, version="1.0.0"),
],

Parâmetros-chave:

Para definir quando a computação da sessão fica inativa, veja Gerir a inatividade da sessão.

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",
}, params={"api-version": "v1"}, json={
    "message": "Process this task"
})

print(response.json())

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

Implementar usando o SDK JavaScript/TypeScript

Usa o SDK quando quiseres gerir implementações de agentes diretamente a partir de Node.js código. O chamador do SDK é executado em Node.js, mas a própria imagem do contentor continua a executar o seu código de agente em Python ou .NET, criado com as bibliotecas de protocolo Responses ou Invocations — não existe um runtime alojado de agente em Node.js.

Pré-requisitos adicionais

• Node.js 22 ou depois

• 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)

• Os pacotes @azure/ai-projects e @azure/identity

  npm install @azure/ai-projects @azure/identity
  

Antes de começar, compile e envie a imagem de contentor para o Azure Container Registry (consulte o separador Python para ver comandos Docker de exemplo) e conceda à identidade gerida do projeto a função Container Registry Repository Reader no registo de contentores.

Criar uma versão de agente hospedada

Quando crias uma versão, a plataforma provisiona automaticamente o agente. Não há uma etapa inicial separada. A plataforma constrói um snapshot do contentor e torna o agente pronto para atender pedidos.

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] || "your_project_endpoint";
const agentName = "my-agent";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

// Create a hosted agent version
const agent = await project.agents.createVersion(agentName, {
  kind: "hosted",
  cpu: "1",
  memory: "2Gi",
  container_configuration: {
    image: "your-registry.azurecr.io/your-image:tag",
  },
  protocol_versions: [{ protocol: "responses", version: "1.0.0" }],
  environment_variables: { MODEL_DEPLOYMENT_NAME: "gpt-5-mini" },
});

console.log(`Agent created: ${agent.name}, version: ${agent.version}`);

Para expor ambos os protocolos, passe ambos em protocol_versions:

protocol_versions: [
  { protocol: "responses", version: "1.0.0" },
  { protocol: "invocations", version: "1.0.0" },
  { protocol: "invocations_ws", version: "1.0.0" },
],

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.

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

// Poll until the agent version is active
for (;;) {
  const versionInfo = await project.agents.getVersion(
    agentName,
    agent.version,
  );
  console.log(`Status: ${versionInfo.status}`);
  if (versionInfo.status === "active") {
    break;
  }
  if (versionInfo.status === "failed") {
    console.log(`Provisioning failed: ${versionInfo.error}`);
    break;
  }
  await sleep(5_000);
}

Encaminhe o endpoint do agente e invoque-o

Encaminhe o endpoint do agente para a versão que criou e depois associe um cliente OpenAI ao endpoint.

Para o protocolo Respostas :

await project.agents.patchAgentObject(agentName, {
  agentEndpoint: {
    version_selector: {
      version_selection_rules: [
        {
          type: "FixedRatio",
          agent_version: agent.version,
          traffic_percentage: 100,
        },
      ],
    },
    protocol_configuration: { responses: {} },
  },
});

// Create an OpenAI client bound to the agent endpoint
const openAIClient = project.getOpenAIClient({
  azureConfig: { allowPreview: true, agentName },
});

const response = await openAIClient.responses.create({
  input: "Hello! What can you do?",
});
console.log(response.output_text);

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

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");
if (!token) {
  throw new Error("Failed to acquire an access token.");
}
const url = `${projectEndpoint}/agents/my-agent/endpoint/protocols/invocations`;

const response = await fetch(`${url}?api-version=v1`, {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token.token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Process this task" }),
});
console.log(await response.json());

Referência: AIProjectClient

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, construa e envie a sua imagem de contentor para o Azure Container Registry, e conceda à identidade gerida do projeto o papel de Leitor de Repositório do Registo de Contentores no registo.

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",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v1"
      },
      "cpu": "1",
      "memory": "2Gi",
      "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.

Para definir quando a computação da sessão fica inativa, veja Gerir a inatividade da sessão.

Para analisar pedidos e respostas de acordo com uma política de segurança de conteúdo, inclua um objeto rai_config no definition. Veja Adicionar uma proteção de segurança de conteúdo a um agente hospedado.

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" \
  -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",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v2"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "environment_variables": {
        "MODEL_DEPLOYMENT_NAME": "gpt-5-mini"
      }
    }
  }'

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 eliminar o agente na totalidade e todas as respetivas versões. Use force=True para apagar em cascata quaisquer sessões ativas, como logo após invocar o agente; sem ele, a chamada falha com um erro de conflito enquanto as sessões estão ativas:

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

Limpeza do SDK

Apague uma única versão:

await project.agents.deleteVersion("my-agent", agent.version);

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

await project.agents.delete("my-agent", { force: true });

Referência: AIProjectClient

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"