Establecer el contexto del proyecto Foundry para los comandos azd

Los comandos azd ai se ejecutan en dos contextos: dentro de un proyecto azd (el flujo de trabajo típico de un equipo) y de forma independiente (trabajo ad hoc, scripts puntuales o invocaciones desde automatización que no tienen un azure.yaml en el que basarse). Ambos modos tienen como destino los mismos recursos de Microsoft Foundry. Solo se diferencian en cómo la CLI determina con qué proyecto de Foundry interactuar. En este artículo, aprenderá el orden de resolución y cómo configurar el contexto independiente.

Requisitos previos

• Se instalaron las extensiones Foundry de Azure Developer CLI.
• Una sesión de Azure autenticada (azd auth login).
• Un extremo existente de un proyecto de Foundry para su uso independiente.

Cuándo usar cada contexto

Los comandos de recursos (azd ai connection, azd ai toolbox, azd ai skilly azd ai routine) funcionan en un único proyecto foundry, por lo que necesitan un punto de conexión de proyecto resuelto desde uno de estos contextos antes de poder ejecutarse.

Algunos comandos azd ai agent requieren un proyecto azd porque operan sobre definiciones de servicio locales. Otros comandos admiten el uso independiente. Por ejemplo, azd ai agent optimize puede tener como destino un agente implementado existente al proporcionar su nombre y resolver el punto de conexión del proyecto Foundry desde la configuración global, una marca explícita o una variable de entorno. Use --agent-endpoint en azd ai agent invoke para llamar a un agente desplegado sin un proyecto azd en disco.

Cómo funciona la resolución de puntos de conexión

Para cada comando que tenga como destino un proyecto foundry, la CLI resuelve el punto de conexión en este orden. El primer origen que devuelve un valor gana y los orígenes posteriores no se consultan:

1. El indicador -p o --project-endpoint del comando. Siempre gana, independientemente del contexto.
2. El entorno activo azd, si te encuentras dentro de un directorio de proyecto azd.
3. Configuración global, debajo de extensions.ai-agents.context.endpoint en ~/.azd/config.json. Esto es lo que azd ai project set escribe.
4. La variable de entorno FOUNDRY_PROJECT_ENDPOINT en el shell actual.
5. Error. La CLI finaliza con una sugerencia estructurada para ejecutar azd ai project set o pasar --project-endpoint.

El punto de conexión es lo único que necesita la CLI. Resuelve el ID de recurso de Azure Resource Manager (suscripción, grupo de recursos, cuenta y proyecto) a partir del punto de conexión en el momento de la invocación, por lo que los comandos funcionan igual tanto si obtienen el punto de conexión de tu entorno como de tu configuración global.

Establecimiento del contexto independiente

El comando azd ai project set escribe el punto de conexión del proyecto Foundry activo en tu configuración global de azd, por lo que los comandos posteriores ejecutados desde cualquier lugar pueden omitir --project-endpoint. El comando toma el punto de conexión como argumento posicional:

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

El comando no es totalmente interactivo cuando se pasa el punto de conexión. Agregue --no-prompt en scripts y CI para que un valor ausente o no resuelto falle de inmediato en lugar de bloquearse:

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

Borrar el contexto independiente

azd ai project unset

Este comando quita todo el bloque context de ~/.azd/config.json. No modifica ningún valor de entorno azd.

Inspeccionar el contexto activo

El azd ai project show comando recorre la cadena de resolución completa e informa del origen que proporcionó el punto de conexión activo. Úselo para confirmar cuáles son los destinos de comando siguientes antes de ejecutarlo:

azd ai project show

Salida de ejemplo cuando el punto de conexión procede de la configuración 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

Dentro de un proyecto azd, la línea Source indica azd env <env-name> en su lugar, y los valores mostrados proceden del archivo .env del entorno en lugar de la configuración global.

Ubicación de almacenamiento

El contexto independiente se encuentra bajo el espacio de nombres extensions.ai-agents en ~/.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"
      }
    }
  }
}

Solo endpoint es canónico. Existen otros campos para que azd ai project show sean legibles. La CLI nunca las lee cuando resuelve un objetivo. Puede editar el archivo manualmente, pero azd ai project set y azd ai project unset son la forma admitida de administrarlo.

Precedencia dentro de un proyecto azd

Dentro de un proyecto azd, el puntos de conexión del proyecto del entorno activo siempre prevalece sobre el contexto global. La ejecución azd ai project set desde dentro de un proyecto sigue actualizando la configuración global, pero la CLI imprime una advertencia de una línea que el entorno sigue teniendo prioridad para los comandos ejecutados desde ese directorio.

Este comportamiento es intencionado. Los valores de entorno a nivel de proyecto forman parte del flujo de trabajo del equipo, mientras que el contexto global es una preferencia de cada máquina. Para anular el entorno para un único comando desde dentro de un proyecto, pasa --project-endpoint o establece FOUNDRY_PROJECT_ENDPOINT en el shell, en lugar de basarte en la configuración global.

Contenido relacionado

• Inicio rápido: Implementación del primer agente hospedado
• Instalación de las extensiones de la CLI de Azure Developer Foundry
• Inicialización de un proyecto de agente hospedado con la CLI para desarrolladores de Azure
• Optimización de un agente existente sin archivos de proyecto de AZD