agent.yaml 스키마 참조

중요합니다

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

메모

에이전트 매니페스트(agent.manifest.yaml) 및 독립 실행형 에이전트 정의(agent.yaml)는 더 이상 사용되지 않습니다. Foundry azd 확장(azure.ai.agents 1.0.0-beta.1)을 기준으로 호스트된 모든 에이전트 구성은 단일 azure.yaml에 있습니다. 호스트된 에이전트에 대한 Azure.yaml 작성자 및 호스트된 에이전트에 대한 azure.yaml 참조를 참조하세요.

AgentSchema 사양은 AI 에이전트를 정의하기 위한 개방형 표준입니다. 호스트된 에이전트를 빌드할 때는 주로 AgentDefinition, AgentManifest 및 ContainerAgent의 세 가지 최상위 스키마 유형을 사용합니다. 에 대한 AgentManifestAgentDefinitionagent.manifest.yamlagent.yaml이 레거시 스키마 모델은 참조용으로 유지되며 .azure.yaml 스키마는 하나의 도구에만 국한되지 않습니다. Azure 개발자 CLI(azd)와 Visual Studio Code Microsoft Foundry 도구 키트가 모두 사용합니다.

스키마는 고유한 명명 규칙이 있는 두 개의 파일 컨텍스트에 나타납니다.

• agent.manifest.yaml 는 레거시 샘플에서 사용하는 매개 변수가 있는 템플릿인 AgentManifest입니다. 현재 azd ai agent init -t 초기화에는 azure.yaml 프로젝트 문서가 필요하며 AgentManifest 래퍼를 거부합니다.
• agent.yaml 는 AgentDefinition으로, 레거시 초기화에서 프로젝트에 src/<agent>/agent.yaml쓴 구체적인 구성입니다.

두 파일 모두 에이전트의 모델 , 도구, 프로토콜, 환경 및 리소스를 설명합니다. 이는 azure.yamlAzure 리소스를 프로비전하고 배포하는 방법을 설명하는 고유한 기능입니다. 참조는 azure.yaml호스트된 에이전트에 대한 azure.yaml 참조를 참조하세요.

스키마 형식

AgentDefinition

AgentDefinition은 실행할 준비가 된 에이전트의 구체적인 사양입니다. 특정 구성이 있고 템플릿 자리 표시자가 없는 {{ parameter }} 단일 에이전트 인스턴스를 설명합니다.

모든 AgentDefinition에는 kind 에이전트 유형을 결정하는 필드가 있습니다.

Kind	Description
prompt	지침만을 통해 구성된 프롬프트 기반 에이전트입니다.
hosted	컨테이너 이미지로 배포된 컨테이너화된 에이전트입니다.
workflow	다른 에이전트를 조정하는 오케스트레이션 에이전트입니다.

생성된 AgentDefinition은 여전히 참조를 포함할 ${VAR_NAME} 수 있습니다. 이러한 개체 틀은 azd AgentSchema 사양의 일부가 아닌 환경 변수 자리 표시자입니다. 배포 시 각 환경의 azd 파일에서 값을 확인하여 여러 .azure/<env>/.env 환경에서 단일 정의 파일을 작업할 수 있습니다.

AgentManifest

AgentManifest는 에이전트를 동적으로 만들기 위한 매개 변수가 있는 템플릿입니다. AgentDefinition을 해당 필드로 래핑하고 다음을 template 추가합니다.

• parameters: 대체 구문을 사용하여 {{ parameter }} 생성 시 메시지가 표시되거나 삽입되는 값입니다.
• resources: 모델 배포, 도구 상자 또는 연결과 같은 외부 종속성입니다.

재사용 가능한 템플릿이 필요하거나 구성이 다른 유사한 에이전트를 배포하려는 경우 AgentManifest를 사용합니다. 실행할 azd ai agent init때 일반적으로 템플릿을 선택하거나 URL을 제공하여 매니페스트를 가리킵니다. init 프로세스는 매개 변수 값을 묻는 메시지를 표시하고 AgentDefinition을 생성합니다.

ContainerAgent

ContainerAgent는 .가 있는 kind: hostedAgentDefinition입니다. 컨테이너별 필드를 사용하여 기본 정의를 확장하고 호스트된 에이전트를 template 빌드할 때 AgentManifest 내부입니다.

매니페스트 또는 정의를 사용하는 경우

매니페스트 사용	정의 사용 시
다른 사용자가 인스턴스화할 수 있도록 재사용 가능한 에이전트 템플릿을 게시합니다.	특정 단일 용도 에이전트를 배포합니다.
사용자가 초기화 시 모델, 도구 또는 연결을 구성하도록 합니다.	모든 구성 값이 알려지고 고정됩니다.
샘플 또는 시작 템플릿을 빌드합니다.	이미 실행 azd ai agent init 되었으며 생성된 정의가 있습니다.

대부분의 개발자는 매니페스트 azd ai agent init 에서 시작한 다음 생성된 정의를 사용합니다. 템플릿 작성자 및 샘플 게시자는 매니페스트의 기본 작성자입니다.

최상위 필드

아래 참조는 정의 필드의 상위 집합인 매니페스트 필드를 문서화합니다.

