Set the Foundry project context for azd commands

Important

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

The azd ai commands run in two contexts: inside an azd project (the typical team workflow) and standalone (ad hoc work, one-off scripts, or invocations from automation that has no azure.yaml to anchor on). Both modes target the same Microsoft Foundry resources. They differ only in how the CLI determines which Foundry project to talk to. In this article, you learn the resolution order and how to set the standalone context.

Prerequisites

When to use each context

Context What it looks like Use when
In an azd project You run azd ai ... from a directory that contains azure.yaml and an active azd environment. You build or operate an agent as part of a tracked project and want the environment to govern which Foundry project you target.
Standalone You run azd ai ... from any other directory. You do ad hoc work against an existing Foundry project, or you script one-off operations from automation that doesn't own an azd project.

The resource commands (azd ai connection, azd ai toolbox, azd ai skill, and azd ai routine) operate on a single Foundry project, so they need a project endpoint resolved from one of these contexts before they can run.

Agent commands have different context requirements. Local development requires an azd project. Use --agent-endpoint on azd ai agent invoke for project-free invocation. azd ai agent monitor <name> --session-id <id> also works outside a project with a global project context. Evaluation and optimization commands support explicit agent names and --project-endpoint; check the individual command's help.

How endpoint resolution works

The core project, agent, connection, toolbox, skill, and routine resolvers use the following sources. Individual commands expose different selectors; optional model and fine-tuning extensions have their own configuration commands.

  1. The --project-endpoint flag, on commands that expose it. The -p short form is command-specific; for example, it means --protocol on agent invoke.
  2. FOUNDRY_PROJECT_ENDPOINT from the active azd environment. A persisted value wins. If the key is absent, the azd host can return the shell value at this stage.
  3. Global config, under extensions.ai-projects.context.endpoint in ~/.azd/config.json. This is what azd ai project set writes.
  4. The FOUNDRY_PROJECT_ENDPOINT environment variable in the current shell.
  5. Error. The CLI exits with a structured suggestion to run azd ai project set or pass --project-endpoint.

An explicitly empty persisted environment value prevents the shell fallback at the environment stage. If no endpoint resolves there, the CLI still checks global config, then the shell variable. Invalid endpoint values produce a validation error rather than falling through.

azd ai project show uses the environment selected by azd env select; its endpoint lookup doesn't honor --environment as an override. Use azd env select <name> before inspecting a different environment.

Set the standalone context

The azd ai project set command writes the active Foundry project endpoint to your global azd config, so subsequent commands run from anywhere can omit --project-endpoint. The command takes the endpoint as a positional argument:

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

The command is fully non-interactive when you pass the endpoint. Add --no-prompt in scripts and CI so a missing or unresolved value fails fast instead of blocking:

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

Note

Only the endpoint is canonical. Resource commands re-derive the subscription, resource group, account, and project from the endpoint at call time.

Clear the standalone context

azd ai project unset

This command clears the project context from global config, including the legacy agent-project context when present. It doesn't touch any azd environment values. Running it when no context is set succeeds.

Inspect the active context

The azd ai project show command walks the full resolution chain and reports which source provided the active endpoint. Use it to confirm what your next command targets before you run it:

azd ai project show

Sample output when the endpoint comes from global config:

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Set at:            <timestamp-recorded-by-project-set>

The output includes the endpoint, source, and, for global config, the time it was set. It doesn't report tenant or subscription details. Inside an azd project, an environment-sourced endpoint displays azd env (<env-name>). Use --output json for structured output.

Storage location

The standalone context lives under the extensions.ai-projects namespace in ~/.azd/config.json:

{
  "extensions": {
    "ai-projects": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

The context stores endpoint and setAt. The project extension can migrate the legacy extensions.ai-agents.project.context entry. Use azd ai project set and azd ai project unset to manage the context.

Precedence inside an azd project

Inside an azd project, a nonempty endpoint resolved from the active environment wins over global context. Running azd ai project set from within a project updates global config, not the active environment.

Project-level environment values are part of the team's workflow, while global context is a per-machine preference. To override the environment for a single resource command, pass --project-endpoint where supported. Setting a shell variable doesn't override a persisted environment value.

Configure a project for provisioning

project set selects a global endpoint; it doesn't declare infrastructure. Use project add to add or update the azure.ai.project service in azure.yaml:

azd ai project add --project-id "<project-resource-id>"

Alternatively, use --project-endpoint <endpoint> for an endpoint-only reference, or --new-project to configure a new project. --project-id records both the endpoint and AZURE_AI_PROJECT_ID; an endpoint-only reference doesn't record an ARM resource ID. Use --force to replace a different configured project.

Add a managed model deployment

Before ejecting infrastructure, add a model deployment to the project's inline declaration:

azd ai project deployment add --model OpenAI/gpt-4.1 --name chat
azd provision

Use --version, --sku, --capacity, and --location to select deployment settings. --force permits replacement of a conflicting inline declaration. The add command changes the declaration; azd provision applies it.

To take ownership of infrastructure files, use azd ai project add --infra=bicep or --infra=terraform. Without existing application infrastructure, ejection defaults to infra. When preserving existing application infrastructure, it adds a Foundry layer under infra/foundry; existing layered configurations retain their declared paths.

Inspect local project configuration

Use azd ai project context to inspect the azd project and environment context. Unlike project show, which reports endpoint resolution, context output can include environment values and secrets. Don't share it or commit .azure to source control.

Related content

  • Last updated on