Traga seu próprio registro para agentes hospedados

Este artigo mostra como implantar um agente hospedado Microsoft Foundry que usa uma imagem de contêiner armazenada em um registro de contêiner autenticado fora de Azure, como o JFrog Artifactory ou um registro de Distribuição do Docker auto-hospedado. A solução usa a troca de tokens do OpenID Connect (OIDC) para que o agente possa se autenticar com o registro usando credenciais de curta duração em vez de segredos armazenados, como nomes de usuário do Registro, senhas ou tokens de acesso.

Neste artigo, o Registro Privado refere-se a qualquer registro de contêiner que exija autenticação. Isso não se refere a um Registro de Contêiner do Azure (ACR) protegido por um ponto de extremidade privado do Azure. Para usar um ACR existente ou um ACR com acesso à rede pública desabilitado, consulte Implantar um agente hospedado com um Registro de Contêiner do Azure privado.

Essa abordagem funciona com registros não Azure que dão suporte à troca de token OIDC. Um aplicativo do Microsoft Entra e a identidade gerenciada do projeto do Foundry participam do fluxo de autenticação, permitindo que o registro emita credenciais de curta duração para a extração de imagens.

Prerequisites

• Uma assinatura do Azure.

• Um projeto existente do Foundry. Você precisa do papel Foundry Project Manager para criar uma conexão de projeto. Consulte a referência de permissões do agente hospedado.

  Importante

  As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

• CLI do Azure, instalado e autenticado.

• Um shell compatível com Bash.

• Azure CLI do Desenvolvedor, versão 1.32.0 ou posterior, instalada e autenticada.

• As extensões do Foundry para Azure Developer CLI, incluindo azure.ai.agents 1.0.0-beta.13 ou posterior. Consulte Instalar as extensões do Foundry para Azure Developer CLI

• Para o fluxo de trabalho do SDK do Python, Python 3.10 ou posterior e os pacotes Azure AI Projects e Azure Identity.

  pip install azure-ai-projects azure-identity
  

• Uma imagem pré-criada e totalmente qualificada em um registro de contêiner autenticado fora do Azure ou em um registro Docker Distribution auto-hospedado.

• Permissão para configurar a confiança de identidade e o acesso ao repositório somente leitura no registro ou em seu serviço de autenticação.

• O destino do registro, o público-alvo do token e o endpoint de troca de token fornecidos pelo seu administrador de registro.

Um registro que dá suporte ao OpenID Connect (OIDC) não é automaticamente compatível com esse fluxo de trabalho. O serviço de autenticação do registro deve ser capaz de trocar um token de identidade gerenciada de um projeto do Microsoft Foundry por credenciais de curta duração aceitas pelo registro para download de imagens. JFrog Artifactory é um exemplo validado de uma implementação compatível. O Docker Distribution requer um adaptador de autenticação porque seu fluxo nativo de autenticação por token bearer não fornece um endpoint de troca de tokens do OAuth 2.0.

Criar um aplicativo Entra

Crie um aplicativo Entra para fornecer o valor de audiência usado durante a troca de tokens:

ENTRA_APPLICATION_ID=$(az ad app create \
  --display-name "Foundry-Registry-Agent" \
  --query appId \
  --output tsv)

echo "$ENTRA_APPLICATION_ID"

Registre a ID do aplicativo (cliente). O aplicativo não precisa de um segredo do cliente para esse fluxo. Forneça a ID do aplicativo ao administrador do registro para configurar como o público-alvo esperado no provedor OIDC do registro ou no serviço de troca de tokens.

Configurar OIDC para seu registro

Configure o serviço de autenticação do registro para confiar na identidade gerenciada do projeto Foundry e conceder a ela acesso para extração apenas ao repositório que contém a imagem do agente:

1. Defina o identificador do recurso do projeto Foundry.

   PROJECT_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/projects/<project-name>"
   

2. Obtenha a ID do objeto de identidade gerenciada do projeto.

   PROJECT_PRINCIPAL_ID=$(az resource show \
     --ids "$PROJECT_ID" \
     --api-version 2025-06-01 \
     --query identity.principalId \
     --output tsv)
   
   echo "$PROJECT_PRINCIPAL_ID"
   

3. Dê PROJECT_PRINCIPAL_ID ao administrador do registro. Vincule essa identidade ao acesso somente de leitura no repositório que contém a imagem do agente.

Escolha a configuração que corresponde ao registro.

JFrog Artifactory

