코딩 에이전트 및 스크립트와 함께 azd ai 사용

중요합니다

이 문서에서 미리 보기로 표시된 항목은 현재 미리 보기로 제공됩니다. 이 미리 보기는 서비스 수준 계약 없이 제공되며 Microsoft 프로덕션 워크로드에 권장하지 않습니다. 특정 기능이 지원되지 않거나 기능이 제한될 수 있습니다. 자세한 내용은 Microsoft Azure Preview에 대한 추가 사용 약관을 참조하세요.

코딩 에이전트와 스크립트에서 사람이 터미널에서 사용하는 것과 동일한 방식으로 azd ai를 사용하세요. 독립 실행형 컨텍스트를 설정하고, 프롬프트를 사용하지 않도록 설정하고, JSON 출력을 구문 분석하고, 신뢰할 수 있는 자동화를 위해 직접 에이전트 엔드포인트를 호출합니다.

사전 요구 사항

설치된 azd Foundry 확장입니다.
인증된 azd 세션입니다.
실행하려는 명령에 대한 Microsoft Foundry 프로젝트 엔드포인트입니다. 자세한 내용은 azd 프로젝트 컨텍스트 설정을 참조하세요.
선택 사항: 에이전트 엔드포인트를 호출해야 하는 경우 배포된 호스트된 에이전트입니다. 설치는 호스트된 에이전트 배포를 참조하세요.

Microsoft Foundry 스킬로 시작하기

코딩 에이전트는 azd ai 관례를 이미 알고 있을 때 가장 잘 작동합니다. Microsoft Foundry Skill은 코딩 에이전트에 그러한 지식을 제공합니다. 즉, 올바른 azd ai 명령과 Foundry 연결 구성을 생성하고, 프로젝트 컨텍스트 설정, --no-prompt 전달, 그리고 구조화된 결과를 위해 --output json 요청과 같은 이 문서의 방식을 적용합니다. 코딩 에이전트를 먼저 해당 스킬에 연결한 다음, 이 문서의 나머지 내용에 있는 패턴을 사용해 에이전트가 생성한 결과물을 검토하고 견고하게 다듬으세요.

프로젝트 컨텍스트를 한 번 설정

모든 리소스 명령(예: connection, toolbox또는skillroutine)을 대상으로 지정하려면 Foundry 프로젝트 엔드포인트가 필요합니다. 자동화에서 세션, CI 작업 또는 코딩 에이전트 호출당 해당 엔드포인트를 한 번 설정한 다음, 나머지 실행에 사용합니다.

두 가지 패턴이 있습니다.

`azd ai project set`로 한 번 고정하기

환경 변수를 내보내지 않고 셸 간에 컨텍스트를 유지하려면 전역 구성에서 설정합니다.

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

azd ai project set <endpoint> 는 URL을 이미 알고 있는 경우 상호작용이 전혀 필요하지 않습니다. azd ai project show는 활성 엔드포인트를 결정한 소스를 확인합니다. 호스트가 어떤 상태에 있는지 확실하지 않은 경우 세션 맨 위에 사용합니다.

환경 변수 설정

스크립트 또는 코딩 에이전트가 실행되는 환경에서 설정합니다 FOUNDRY_PROJECT_ENDPOINT . 모든 azd ai 명령은 프로젝트 내 azd 환경과 전역 구성 다음으로 이를 자동으로 적용합니다.

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

이 패턴은 일반적으로 비밀과 구성이 환경 변수로 이미 도착하며 작업 간에 정리할 전역 상태가 없기 때문에 CI에 적합합니다.

우선 순위 순서를 포함하여 CLI가 엔드포인트를 확인하는 방법에 대한 전체 설명은 azd 프로젝트 컨텍스트 설정을 참조하세요.

프롬프트 사용 안 함

모든 azd ai 명령은 --no-prompt을 허용합니다. 설정하면 대화형 입력을 차단하는 대신 명령이 빠르게 실패합니다. 누락된 필수 인수 또는 그밖의 경우 키 입력을 기다리는 delete 확인은 구조화된 출력에서는 즉시 오류가 됩니다.

항상 CI 및 코딩 에이전트 호출에서 --no-prompt를 설정하세요.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

Tip

--no-prompt 또한 "delete 확인 프롬프트를 건너뛰기"를 의미하므로, 해당 프롬프트 하나만 표시하지 않도록 하기 위해 --force를 사용할 필요는 없습니다.

JSON 출력 가져오기

대부분의 azd ai 명령은 --output json를 지원하며, 여기에는 connection, toolbox, skill, routine 리소스 명령과 azd ai agent show가 포함됩니다. 사람이 읽을 수 있는 텍스트 출력을 스크래핑하는 대신, jq, ConvertFrom-Json, 또는 사용 중인 언어의 JSON 파서를 사용해 결과를 안정적으로 구문 분석하는 데 사용하세요. 이 azd ai agent invoke 명령은 수정되지 않은 서버 응답에 사용합니다 --output raw .

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

텍스트 출력은 사람용이며 릴리스 간에 변경될 수 있습니다. JSON 구조는 안정적인 규약입니다.

멱등하게 리소스 생성하기

create는 upsert가 아닙니다. 명명된 리소스가 이미 있는 경우 다시 실행이 실패합니다. 이 기본값은 한 호출자가 다른 호출자의 상태를 자동으로 덮어쓰지 못하도록 하기 때문에 프로젝트 범위가 지정된 공유 리소스에 적합합니다.

이전 상태와 관계없이 반드시 성공해야 하는 자동화의 경우, connection 명령은 기존 리소스를 대체하기 위해 --force를 허용합니다.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Warning

--force는 연결(ARM PUT)을 대체하며 병합되지 않습니다. 동일한 리소스에 대한 다른 호출자의 편집 내용이 손실될 수 있으므로 공유 리소스에서 신중하게 사용합니다.