Field	유형	필수	Description
name	string	Yes	에이전트 매니페스트의 이름입니다.
description	string	No	에이전트에 대한 설명입니다.
metadata	object	No	추가 메타데이터(예: tags.
template	ContainerAgent	Yes	에이전트 정의 템플릿입니다.
parameters	object	No	init 중에 메시지가 표시되는 구성 가능한 매개 변수입니다.
resources	배열	Yes	에이전트에 필요한 리소스입니다.

template(ContainerAgent)

template 필드는 호스트된 컨테이너 에이전트를 정의합니다.

Field	유형	필수	Description
name	string	Yes	요원 이름.
kind	string	Yes	호스트된 hosted 에이전트의 경우여야 합니다.
protocols	배열	Yes	프로토콜 지원.
environment_variables	배열	No	컨테이너에 대한 환경 변수입니다.
resources	object	No	컨테이너 CPU 및 메모리 리소스.
image	string	No	미리 빌드된 컨테이너 이미지 경로입니다.
dockerfilePath	string	No	Dockerfile의 경로입니다.

프로토콜

protocols:
  - protocol: responses    # OpenAI Responses API
    version: 2.0.0

Protocol	Description
responses	OpenAI 응답 API. 대화 기록 관리를 포함합니다.
invocations	사용자 지정 페이로드 프로토콜입니다. 기본 제공 대화 관리가 없습니다.

전체 프로토콜 사양은 호스트된 에이전트 런타임 계약을 참조하세요.

environment_variables

environment_variables:
  - name: FOUNDRY_MODEL_NAME
    value: ${FOUNDRY_MODEL_NAME}

구문은 ${ } .에서 azd환경 변수를 참조 .azure/<env>/.env 합니다.

메모

에서 선언 FOUNDRY_PROJECT_ENDPOINT 하지 마세요.environment_variables 플랫폼은 호스팅된 컨테이너에 자동으로 삽입하고 azd ai agent run 로컬 개발을 위해 설정합니다. 여기에 선언하는 것은 중복되며 플랫폼 값을 가리는 위험이 있습니다.

parameters

동안 azd ai agent init매개 변수가 표시됩니다. 중요한 값에 사용합니다 secret: true .

parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token

resources

리소스는 에이전트에 필요한 항목을 정의합니다. 아래 셰이프에서는 매니페스트가 선언하는 내용과 프로젝트에 기록되는 내용을 azd ai agent init 설명합니다. 초기화한 후 런타임에 직접 CLI 명령( , , azd ai connectionazd ai toolbox및 azd ai skill)을 사용하여 동일한 프로젝트 범위 리소스를 관리합니다azd ai routine.

메모

스키마에는 기술 필드가 포함되지 않습니다. azd ai agent init, azd ai agent run및 azd up 명령은 기술을 자동으로 다운로드하지 않습니다. 프로젝트 수준 리소스 azd ai skill 로 기술을 관리하고 에이전트 런타임에 직접 연결합니다.

모델 리소스

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

연결 리소스

resources:
  - kind: connection
    name: MyConnection
    target: https://api.example.com
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ my_api_key }}"

도구 상자 리소스

resources:
  - kind: toolbox
    name: agent-tools
    description: Agent toolbox
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: codeInterpreter
        type: builtin
        capability: code-interpreter
      - name: myMcp
        type: connection
        connection: "{{ MyConnection }}"

도구 상자 버전에는 원시 항목(예tools: 기본 제공 기능 web-search 또는), code-interpreter (원격 도구 MCP 서버 또는 connections검색 인덱스와 같은 프로젝트 연결) 및 skills (기존 프로젝트 기술에 대한 참조) 세 가지 종류의 항목이 포함됩니다. tools 슬롯은 매니페스트에서 앞에 선언됩니다. 연결 및 기술 참조를 증분 방식으로 azd ai toolbox connection add 추가합니다 azd ai toolbox skill add.

전체 예제

name: my-web-search-agent
description: An agent with web search and MCP tools

metadata:
  tags:
    - AI Agent Hosting

template:
  name: my-web-search-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 2.0.0
  environment_variables:
    - name: FOUNDRY_MODEL_NAME
      value: ${FOUNDRY_MODEL_NAME}
    - name: TOOLBOX_ENDPOINT
      value: ${TOOLBOX_ENDPOINT}

parameters:
  github_pat:
    secret: true
    description: GitHub PAT for MCP connection

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

  - kind: connection
    name: GithubMcpConnection
    target: https://api.githubcopilot.com/mcp
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    description: Web search and GitHub MCP tools
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: github
        type: connection
        connection: "{{ GithubMcpConnection }}"

변수 치환

대체는 매니페스트 매개 변수가 초기화 시간에 확인되고 환경 변수가 실행 또는 배포 시 확인되는 두 계층에서 발생합니다. 그런 다음, 하나의 정의 파일이 모든 환경에서 작동할 azd 수 있습니다.

Syntax	해결된 경우	무엇에 의해
{{ param_name }}	azd ai agent init	사용자에게 표시되는 매니페스트 매개 변수 값입니다.
${VAR_NAME}	azd deploy 또는 azd ai agent run	azd에서 환경 변수 .azure/<env>/.env

관련 콘텐츠

• 호스트된 에이전트에 대한 azure.yaml 작성
• 호스트된 에이전트에 대한 azure.yaml 참조
• AgentSchema 사양
• 호스트된 에이전트 런타임 계약
• 호스팅 에이전트란?