Define o contexto do projeto Foundry para comandos azd

Importante

Os itens assinalados como (pré-visualização) neste artigo estão atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e não a recomendamos para trabalhos em produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.

Os comandos azd ai são executados em dois contextos: dentro de um projeto azd (o fluxo de trabalho típico da equipa) e de forma autónoma (tarefas ad hoc, scripts pontuais ou invocações a partir de automação que não tem qualquer azure.yaml em que se apoiar). Ambos os modos visam os mesmos recursos do Microsoft Foundry. Diferem apenas na maneira como o CLI determina com qual projeto da Foundry comunicar. Neste artigo, aprende a ordem de resolução e como definir o contexto independente.

Pré-requisitos

Quando usar cada contexto

Contexto Aspeto Utilizar quando
Num azd projeto Executa azd ai ... a partir de um diretório que contém azure.yaml e um ambiente azd ativo. Constróis ou operas um agente como parte de um projeto acompanhado e queres que o ambiente governe qual projeto Foundry pretendes.
Autónomo Executa azd ai ... a partir de qualquer outro diretório. Efetua trabalho ad hoc sobre um projeto Foundry existente ou cria operações pontuais através de uma automação que não é proprietária de um projeto azd.

Os comandos de recurso (azd ai connection, azd ai toolbox, azd ai skill, e azd ai routine) operam num único projeto Foundry, pelo que precisam de resolver um endpoint de projeto a partir de um destes contextos antes de poderem ser executados.

Alguns azd ai agent comandos requerem um azd projeto porque operam com base em definições locais de serviço. Outros comandos suportam uso autónomo. Por exemplo, azd ai agent optimize pode ter como alvo um agente já implementado quando fornecer o respetivo nome e determinar o endpoint do projeto Foundry a partir da configuração global, de uma opção explícita ou de uma variável de ambiente. Utilize --agent-endpoint no azd ai agent invoke para chamar um agente implementado sem ter um projeto azd no disco.

Como funciona a resolução dos endpoints

Para cada comando que tenha como alvo um projeto Foundry, a CLI resolve o endpoint nesta ordem. A primeira fonte que devolve um valor vence, e as fontes posteriores não são consultadas:

  1. A opção -p ou --project-endpoint no comando. Ganha sempre, independentemente do contexto.
  2. O ambiente ativo azd, se estiveres dentro do diretório de um projeto azd.
  3. Configuração global, sob extensions.ai-agents.context.endpoint em ~/.azd/config.json. É isto que azd ai project set escreve.
  4. A variável de ambiente FOUNDRY_PROJECT_ENDPOINT na shell atual.
  5. Erro. A CLI termina com uma sugestão estruturada para executar azd ai project set ou fornecer --project-endpoint.

O endpoint é a única coisa de que a CLI precisa. Resolve o ID de recurso do Azure Resource Manager (subscrição, grupo de recursos, conta e projeto) do endpoint no momento da invocação, por isso os comandos funcionam da mesma forma quer tenham obtido o endpoint do teu ambiente ou da tua configuração global.

Defina o contexto independente

O comando azd ai project set guarda o endpoint ativo do projeto Foundry na configuração global azd, pelo que os comandos subsequentes, executados em qualquer local, podem omitir --project-endpoint. O comando toma o ponto final como argumento posicional:

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

O comando é totalmente não interativo quando especifica o endpoint. Adicione --no-prompt nos scripts e na CI para que um valor em falta ou não resolvido falhe imediatamente em vez de bloquear:

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

Note

Apenas o ponto final é canónico. Os comandos de recursos re-derivam a subscrição, o grupo de recursos, a conta e o projeto a partir do endpoint no momento da chamada.

Limpar o contexto autónomo

azd ai project unset

Este comando remove o context bloco inteiro de ~/.azd/config.json. Não afeta quaisquer valores de azd ambiente.

Examinar o contexto ativo

O azd ai project show comando percorre a cadeia de resolução total e reporta qual fonte forneceu o endpoint ativo. Usa-o para confirmar o que o teu próximo comando tem como alvo antes de o executares:

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

Num projeto azd, a linha Source passa a ser azd env <env-name> em vez de, e os valores apresentados vêm do ficheiro .env do ambiente, em vez da configuração global.

Local de armazenamento

O contexto autónomo reside sob o 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íveis. O CLI nunca os lê ao resolver um alvo. Pode editar o ficheiro à mão, mas azd ai project set e azd ai project unset são a forma suportada de o gerir.

Precedência dentro de um projeto azd

Num projeto azd, o endpoint do projeto do ambiente ativo tem sempre prioridade sobre o contexto global. Executar azd ai project set a partir de dentro de um projeto continua a atualizar a configuração global, mas a CLI imprime um aviso de uma linha de que o ambiente continua a ter prioridade para comandos executados a partir desse diretório.

Este comportamento é intencional. Os valores de ambiente ao nível do projeto fazem parte do fluxo de trabalho da equipa, enquanto o contexto global é uma preferência definida por máquina. Para sobrescrever o ambiente para um único comando dentro de um projeto, forneça --project-endpoint ou defina FOUNDRY_PROJECT_ENDPOINT no shell, em vez de recorrer à configuração global.

Conteúdo relacionado

  • Last updated on