몇 가지 필드만 변경하고 다른 모든 항목을 유지하려면 다음을 사용합니다 update. 또는 tool, tag, metadata, key와 같은 전용 컬렉션 하위 명령어를 사용하세요.

파일에서 도구 상자 만들기

기본 제공 도구, 연결 및 스킬을 번들로 묶는 멀티엔트리 도구 상자의 경우 전체 정의를 YAML 파일에 넣고 --from-file를 azd ai toolbox create에 전달합니다. 파일은 해당 AgentSchema 셰이프를 사용합니다.

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file는 호출 시점에 읽는 일회성 입력입니다. CLI는 파일을 추적하거나 다시 읽지 않으므로 명령을 다시 실행하기 전까지는 YAML에 대한 향후 편집 내용이 적용되지 않습니다. 명시적 플래그(--kind, --target, --auth-type및 일치하는 자격 증명 플래그)를 사용하여 연결을 만든 다음 도구 상자 파일에서 이름으로 참조합니다.

azd 프로젝트 없이 배포된 에이전트 호출

코딩 에이전트 또는 스크립트가 작업 디렉터리 --agent-endpoint 외부에 있는 배포된 에이전트를 호출해야 하는 경우 직접 대상으로 지정합니다. 이 접근 방식은 azure.yaml와 활성 azd env를 모두 우회합니다. URL만으로도 충분합니다.

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

한 리포지토리의 CI가 다른 리포지토리가 소유한 에이전트를 호출해야 하거나 MCP 서버가 여러 에이전트를 프런트하고 엔드포인트 URL만 알고 있는 경우 이 셰이프를 사용합니다. 전체 옵션 집합 invoke 은 호스트된 에이전트 호출을 참조하세요.

로컬 실행에 비밀 전달

비밀을 사용해 에이전트를 로컬에서 시작하려면, 해당 비밀을 azd 환경 변수로 설정하고 env에서 azure.ai.agent 서비스용 azure.yaml 맵에서 이를 참조하세요. 값은 .azure/<env>/.env에 있으며, 이 파일은 기본적으로 Git에서 무시됩니다.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

로컬 .env 파일에 두면 안 되는 시크릿은 Foundry 프로젝트 연결에 저장한 다음 ${{connections.<name>.credentials.<field>}} 자리 표시자를 사용해 참조하세요. 전체 로컬 실행 범위는 호스팅된 에이전트를 로컬에서 실행을(를) 참조하세요.

짧은 설정 스크립트 작성

이 bash 스크립트는 위의 패턴을 결합합니다. 프로젝트 컨텍스트를 고정하고, 연결과 도구 상자를 멱등적으로 생성하고, 도구 상자에 도구를 연결하고, JSON을 파싱하여 결과를 확인합니다.

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail는 어느 단계에서든 오류가 발생하면 스크립트가 즉시 실패하게 합니다. --no-prompt와 함께 사용하면 CI 게이트에 적합한 예측 가능한 종료 코드를 얻을 수 있습니다.

엔드포인트 확인 방법 검토

코딩 에이전트는 이 우선 순위 순서를 따라 명령이 대상으로 지정할 Foundry 프로젝트를 예측할 수 있습니다. 값을 생성하는 첫 번째 원본이 우선합니다. 이후 원본은 참조되지 않습니다.

--project-endpoint (또는 -p) 플래그(항상 우선 적용됨).
azd 프로젝트 내: 활성화된 azd env 값.
전역 구성(azd ai project set에 의해 설정됨).
FOUNDRY_PROJECT_ENDPOINT 환경 변수.
azd ai project set을(를) 실행하거나 --project-endpoint을(를) 전달하라는 구조화된 제안과 관련된 오류입니다.

독립 실행형 컨텍스트가 프로젝트 내 작업과 상호 작용하는 방법을 포함하여 전체 설명은 azd 프로젝트 컨텍스트 설정을 참조하세요.

코딩 에이전트 팁 적용

항상 --no-prompt를 전달하고, 이를 지원하는 명령에는 --output json를 추가합니다. 이를 통해 예측 가능한 종료 코드와 구문 분석 가능한 결과를 제공합니다.
호스트가 어떤 상태에 있는지 확실하지 않은 경우 세션 시작 시 확인된 컨텍스트 azd ai project show 를 확인합니다. 비용이 적은 읽기 전용 호출입니다.
실패할 경우 오류 출력에서 구조화된 제안을 구문 분석하여 다음 단계를 결정하는 것이 좋습니다. 예를 들어 "Foundry 프로젝트 엔드포인트가 해결되지 않음" 오류는 다시 시도하기 전에 실행 azd ai project set하거나 설정 FOUNDRY_PROJECT_ENDPOINT해야 했음을 의미합니다.
문제를 진단할 때만 사용합니다 --debug . 파싱하기 어려운 장황한 여러 줄 출력을 생성하며, 애초에 프로그램에서 사용하는 인터페이스로 만들어진 것도 아닙니다.
"이미 존재함" 오류가 발생한 create 실패를 복구 가능한 것으로 처리합니다. 해당 리소스를 교체하려는 경우 --force으로 다시 실행하고, 그 일부만 변경하면 되는 경우에는 update와 collection 하위 명령으로 전환하세요.

CLI가 Foundry 프로젝트 엔드포인트를 확인하는 방법을 이해하도록 azd 프로젝트 컨텍스트를 설정합니다.
파이프라인에서 실행되는 패턴azd ai.
를 비롯한 전체 azd ai agent invoke 옵션을 위해 --agent-endpoint합니다.

피드백

이 페이지가 도움이 되었나요?

2026-06-26 에 마지막으로 업데이트됨