No JFrog Artifactory, crie uma integração OIDC e um mapeamento de identidade que vinculem a identidade gerenciada do projeto a um grupo com acesso somente leitura ao repositório. Use /access/api/v1/oidc/token como o endpoint de token. Anote o nome do provedor OIDC da JFrog porque a conexão envia esse nome ao endpoint de token como body.provider_name.

Configure a ID do aplicativo do Entra a partir da Etapa 1 como o público-alvo do JFrog OIDC. O público-alvo na conexão do Foundry deve corresponder ao público-alvo na integração OIDC do JFrog.

Anote estes valores com o administrador do JFrog:

Valor	Description
Destino do registro	Origem HTTPS para o registro, como https://registry.contoso.com.
Público	ID do aplicativo do Microsoft Entra configurado como audience do OIDC do JFrog.
Ponto de extremidade de token	/access/api/v1/oidc/token.
Nome do provedor OIDC	Nome do provedor enviado como body.provider_name.

Distribuição do Docker

O Docker Distribution utiliza um desafio de bearer token de registro. Primeiro, um cliente de registro recebe um desafio WWW-Authenticate e, em seguida, solicita um token com os valores service e de repositório scope. Esse fluxo difere da troca de tokens OAuth 2.0.

Implante um adaptador de autenticação à frente do serviço de token do registro de distribuição. Configure o adaptador para:

• Confie na identidade gerenciada do projeto Foundry.
• Aceite a troca de token da conexão de registro do Foundry.
• Mapeie a identidade do projeto para conceder permissão de pull ao repositório necessário.
• Obtenha ou emita uma credencial de curta duração que o Registro de Distribuição aceita para esse repositório.

Configure o registro do Distribution para confiar no serviço de token do registro. Para ver os requisitos de desafio e do serviço de tokens, consulte autenticação do Docker Registry v2.

A implementação do adaptador depende do seu provedor de identidade e do seu serviço de token de registro. Use o endpoint de troca HTTPS do adaptador como tokenEndpoint na conexão do Foundry. A Foundry não define um contrato universal de solicitação e resposta do adaptador de Distribuição do Docker. Antes da implantação, obtenha o contrato suportado junto ao seu provedor de registro ou adaptador e teste se o endpoint retorna credenciais de pull aceitas pelo seu registro do Distribution.

Registre esses valores do administrador do adaptador:

Valor	Description
Destino do registro	Origem HTTPS para o registro, como https://registry.contoso.com.
Público	Identificador de recurso configurado como o público-alvo do token.
Ponto de extremidade de token	Endpoint HTTPS, ou caminho relativo ao destino do registro, que faz a troca do token de identidade do projeto.
Campos específicos do provedor	Campos de formulário adicionais exigidos pelo endpoint do token.

Criar a conexão com o registro

Crie uma CustomKeys conexão no mesmo projeto Foundry que hospeda o agente. Os metadados de conexão o identificam como uma conexão de registro de imagem que usa a troca de token OAuth.

CLI para Desenvolvedores do Azure

Defina o ponto de extremidade do projeto. Inclua o nome do projeto no caminho /api/projects/<project-name>:

PROJECT_ENDPOINT="https://<account-name>.services.ai.azure.com/api/projects/<project-name>"

Crie a conexão. Escolha o comando para o serviço de autenticação do Registro.

Para o JFrog Artifactory:

azd ai connection create private-registry \
  --project-endpoint "$PROJECT_ENDPOINT" \
  --kind custom-keys \
  --target "https://<registry-host>" \
  --auth-type custom-keys \
  --custom-key "audience=<token-audience>" \
  --custom-key "tokenEndpoint=<token-exchange-path>" \
  --custom-key "body.provider_name=<oidc-provider-name>" \
  --metadata "type=registry_connection" \
  --metadata "mode=oauth_token_exchange"

Para um adaptador de autenticação do Docker Distribution:

azd ai connection create private-registry \
  --project-endpoint "$PROJECT_ENDPOINT" \
  --kind custom-keys \
  --target "https://<registry-host>" \
  --auth-type custom-keys \
  --custom-key "audience=<token-audience>" \
  --custom-key "tokenEndpoint=<adapter-token-exchange-path>" \
  --metadata "type=registry_connection" \
  --metadata "mode=oauth_token_exchange"

Adicione uma body.<field-name> chave personalizada para cada campo de formulário extra exigido pelo adaptador.

Verifique a conexão sem exibir suas credenciais:

azd ai connection show private-registry \
  --project-endpoint "$PROJECT_ENDPOINT"

A saída identifica uma conexão CustomKeys com o destino de registro e os metadados registry_connection.

Bicep

