Defina o contexto do projeto Foundry para os comandos do azd

Os comandos azd ai são executados em dois contextos: dentro de um projeto azd (o fluxo de trabalho típico da equipe) e de forma autônoma (trabalho ad hoc, scripts pontuais ou invocações oriundas de automação que não têm um azure.yaml no qual se basear). Ambos os modos têm como destino os mesmos recursos do Microsoft Foundry. Elas diferem apenas na forma como a CLI determina com qual projeto do Foundry se conectar. Neste artigo, você aprenderá a ordem de resolução e como definir o contexto autônomo.

Pré-requisitos

• As extensões do Azure Developer CLI Foundry instaladas.
• Uma sessão de Azure autenticada (azd auth login).
• Um endpoint de projeto existente do Foundry para uso independente.

Quando usar cada contexto

Os comandos de recurso (azd ai connection, azd ai toolbox, azd ai skill e azd ai routine) atuam sobre um único projeto do Foundry, portanto eles precisam de um endpoint de projeto resolvido a partir de um desses contextos antes de poderem ser executados.

Alguns comandos azd ai agent exigem um projeto azd porque funcionam com definições de serviço locais. Outros comandos dão suporte ao uso autônomo. Por exemplo, azd ai agent optimize pode ter como destino um agente já implantado quando você fornece o nome dele e resolve o endpoint do projeto Foundry a partir da configuração global, de uma flag explícita ou de uma variável de ambiente. Use --agent-endpoint em azd ai agent invoke para chamar um agente implantado sem um projeto azd no disco.

Como funciona a resolução do ponto de extremidade

Para cada comando destinado a um projeto do Foundry, a CLI determina o ponto de extremidade nesta ordem. A primeira fonte que retorna um valor ganha e as fontes posteriores não são consultadas:

1. O sinalizador -p ou --project-endpoint no comando. Sempre vence, independentemente do contexto.
2. O ambiente ativo azd, se você estiver dentro de um diretório do projeto azd.
3. Configuração global, extensions.ai-agents.context.endpoint em ~/.azd/config.json. É isso que azd ai project set escreve.
4. A variável de ambiente FOUNDRY_PROJECT_ENDPOINT no shell atual.
5. Erro. A CLI é encerrada com uma sugestão estruturada para executar azd ai project set ou passar --project-endpoint.

A CLI só precisa do endpoint. Ele determina o ID do recurso do Azure Resource Manager (assinatura, grupo de recursos, conta e projeto) a partir do ponto de extremidade no momento da invocação para que os comandos funcionem da mesma forma, independentemente de terem obtido o ponto de extremidade do seu ambiente ou da sua configuração global.

Defina o contexto independente

O comando azd ai project set grava o endpoint do projeto Foundry ativo na sua configuração global azd, para que os comandos subsequentes executados de qualquer lugar possam omitir --project-endpoint. O comando usa o ponto de extremidade como um argumento posicional:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project

O comando se torna totalmente não interativo quando você fornece o endpoint. Adicione --no-prompt aos scripts e à CI para que um valor ausente ou não resolvido falhe imediatamente em vez de bloquear o processo:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt

Limpar o contexto autônomo

azd ai project unset

Esse comando remove todo o bloco context de ~/.azd/config.json. Ele não altera nenhum valor de ambiente azd.

Inspecionar o contexto ativo

O comando azd ai project show percorre toda a cadeia de resolução e informa qual origem forneceu o endpoint ativo. Use-o para confirmar quais são seus próximos destinos de comando antes de executá-lo:

azd ai project show

Exemplo de saída quando o endpoint vem da configuração global:

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Tenant:            contoso.onmicrosoft.com
Subscription:      Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project:   my-project

Em um projeto azd, a linha Source mostra azd env <env-name>, e os valores exibidos vêm do arquivo .env do ambiente, e não da configuração global.

Local de armazenamento

O contexto autônomo reside no extensions.ai-agents namespace em ~/.azd/config.json:

{
  "extensions": {
    "ai-agents": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "subscription": "00000000-0000-0000-0000-000000000000",
        "tenant": "contoso.onmicrosoft.com",
        "foundryProject": "my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

Só endpoint é canônico. Os outros campos existem para tornar azd ai project show legível. A CLI nunca lê esses itens ao resolver um alvo. Você pode editar o arquivo à mão, mas azd ai project set e azd ai project unset são a forma suportada de gerenciá-lo.

Precedência dentro de um projeto azd

Em um projeto azd, o ponto de extremidade do projeto do ambiente ativo sempre prevalece sobre o contexto global. A execução azd ai project set de dentro de um projeto ainda atualiza a configuração global, mas a CLI imprime um aviso de uma linha de que o ambiente continua tendo precedência para comandos executados a partir desse diretório.

Este comportamento é intencional. Os valores de ambiente no nível do projeto fazem parte do fluxo de trabalho da equipe, enquanto o contexto global é uma preferência por máquina. Para substituir o ambiente por um único comando de dentro de um projeto, passe --project-endpointou defina FOUNDRY_PROJECT_ENDPOINT no shell, em vez de depender da configuração global.

Conteúdo relacionado

• Início Rápido: Implantar seu primeiro agente hospedado
• Instalar as extensões do Foundry da Azure Developer CLI
• Inicializar um projeto de agente hospedado com a CLI do desenvolvedor do Azure
• Otimizar um agente existente sem arquivos de projeto do AZD