중요합니다
이 문서에 표시된 항목(미리 보기)은 현재 퍼블릭 미리 보기에서 확인할 수 있습니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 프로덕션 워크로드에는 권장되지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.
명령은 azd ai 프로젝트 내부(일반적인 팀 워크플로) 및 독립 실행형(임시 작업, 일회성 스크립트 또는 앵커가 없는 azd 자동화의 호출)의 두 가지 컨텍스트 azure.yaml 에서 실행됩니다. 두 모드 모두 동일한 Microsoft Foundry 리소스를 대상으로 합니다. CLI에서 통신할 Foundry 프로젝트를 결정하는 방식만 다릅니다. 이 문서에서는 해결 순서와 독립 실행형 컨텍스트를 설정하는 방법을 알아봅니다.
사전 요구 사항
- Azure 개발자 CLI Foundry 확장이 설치되었습니다.
- 인증된 Azure 세션(
azd auth login)입니다. - 독립 실행형 사용을 위한 기존 Foundry 프로젝트 엔드포인트입니다.
각 컨텍스트를 사용하는 경우
| 컨텍스트 | 어떻게 보이는지 | 사용 시기 |
|---|---|---|
azd 프로젝트에서 |
azure.yaml 및 활성 azd 환경이 있는 디렉터리에서 azd ai ...를 실행합니다. |
추적되는 프로젝트의 일부로 에이전트를 빌드하거나 운영하며, 환경이 대상으로 삼을 Foundry 프로젝트를 결정하도록 하려는 경우입니다. |
| 독립 실행형 | 다른 디렉터리에서 azd ai ...를 실행합니다. |
기존 Foundry 프로젝트를 대상으로 임시 작업을 수행하거나, azd 프로젝트를 소유하지 않는 자동화에서 일회성 작업을 스크립트로 작성합니다. |
리소스 명령(azd ai connection, azd ai toolbox및azd ai skillazd ai routine)은 단일 Foundry 프로젝트에서 작동하므로 실행하려면 이러한 컨텍스트 중 하나에서 프로젝트 엔드포인트를 확인해야 합니다.
명령(예: azd ai agent, run및invoke)은 optimize 독립 실행형이 아닙니다. 이들은 azd 및 환경 해결을 위한 azure.yaml 프로젝트가 필요합니다.
azd ai agent invoke에서 --agent-endpoint를 사용하여 디스크에 azd 프로젝트 없이 배포된 에이전트를 호출합니다.
엔드포인트 확인 작동 방식
Foundry 프로젝트를 대상으로 하는 모든 명령에 대해 CLI는 이 순서대로 엔드포인트를 확인합니다. 값을 반환하는 첫 번째 원본이 우선하며 이후 원본은 참조되지 않습니다.
- 명령의
-p또는--project-endpoint플래그입니다. 컨텍스트에 관계없이 항상 승리합니다. -
azd프로젝트 디렉터리 안에 있는 경우 활성azd환경. - 글로벌 구성,
extensions.ai-agents.context.endpoint에서~/.azd/config.json아래. 이것이azd ai project set가 쓰는 내용입니다. -
FOUNDRY_PROJECT_ENDPOINT현재 셸의 환경 변수입니다. - 오류. CLI는
azd ai project set를 실행하거나--project-endpoint를 전달하라는 구조화된 제안과 함께 종료됩니다.
엔드포인트는 CLI에 필요한 유일한 것입니다. 호출 시 엔드포인트에서 Azure Resource Manager 리소스 ID(구독, 리소스 그룹, 계정 및 프로젝트)를 확인하므로 명령이 사용자 환경 또는 글로벌 구성에서 엔드포인트를 얻었는지 여부에 관계없이 동일하게 작동합니다.
독립 실행형 컨텍스트 설정
이 azd ai project set 명령은 활성 Foundry 프로젝트 엔드포인트를 전역 azd 구성에 기록합니다. 따라서 이후 명령은 어디에서 실행하든 --project-endpoint를 생략할 수 있습니다. 이 명령은 엔드포인트를 위치 인수로 사용합니다.
azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project
엔드포인트를 지정하면 이 명령은 완전히 비대화식으로 실행됩니다. 스크립트와 CI에 --no-prompt를 추가하여 누락되거나 확인할 수 없는 값이 진행을 막는 대신 페일 패스트하게 합니다.
azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
메모
엔드포인트만이 표준입니다. 리소스 명령은 호출 시 엔드포인트에서 구독, 리소스 그룹, 계정 및 프로젝트를 다시 파생합니다.
독립 실행형 컨텍스트 지우기
azd ai project unset
이 명령은 ~/.azd/config.json에서 context 블록 전체를 제거합니다. 어떠한 azd 환경 값도 건드리지 않습니다.
활성 컨텍스트 확인
이 azd ai project show 명령은 전체 해상도 체인을 안내하고 활성 엔드포인트를 제공한 원본을 보고합니다. 이 명령을 사용하여 다음 명령을 실행하기 전에 대상을 확인합니다.
azd ai project show
엔드포인트가 전역 구성에서 제공되는 경우의 샘플 출력:
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
azd 프로젝트 내에서는 Source 줄에 대신 azd env <env-name>라고 표시되며, 표시되는 값은 전역 설정이 아니라 해당 환경의 .env 파일에서 가져옵니다.
스토리지 위치
독립 실행형 컨텍스트는 ~/.azd/config.json에서 extensions.ai-agents 네임스페이스 아래에 있습니다:
{
"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"
}
}
}
}
정식은 endpoint뿐입니다. 다른 필드는 azd ai project show를 읽기 쉽게 하기 위해 존재합니다. CLI는 대상을 확인할 때 그것들을 전혀 읽지 않습니다. 파일을 직접 편집할 수 있지만 azd ai project setazd ai project unset 파일을 관리하는 지원되는 방법입니다.
azd 프로젝트 내 우선 순위
azd 프로젝트 내에서 활성 환경의 프로젝트 엔드포인트는 항상 전역 컨텍스트보다 우선합니다. 프로젝트 내에서 실행 azd ai project set 하면 여전히 전역 구성이 업데이트되지만 CLI는 환경이 해당 디렉터리에서 실행되는 명령에 계속 우선한다는 경고를 한 줄로 출력합니다.
이 동작은 의도적인 동작입니다. Project 수준 환경 값은 팀 워크플로의 일부이지만 전역 컨텍스트는 컴퓨터별 기본 설정입니다. 프로젝트 내부에서 단일 명령에 대해서만 환경을 재정의하려면 전역 구성에 의존하는 대신 --project-endpoint를 전달하거나 셸에서 FOUNDRY_PROJECT_ENDPOINT를 설정하세요.