Crie um arquivo chamado registry-connection.bicep. O providerName parâmetro é opcional. Forneça isso para o JFrog Artifactory e omita isso para um adaptador de autenticação do Docker Distribution.

targetScope = 'resourceGroup'

param accountName string
param projectName string
param connectionName string = 'private-registry'
param registryTarget string
param audience string
param tokenEndpoint string
param providerName string = ''

var registryKeys = union(
  {
    audience: audience
    tokenEndpoint: tokenEndpoint
  },
  empty(providerName) ? {} : {
    'body.provider_name': providerName
  }
)

resource account 'Microsoft.CognitiveServices/accounts@2025-06-01' existing = {
  name: accountName
}

resource project 'Microsoft.CognitiveServices/accounts/projects@2025-06-01' existing = {
  parent: account
  name: projectName
}

resource registryConnection 'Microsoft.CognitiveServices/accounts/projects/connections@2025-04-01-preview' = {
  parent: project
  name: connectionName
  properties: {
    category: 'CustomKeys'
    target: registryTarget
    authType: 'CustomKeys'
    credentials: {
      keys: registryKeys
    }
    metadata: {
      type: 'registry_connection'
      mode: 'oauth_token_exchange'
    }
  }
}

output registryConnectionId string = registryConnection.id

Implante o modelo no escopo do grupo de recursos:

az deployment group create \
  --resource-group <resource-group> \
  --template-file registry-connection.bicep \
  --parameters \
      accountName=<foundry-account-name> \
      projectName=<foundry-project-name> \
      connectionName=private-registry \
      registryTarget=https://<registry-host> \
      audience=<token-audience> \
      tokenEndpoint=<token-exchange-path> \
      providerName=<jfrog-oidc-provider-name>

Para um adaptador de autenticação do Docker Distribution, omita o parâmetro providerName. Adicione outra chave a registryKeys para cada valor extra de body.<field-name> que seu adaptador exige.

Configurar o acesso à rede privada

Escolha a opção que corresponde à configuração de rede de projeto do Foundry.

Sem isolamento de VNet

Quando o destino do registro e o ponto de extremidade de token estiverem disponíveis em endpoints HTTPS públicos, você não precisará configurar rede adicional para o registro.

Com isolamento de VNet

A conta Foundry também deve incluir a injeção na rede virtual do agente hospedado no momento da criação da conta. Você não pode adicionar injeção de rede a uma conta de Foundry existente para agentes hospedados. Para ver as restrições atuais, consulte Configurar a rede privada para o Foundry Agent Service.

1. Confirme se o provedor do Registro expõe um recurso Link Privado do Azure ou se o registro auto-hospedado está disponível por meio de um serviço de Link Privado gerenciado pelo cliente. Um ponto de extremidade privado do Azure não pode ter como destino um nome de host de registro arbitrário.
2. Crie um ponto de extremidade privado na rede virtual Foundry que tenha como destino o recurso de Link Privado do provedor ou o serviço de Link Privado do registro auto-hospedado.
3. Configure o DNS privado para que o nome do host do registro e o endpoint de token sejam resolvidos para os endereços do ponto de extremidade privado da rede virtual do Foundry.
4. Permita o tráfego TCP de saída pela porta 443 da rede Foundry para ambos os endpoints.

Criar e implantar o agente

Crie e implante o agente hospedado a partir da imagem predefinida do registro privado.

CLI para Desenvolvedores do Azure

Inicialize um projeto de agente hospedado com a imagem totalmente qualificada e o nome da conexão. A conexão já deve existir no projeto selecionado.

azd ai agent init --no-prompt \
  --agent-name private-registry-agent \
  --image <registry-host>/<repository>/agent:<tag> \
  --project-id "$PROJECT_ID" \
  --registry-connection private-registry

Revise o azure.yaml gerado. Mantenha o serviço azure.ai.project e o relacionamento uses do agente. O serviço do agente deve incluir a imagem docker.imagePassthrough: truepredefinida e o nome da conexão do Registro:

services:
  existing-project:
    host: azure.ai.project
    endpoint: ${FOUNDRY_PROJECT_ENDPOINT}

  private-registry-agent:
    host: azure.ai.agent
    uses:
      - existing-project
    kind: hosted
    name: private-registry-agent
    image: "<registry-host>/<repository>/agent:<tag>"
    docker:
      imagePassthrough: true
    registryConnectionId: private-registry
    protocols:
      - protocol: responses
        version: "2.0.0"

Uma conexão existente não pertence à uses lista. O valor de registryConnectionId pode ser o nome do Foundry da conexão ou o ID do recurso da conexão.

Se o agente exigir configuração em tempo de execução, armazene valores não secretos no ambiente azd ativo e faça referência a esses valores no mapa env do serviço do agente. Não armazene segredos diretamente em azure.yaml. Consulte Configurar variáveis de ambiente para um agente hospedado.

Implante o agente:

azd deploy --no-prompt

SDK do Python

Crie a versão do agente hospedado com registry_connection_id definido como o nome ou a ID de recurso da conexão existente do projeto Foundry. A criação da versão também implanta o agente.

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    ContainerConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential

PROJECT_ENDPOINT = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

agent = project.agents.create_version(
    agent_name="private-registry-agent",
    definition=HostedAgentDefinition(
        cpu="0.5",
        memory="1Gi",
        container_configuration=ContainerConfiguration(
            image="<registry-host>/<repository>/agent:<tag>",
            registry_connection_id="private-registry",
        ),
        protocol_versions=[
            ProtocolVersionRecord(
                protocol="responses",
                version="2.0.0",
            )
        ],
        environment_variables={
            "AZURE_AI_MODEL_DEPLOYMENT_NAME": os.environ[
                "AZURE_AI_MODEL_DEPLOYMENT_NAME"
            ],
        },
    ),
)

print(f"Created {agent.name}, version {agent.version}")

O SDK envia o nome da conexão ou a ID do recurso como registry_connection_id na definição do agente. As credenciais do registro permanecem na conexão do projeto Foundry e não são incluídas no seu código.

Verificar e invocar o agente

Aguarde até que o agente hospedado se torne ativo e envie uma solicitação de teste.

CLI para Desenvolvedores do Azure

Verifique o status do agente:

azd ai agent show

Aguarde até que o status seja alterado para Ativo e invoque o agente:

azd ai agent invoke "Respond with a short deployment confirmation."

SDK do Python

Sondar a versão implantada até que ela se torne ativa:

import time

while True:
    version = project.agents.get_version(
        agent_name="private-registry-agent",
        agent_version=agent.version,
    )
    status = version["status"]
    print(f"Status: {status}")

    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Agent deployment failed: {version['error']}")

    time.sleep(5)

Invoque o agente usando o ponto de extremidade Respostas:

openai_client = project.get_openai_client(
    agent_name="private-registry-agent"
)

response = openai_client.responses.create(
    input="Respond with a short deployment confirmation.",
)

print(response.output_text)

Uma implantação bem-sucedida confirma que o Foundry trocou o token de identidade, recuperou a imagem e iniciou o contêiner. Uma invocação bem-sucedida também confirma que o contêiner implementa o protocolo de Respostas configurado.

Solucionar problemas de implantação do Registro

Sintoma	Causa provável	Resolução
Retornos da troca de tokens invalid_subject	O mapeamento do registro não identifica a identidade gerenciada do projeto.	Compare a declaração de identidade usada pelo Registro com a ID do objeto de identidade gerenciada do projeto.
A troca de token retorna invalid_audience ou invalid_target	O público da conexão e o público do provedor de identidade do registro não coincidem.	Use o mesmo identificador de recurso no provedor do Registro e na chave da audience conexão.
A troca de token rejeita o emissor	O provedor de registro espera um emissor de token diferente.	Inspecione o token apresentado nos logs de autenticação do Registro e configure o provedor para corresponder exatamente à sua iss declaração.
A troca de token é concluída com sucesso, mas o download da imagem retorna 403	A identidade mapeada não tem permissão de pull do repositório ou o token emitido tem o escopo errado.	Conceda permissão de pull somente para leitura ao repositório de imagens e verifique o escopo de repositório do token.
Um registro de Distribuição do Docker retorna 401 após a troca de tokens	A credencial emitida pelo adaptador não atende aos requisitos de bearer token do registro.	Verifique o registro service, o repositório scope, o emissor do token, a chave de assinatura e a configuração de confiança.
A conexão do Registro não pode ser encontrada	A conexão existe em um projeto de Foundry diferente ou o nome não corresponde.	Crie a conexão no projeto selecionado e defina registryConnectionId como seu nome exato ou ID de recurso.
A solicitação expira	Foundry não consegue resolver nem acessar o registro ou o endpoint de token.	Verifique o DNS privado, a aprovação do ponto de extremidade privado, as rotas, os firewalls e o TCP 443 de saída para ambos os pontos de extremidade.

Conteúdo relacionado

• Entenda os agentes hospedados.
• Examine as permissões do agente hospedado.
• Configure CI/CD para agentes hospedados.