서버리스 에이전트 런타임 참조

이 글은 Azure Functions 서버리스 에이전트 런타임에 대한 구성 참고 자료를 제공합니다. 런타임에 대한 개요와 언제 사용해야 하는지에 대한 지침은 Azure Functions의 Serverless agents runtime을 참조하세요.

Important

서버리스 에이전트 런타임은 현재 미리보기 단계입니다. 기능, 구성 이름 및 지원되는 커넥터는 일반 공급 전에 변경할 수 있습니다.

에이전트 파일 참조

에이전트 파일(.agent.md)은 YAML 프론트 매터를 사용하여 에이전트를 구성하고, 이어서 마크다운 명령어가 이어집니다.

전면 물질 장

다음 프런트 매터 필드를 사용하여 에이전트를 구성합니다.

Field	필수	Description
`name`	Yes	에이전트의 표시 이름입니다.
`description`	Yes	에이전트가 수행하는 작업 및 사용 시기에 대한 간단한 설명입니다.
`trigger`	네(활성화되어 있지 않은 한 `builtin_endpoints` )	에이전트를 호출하는 방법을 정의합니다. 에이전트 파일당 하나의 트리거만 허용됩니다.
`builtin_endpoints`	No	기본 제공 디버그 및 컴퍼지션 엔드포인트를 사용하도록 설정합니다. 모든 기본 제공 엔드포인트를 사용하도록 설정하려면 `true`를 사용하거나 `debug_chat_ui`, `chat_api`, `mcp`를 개별적으로 구성하세요. `debug_chat_ui: true` 또한 내장 UI가 해당 API를 호출하기 때문에 백업 `chatchatstream`및 엔드포인트 경로 도 활성화됩니다.
`input_schema`	No	HTTP 트리거 에이전트에 대한 HTTP 요청 본문의 유효성을 검사하는 데 사용되는 JSON 스키마입니다.
`logger`	No	에이전트에 대해 런타임 로깅을 사용할 수 있는지 여부를 제어합니다. 기본값은 `true`입니다.
`mcp`	No	에서 `mcp.json`검색된 MCP 서버에 대한 액세스를 제어합니다. 이 에이전트에 대해 MCP 서버를 사용하지 않도록 설정하거나 특정 서버를 제거하는 데 사용합니다 `falseexclude` .
`metadata`	No	사용자 고유의 조직 또는 도구에 대한 사용자 지정 메타데이터입니다.
`model`	No	`agents.config.yaml` 또는 앱 설정에 구성된 기본 모델을 재정의합니다.
`response_example`	No	HTTP 트리거 에이전트의 구조적 응답을 안내하는 데 사용되는 응답 셰이프 예제입니다.
`response_schema`	No	HTTP 트리거 에이전트에서 반환된 구조적 응답의 유효성을 검사하는 데 사용되는 JSON 스키마입니다.
`skills`	No	발견한 기술에 대한 접근을 통제합니다. 이 에이전트에 대한 기술을 사용하지 않도록 설정하거나 특정 기술을 제거하는 데 사용합니다 `falseexclude` .
`substitute_variables`	No	환경 변수 치환이 앞문과 명령어에 적용되는지 제어합니다. 기본값은 `true`입니다.
`system_tools`	No	에이전트가 샌 드박스 실행 같은 설정된 시스템 도구에서 옵트아웃할 수 있게 해줍니다.
`timeout`	No	기본 실행 시간 제한(초)을 재정의합니다.
`tools`	No	발견된 맞춤형 Python 도구에 대한 접근을 제어합니다. 이 에이전트에 대한 사용자 지정 도구를 사용하지 않도록 설정하거나 특정 도구를 제거하는 데 사용합니다 `falseexclude` .

트리거 구성

각 에이전트 파일은 앞부분의 trigger 객체에 정의된 하나의 트리거를 지원합니다.

Field	필수	Description
`type`	Yes	트리거 바인딩 타입입니다. 허용된 값은 지원되는 타입 표 를 참조하세요.
`args`	형식에 따라 다름	어떤 이벤트가 에이전트를 시작하는지 설정하는 트리거별 설정입니다.

지원되는 트리거 유형

다음 표는 지원되는 trigger.type 값, 필요한 args값, 그리고 타입별 전체 참조 링크들을 나열합니다:

`trigger.type`	필수 `args`	Reference
`http_trigger`	`route`	HTTP 트리거
`timer_trigger`	`schedule`	타이머 트리거
`queue_trigger`	`queue_name`, `connection`	큐 트리거
`blob_trigger`	`path`, `connection`	Blob 트리거
`event_grid_trigger`	(없음)	Event Grid 트리거
`event_hub_message_trigger`	`event_hub_name`, `connection`	이벤트 허브 트리거
`service_bus_queue_trigger`	`queue_name`, `connection`	Service Bus 큐 트리거
`service_bus_topic_trigger`	`topic_name`, , `subscription_nameconnection`	Service Bus 주제 트리거
`cosmos_db_trigger`	`connection`, , `database_namecontainer_name`	Cosmos DB 트리거
`cosmos_db_trigger_v3`	`database_name`, , `collection_nameconnection_string_setting`	코스모스 DB 트리거 v3
`sql_trigger`	`table_name`, `connection_string_setting`	SQL 트리거
`mysql_trigger`	`table_name`, `connection_string_setting`	MySQL 트리거
`kafka_trigger`	`topic`, `broker_list`	카프카 트리거
`dapr_binding_trigger`	`binding_name`	Dapr 바인딩 트리거
`dapr_service_invocation_trigger`	`method_name`	Dapr 서비스 호출 트리거
`dapr_topic_trigger`	`pub_sub_name`, `topic`	Dapr 주제 트리거
`generic_trigger`	`type` (제본식 명칭)	제네릭 트리거
`connector_trigger`	커넥터 네임스페이스에서 설정됨.	커넥터 트리거

트리거 예시

다음 예시들은 일반적인 트리거 구성을 보여줍니다:

타이머 트리거 ( 매일 오후 3:00 UTC에 작동):

trigger:
  type: timer_trigger
  args:
    schedule: "0 0 15 * * *"

HTTP 트리거:

trigger:
  type: http_trigger
  args:
    route: summarize
    auth_level: FUNCTION

큐 트리거:

trigger:
  type: queue_trigger
  args:
    queue_name: work-items
    connection: AzureWebJobsStorage

블롭 트리거:

trigger:
  type: blob_trigger
  args:
    path: uploads/{name}
    connection: AzureWebJobsStorage

앱 전체 구성 (agents.config.yaml)

모든 에이전트가 상속할 수 있는 앱 전체 런타임 기본값에 사용합니다 agents.config.yaml . 런타임은 이 파일 없이 앱을 로드할 수 있습니다. 모델 배포, 시간 제한 또는 샌드박스 실행 엔드포인트와 같은 공유 설정이 필요할 때 추가합니다.

이 파일은 하나의 앱 수준 입력입니다. 또한 런타임은 mcp.json에서 MCP 서버를, skills/에서 스킬을, 그리고 tools/에서 사용자 지정 Python 도구를 찾아냅니다. 이러한 기능은 기본적으로 에이전트에서 사용하도록 설정됩니다. 에이전트 전면 문제는 런타임 기본값을 재정의하거나 상속된 MCP 서버, 기술 및 도구를 필터링할 수 있습니다.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

개별 에이전트는 자체 프런트 매터에서 지원되는 런타임 설정을 재정의할 수 있습니다.

구성 필드

다음에서 이러한 최상위 필드를 사용합니다.agents.config.yaml

Field	필수	Description
`model`	No	자체 프론트 매터에서 `model`를 설정하지 않은 에이전트에 사용되는 기본 모델 또는 모델 배포입니다.
`timeout`	No	기본 실행 시간 제한(초)입니다. 런타임 기본값은 900초입니다.
`system_tools.dynamic_sessions_code_interpreter.endpoint`	샌드박스 실행 사용 시	샌드박스 도구에서 사용하는 Azure Container Apps 동적 세션 풀에 대한 관리 엔드포인트입니다.
`system_tools.dynamic_sessions_code_interpreter.client_id`	No	세션 풀을 호출하는 데 사용되는 관리 ID의 클라이언트 ID입니다.
`tools.exclude`	No	`tools/` 폴더에서 검색된 사용자 지정 Python 도구에 대한 전역 제외 목록입니다.

해결 순서

런타임은 먼저 에이전트 프런트 매터의 값을 확인하고 앱 agents.config.yaml설정 및 런타임 기본값을 확인합니다. 문자열 값은 agents.config.yaml 앱 설정(예: $AZURE_OPENAI_DEPLOYMENT 또는 $ACA_SESSION_POOL_ENDPOINT.)을 참조할 수 있습니다.

모델, 시간 제한 및 시스템 도구의 기본값을 유지합니다 agents.config.yaml. 커넥터 네임스페이스의 MCP 서버 엔드포인트를 비롯한 원격 MCP 서버 정의를 유지합니다 mcp.json.

변수 치환

런타임은 앱 설정 및 환경 변수를 에이전트 전면 문제, 에이전트 명령 본문 agents.config.yaml및 mcp.json의 문자열 값으로 대체할 수 있습니다.

치환 작업에는 런$SETTING_NAME타임에서 같은 방식으로 처리되는 또는 를 사용할 %SETTING_NAME% 수 있습니다. 변수 이름은 문자 또는 밑줄로 시작해야 하며 문자, 숫자 및 밑줄을 포함할 수 있습니다.

model: $FOUNDRY_MODEL
system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: %ACA_SESSION_POOL_ENDPOINT%

Email the summary to $TO_EMAIL.

{
  "servers": {
    "office365": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL"
    }
  }
}

교체 규칙:

객체나 리스트에 중첩된 문자열 값을 포함해 적용됩니다. 오브젝트 키에는 적용되지 않습니다.
에이전트 명령 본문의 펜스 코드 블록은 대체되지 않으므로 예제에는 리터럴 $VALUE 또는 %VALUE% 텍스트가 포함될 수 있습니다.
대체 콘텐츠에서 문자 그대로의 자리 표시자를 사용 $$SETTING_NAME 하거나 %%SETTING_NAME%% 사용하세요.
빠진 변수들은 변경되지 않습니다. 빈 값은 빈 문자열로 해결됩니다.
교체는 한 번의 패스입니다. 구문은 ${SETTING_NAME} 지원되지 않습니다.
한 에이전트의 대체를 비활성화하려면 에이전트 파일에서 설정 substitute_variables: false 하세요. 이것은 또는 agents.config.yaml에서의 mcp.json 치환을 비활성화하지 않습니다.

MCP 서버 구성 (mcp.json)

앱에서 원격 MCP 서버를 사용하는 경우 함수 앱 프로젝트의 루트에 추가 mcp.json 합니다. 런타임은 이 파일에서 원격 HTTP 또는 스트리밍 가능한 HTTP MCP 서버를 검색하고 에이전트별 필터에 따라 해당 도구를 에이전트에서 사용할 수 있도록 합니다.

서버 입력 필드

각 servers 항목에서 다음 필드를 사용합니다.

Field	필수	Description
`type`	Yes	사용 `http` 또는 `streamable-http`. 로컬 `stdio` MCP 서버는 런타임에서 지원되지 않습니다.
`url`	Yes	원격 MCP 서버 엔드포인트. 환경 변수 대체가 지원됩니다.
`headers`	No	일반 원격 MCP 서버에 대한 정적 헤더입니다. 에 정적 비밀을 `mcp.json`저장하지 마세요.
`auth.scope`	Microsoft Entra 인증을 사용하는 경우	MCP 서버 호출을 인증하는 데 사용되는 Microsoft Entra 토큰 범위.
`auth.client_id`	No	이 MCP 서버로 인증할 때 사용할 관리 ID의 클라이언트 ID입니다. Azure 함수 앱의 시스템 할당 관리 ID를 사용하려면 이 필드를 생략합니다.

Authentication

에이전트가 커넥터 네임스페이스에서 관리되는 MCP 서버를 사용하는 경우 Azure API Hub 범위를 사용합니다. 에 사용자 비밀을 mcp.json저장하지 마세요.

{
  "servers": {
    "office365-outlook": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL",
      "auth": {
        "scope": "https://apihub.azure.com/.default",
        "client_id": "$O365_MCP_CLIENT_ID"
      }
    }
  }
}

이 설정은 auth.client_id MCP 서버에서 인증하는 관리 ID를 선택합니다. 사용자가 할당한 관리 ID의 클라이언트 ID로 설정합니다. Azure 함수 앱의 시스템 할당 관리 ID를 사용하도록 생략합니다. 선택한 ID 또는 로컬로 실행할 때 로컬 개발자 ID는 MCP 서버를 호출할 수 있어야 합니다.

Azure 커넥터

커넥터를 사용하면 에이전트가 사용자 지정 API 클라이언트 코드 없이 외부 서비스로 작업할 수 있습니다. 예를 들어 Microsoft 365 Outlook 커넥터는 전자 메일을 보낼 수 있고, Teams 커넥터는 메시지로 작업할 수 있으며, 다른 커넥터는 Salesforce, SAP 또는 SQL과 같은 시스템에서 작업을 호출할 수 있습니다. 커넥터 네임스페이스는 앱에서 이러한 통합을 사용할 수 있도록 하는 연결, 트리거 및 MCP 서버를 호스트합니다.

서버리스 에이전트 앱에서 커넥터 기능을 사용하려면 먼저 커넥터 네임스페이스 자원을 생성하고, 서비스에 연결을 생성한 뒤 그 연결을 승인합니다. 그런 다음 에이전트에서 연결을 사용하는 방법을 선택합니다.

커넥터는 연결된 서비스에서 새 전자 메일, Teams 메시지 또는 일정 이벤트와 같은 문제가 발생할 때 에이전트를 시작합니다. 이를 사용하려면 커넥터 네임스페이스에서 권한 있는 연결을 사용하는 트리거를 만든 다음 해당 커넥터 트리거 정의의 트리거 이름 및 인수를 사용하여 에이전트를 구성합니다.
커넥터 MCP 도구를 사용하면 에이전트가 전자 메일 보내기 또는 레코드 업데이트와 같은 서비스 작업을 호출할 수 있습니다. 이를 사용하려면 커넥터 네임스페이스에 권한 있는 연결을 사용하는 MCP 서버를 만든 다음 MCP 서버 엔드포인트를 추가합니다 mcp.json.

자세한 내용은 Use connectors in Azure Functions를 참조하세요.

기술

재사용 가능한 프롬프트 자산 skills/을 . 아래에 저장합니다. 필요한 경우 도메인별 지침을 사용할 수 있도록 하면서 기본 에이전트 지침을 작게 유지하는 데 도움이 됩니다. 런타임은 에이전트 기술 형식을 사용합니다.

스킬 포맷

런타임은 함수 앱 프로젝트 루트에서 skills/를 검색하고, SKILL.md를 포함하는 폴더를 재귀적으로 찾습니다.

skills/
  incident-response/
    SKILL.md
    triage-checklist.md
    escalation-policy.md

파일에는 SKILL.md YAML 앞부분과 마크다운 명령어가 포함되어 있습니다.

---
name: incident-response
description: Triage production incidents, summarize impact, and recommend next steps. Use when the task mentions incidents, outages, alerts, or severity levels.
---

Follow the incident response checklist in [triage-checklist.md](triage-checklist.md).

저작 규칙

에이전트 파일 및 기타 프로젝트 리소스를 생성할 때 다음 지침을 따르세요:

모든 기술 폴더에는 SKILL.md 파일이 포함되어야 합니다.
name 필드와 description 필드가 필요합니다.
스킬 이름은 소문자, 숫자, 단일 하이픈을 사용하세요. 공백, 밑줄, 대문자, 선행 하이픈, 후행 하이픈 또는 반복되는 하이픈을 사용하지 마세요.
기술 이름은 앱 전체에서 고유해야 합니다.
설명은 기술이 수행하는 작업과 에이전트에서 사용해야 하는 시기를 모두 설명해야 합니다. 런타임은 에이전트가 전체 기술을 로드할 시기를 결정할 수 있도록 먼저 기술 이름과 설명을 로드합니다.
기술에는 동일한 기술 폴더에 여러 markdown 파일이 포함될 수 있습니다. 상대 링크를 사용하여 SKILL.md에서 지원용 Markdown 파일을 참조하세요.
서버리스 에이전트 런타임은 스킬 콘텐츠로 마크다운 파일만을 지원합니다. 실행 파일이 필요하다면, 그 코드를 커스텀 Python 도구로 패키징하고 기술 설명서에 있는 도구의 이름을 참조하세요.

에이전트별 필터링 기술

에이전트는 기본적으로 검색된 모든 기술을 상속합니다. 특정 에이전트가 사용하지 않아야 하는 경우 에이전트 파일에서 기술을 사용하지 않도록 설정하거나 제외합니다.

skills: false

skills:
  exclude:
    - incident-response

샌드박스 실행

코드 실행 또는 브라우저 자동화의 경우 런타임은 Azure Container Apps 동적 세션 사용할 수 있습니다. 동적 세션은 세션 풀에서 격리된 환경을 제공합니다. 런타임은 코드 인터프리터 세션을 사용하여 에이전트에 도구를 제공합니다 execute_python .

Configuration

agents.config.yaml에서 샌드박스 실행을 구성합니다:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requirements

세션 풀은 --container-type PythonLTS 사용하여 만든 풀과 같은 Python 코드 인터프리터 세션 풀이어야 합니다.
값은 endpoint 세션 풀 관리 엔드포인트입니다.
Azure에서는 함수 앱이 사용하는 관리 신원이 세션 풀에서 코드를 실행하는 데 필요한 역할 할당을 가져야 합니다. Azure Container Apps 코드 인터프리터 세션에는 세션 풀의 Azure ContainerApps Session Executor 및 Contributor 역할이 필요합니다.
로컬로 실행하는 경우 개발자 ID는 세션 풀에 대한 동일한 필수 액세스 권한이 있어야 합니다.
샌드박스 실행을 위해 사용자 할당 관리 ID를 사용하려면 필요한 역할 할당이 있는 ID의 클라이언트 ID로 설정합니다 system_tools.dynamic_sessions_code_interpreter.client_id . 이 설정이 설정되지 않은 경우 런타임은 기본 자격 증명 체인을 사용합니다 AZURE_CLIENT_ID.

샌드박스 도구는 격리된 세션에서 Python 실행됩니다. 변수, 가져오기 및 파일은 동일한 에이전트 세션의 도구 호출에서 지속될 수 있습니다. 에이전트 세션 ID를 사용할 수 없는 경우 런타임은 새 샌드박스 세션을 사용하므로 관련 없는 실행이 상태를 공유하지 않습니다.

에이전트별로 비활성화

에이전트는 전역적으로 구성된 경우 샌드박스 실행을 상속합니다. 에이전트 파일에서 특정 dynamic_sessions_code_interpreter 에이전트 false 의 실행을 비활성화할 수 있습니다.

system_tools:
  dynamic_sessions_code_interpreter: false

사용자 지정 Python 도구

런타임 내장 기능이 포함되지 않는 앱별 로직이 필요할 때는 맞춤형 Python 도구를 사용하세요. 커스텀 도구는 샌드박스 세션이 아니라 함수 앱 프로세스에서 실행됩니다.

도구 발견

함수 앱 프로젝트 루트의 tools/ 폴더에 도구 파일을 추가합니다.

tools/
  submit_ticket.py
  lookup_customer.py

런타임은 .py에서 파일 이름이 tools/로 시작하지 않는 _ 파일을 찾습니다. 현재 미리 보기에서 런타임은 각 파일에서 지원되는 첫 번째 도구를 등록합니다. 파일당 하나의 도구를 사용하여 검색을 예측 가능하게 유지합니다.

정의 도구

런타임 패키지에서 함수를 @tool 장식하여 도구를 정의합니다:

from azure_functions_agents import tool


@tool(name="submit_ticket", description="Create a support ticket with a title and summary.")
async def submit_ticket(title: str, summary: str) -> str:
    return f"Created ticket for {title}: {summary}"

보다 풍부한 매개 변수 설명 및 유효성 검사를 위해 Pydantic 모델을 도구 스키마로 사용합니다.

from pydantic import BaseModel, Field
from azure_functions_agents import tool


class LookupCustomerParams(BaseModel):
    customer_id: str = Field(description="Customer identifier from the CRM system.")


@tool(schema=LookupCustomerParams, description="Look up customer details by customer ID.")
async def lookup_customer(params: LookupCustomerParams) -> str:
    return f"Customer details for {params.customer_id}"

데코레이터 없이 일반 Python 함수를 정의할 수도 있습니다. 런타임은 파일에서 찾은 첫 번째 일반 함수를 래핑하고, 함수 이름을 도구 이름으로 사용하고, 문서 문자열을 도구 설명으로 사용합니다.

def summarize_order(order_id: str) -> str:
    """Summarize an order by order ID."""
    return f"Summary for order {order_id}"

도구 이름, 설명, 형식 힌트 및 Pydantic 필드 설명은 모델이 도구를 호출하는 시기와 방법을 결정하는 데 도움이 됩니다. Azure Functions 앱의 다른 Python 코드와 마찬가지로 사용자 지정 도구에서 사용하는 패키지 종속성을 requirements.txt에 추가하세요.

에이전트별 필터링 도구

에이전트는 기본적으로 검색된 사용자 지정 도구를 상속합니다. 특정 에이전트가 사용하지 않아야 하는 경우 에이전트 파일에서 사용자 지정 도구를 사용하지 않도록 설정하거나 제외합니다.

tools: false

tools:
  exclude:
    - submit_ticket

모델 제공자 구성

런타임은 Microsoft 에이전트 프레임워크를 사용하여 모델 공급자를 호출합니다. 미리 보기 지원에는 Azure OpenAI, Azure AI Foundry 및 OpenAI가 포함됩니다.

공급자 선택

채팅 클라이언트를 생성하려면 런타임에 최소 하나의 제공자 신호를 설정해야 합니다. 그 설정을 사용 AZURE_FUNCTIONS_AGENTS_PROVIDER 해 명시적으로 공급자를 설정할 수도 있고, 다른 앱 설정에서 런타임이 공급자를 추론하도록 할 수도 있습니다.

다음 제공자 설정을 사용하세요:

Provider	`AZURE_FUNCTIONS_AGENTS_PROVIDER` 값	필수 설정	선택적 설정	모델 설정 행동
Azure AI Foundry (에이아이 파운드리)	`foundry`	`FOUNDRY_PROJECT_ENDPOINT`	`AZURE_CLIENT_ID` 사용자 지정 관리 신원을 원할 때	Foundry 프로젝트가 사용해야 할 모델 배포 이름으로 설정 `FOUNDRY_MODEL` 하세요.
Azure OpenAI	`azure_openai`	`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT`	`AZURE_OPENAI_API_KEY` `AZURE_OPENAI_API_VERSION`, , `AZURE_CLIENT_ID` 사용자가 지정한 관리 식별자를 원할 때	Azure OpenAI 배포 이름으로 설정 `AZURE_OPENAI_DEPLOYMENT` 하세요.
OpenAI	`openai`	`OPENAI_API_KEY`	없음	에이전트나 런타임 구성에서 모델을 통과하지 않을 때는 OpenAI 모델 이름으로 설정 `AZURE_FUNCTIONS_AGENTS_MODEL` 하세요.

를 설정 AZURE_FUNCTIONS_AGENTS_PROVIDER하지 않으면 런타임은 다음 순서로 제공자를 자동으로 감지합니다:

AZURE_OPENAI_ENDPOINTAzure OpenAI를 선택.
FOUNDRY_PROJECT_ENDPOINTAzure AI Foundry를 선택한다.
OPENAI_API_KEY OpenAI를 선택한다.

자동 감지에 의존할 때는, 제공자를 식별한 제공자 특화 설정에 제공자가 요구하는 모델 설정이 함께 있어야 합니다. 예를 들어, 여전히 , FOUNDRY_PROJECT_ENDPOINTFOUNDRY_MODEL, AZURE_OPENAI_ENDPOINT , 그리고 여전히 필요합니다 AZURE_OPENAI_DEPLOYMENT.

AZURE_FUNCTIONS_AGENTS_MODEL 는 런타임 전체 대체 모델링 설정입니다. 유효한 가치는 활성 제공자에 따라 달라집니다:

Azure AI Foundry의 경우, Foundry 프로젝트에 존재하는 모델 배포 이름(예: gpt-5.4.)을 사용하세요.
Azure OpenAI의 경우, 의도적으로 런타임 전체 백업을 원할 때만 배포 이름을 사용하세요. 대부분의 앱에서는 대신 설정 AZURE_OPENAI_DEPLOYMENT 하세요.
OpenAI의 경우, OpenAI API에서 수락하는 모델명, 예를 gpt-4o-mini들어 .

모델 우선 순위

모델 선택에서는 다음과 같은 일반적인 우선 순위를 사용합니다.

에이전트 또는 런타임 호출에서 요청한 모델입니다.
공급자별 설정(예: AZURE_OPENAI_DEPLOYMENT 또는 FOUNDRY_MODEL.
모델은 에서 AZURE_FUNCTIONS_AGENTS_MODEL집합했습니다.
활성 공급자의 내장 기본 모델입니다.

관리 아이디 구성

런타임은 Microsoft Entra 인증을 지원하는 Azure 리소스에 연결할 때 관리 신원을 사용합니다. 앱의 기본 신원 선택기로 사용 AZURE_CLIENT_ID 하거나, 더 세밀한 제어를 위해 기능별 설정을 사용할 수 있습니다:

런타임 기능	ID 설정	후퇴¹
Azure OpenAI model provider²	`AZURE_CLIENT_ID`	`DefaultAzureCredential`
Azure AI Foundry 모델 공급자	`AZURE_CLIENT_ID`	`DefaultAzureCredential`
Azure Container Apps 동적 세션 샌드박스	`system_tools.dynamic_sessions_code_interpreter.client_id`	`AZURE_CLIENT_ID`, 그럼 `DefaultAzureCredential`
커넥터 네임스페이스에서 호스트되는 MCP 서버	`auth.client_id`의 서버 항목에 있는 `mcp.json` 값	`AZURE_CLIENT_ID`, 그럼 `DefaultAzureCredential`
블롭 기반 세션^{역사 3}	`AzureWebJobsStorage__clientId`	`AZURE_CLIENT_ID`, 그럼 `DefaultAzureCredential`

식별 설정이 설정되지 않은 경우, 런타임은 DefaultAzureCredential을 사용하며, 이는 Azure에서 시스템 할당된 관리 식별자와 로컬에서는 개발자 식별자(Azure CLI 또는 Visual Studio)로 해석됩니다.
Azure OpenAI에서 API 키를 구성할 때(를 사용), AZURE_OPENAI_API_KEY모델 제공자는 관리 신원 대신 키를 사용합니다. 자세한 내용은 Azure OpenAI 확장 for Azure Functions를 참조하세요.
세션 히스토리는 Azure Functions 호스트와 동일한 기본 호스트 스토리지 식별 설정을 사용합니다. AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri, 및 AzureWebJobsStorage__clientId를 사용하여 Blob 기반 기록에 대한 ID 기반 저장소를 구성합니다. 런타임은 세션 기록에 별도의 에이전트별 ID 설정을 사용하지 않습니다. 자세한 내용은 Functions 개발자 가이드의 Define connections 항목을 참조하세요.

기본 제공 엔드포인트

런타임은 에이전트가 프론트 매터의 설정을 통해 builtin_endpoints 옵트인할 때 선택적 내장 엔드포인트를 노출합니다. 이 엔드포인트들은 개발, 테스트, 진단에 유용합니다. 이들은 주요 생산 애플리케이션 인터페이스로 설계된 것이 아닙니다.

에이전트의 프론트 매터에 내장된 엔드포인트를 활성화하세요:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

설정은 debug_chat_ui: true 또한 API chat 를 활성화 chatstream 하는데, UI가 API에 의존하기 때문입니다. 디버그 UI 없이 프로그래밍 채팅 접근을 원할 때 자동으로 설정 chat_api: true 하세요.

엔드포인트 경로

<AGENT_NAME> 경로 세그먼트는 표시 .agent.md 필드가 아니라 name 파일 이름에서 가져옵니다. 예를 들어, main.agent.md에서는 /agents/main/을 사용합니다.

표면	경로	핵심 요구사항
채팅 UI	`/agents/<AGENT_NAME>/`	기능 키(브라우저에서 프롬프트됨).
HTTP 채팅 API	`POST /agents/<AGENT_NAME>/chat`	함수 키입니다.
스트리밍 채팅 API	`POST /agents/<AGENT_NAME>/chatstream`	함수 키입니다.
MCP 엔드포인트	`/runtime/webhooks/mcp`	`mcp_extension` 시스템 키입니다.

키 꺼내기

Azure에서 채팅 UI를 호스팅할 때, 메시지를 보내기 전에 함수 키를 입력하라는 요청을 합니다. HTTP 채팅 API를 직접 호출할 때 키를 사용할 수 있습니다.

다음 az functionapp keys list 명령어를 사용하여 앱의 기본 기능 키를 불러옵니다:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "functionKeys.default" \
  --output tsv

이 예시에서는 그룹 이름과 앱 이름으로 와 <RESOURCE_GROUP> 를 바꾸 <FUNCTION_APP_NAME> 세요. 반환된 키를 헤더에 x-functions-key 포함시키거나, code 엔드포인트로 보내는 HTTP 요청에 쿼리 문자열 매개변수를 포함할 수 있습니다.

MCP 클라이언트에 연결할 때는 다음 명령어를 사용하여 MCP 확장 시스템을 요청하세요:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "systemKeys.mcp_extension" \
  --output tsv

MCP 엔드포인트는 이 시스템 키를 필요로 합니다.

채팅 API 요청 흐름

두 내장 채팅 API 모두 다음과 같은 필드를 가진 prompt JSON 본문을 기대합니다:

{
  "prompt": "Summarize today's failures."
}

JSON 응답 하나가 필요할 때 사용 POST /agents/<AGENT_NAME>/chat 하세요. 응답체는 , , session_id그리고 response를 포함한다tool_calls. 런타임은 응답 헤더에 동일한 세션 ID를 에코 응답합니다 x-ms-session-id .

Server-Sent 이벤트(SSE)를 원할 때 사용 POST /agents/<AGENT_NAME>/chatstream 하세요. 스트림은 해결된 세션 ID를 포함하는 이벤트로 session 시작하고, 그 다음에 0개 이상의 delta, intermediate, , tool_start, tool_end 이벤트가 이어지며, 또는 로 끝납니다doneerror.

다중 턴 대화를 계속하려면, 이전 응답의 세션 ID를 요청 x-ms-session-idchat 헤더나 chatstream 호출에 전송하세요. 그 헤더를 생략하면 런타임이 자동으로 새 세션을 생성합니다.

POST /agents/main/chatstream HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
x-ms-session-id: <SESSION_ID_FROM_A_PREVIOUS_RESPONSE>

{"prompt":"Continue the last summary and add blockers."}

세션 및 상태

다중 턴 에이전트 상호작용은 세션 이력이 필요합니다. 런타임은 환경에 따라 자동으로 세션 저장을 관리합니다:

Environment	Storage	Configuration
애저 (Azure)	기본 호스트 스토리지 계정의 Blob Storage (`AzureWebJobsStorage`)	연결 문자열 또는 식별 기반(선호). 관리 신원 구성을 참조하세요.
지역 개발	로컬 에이전트 구성 디렉터리 하의 파일 기반	설정이 필요 없습니다.

런타임은 별도의 세션 데이터베이스가 필요하지 않습니다. 샌드박스 실행은 세션 인식 기능도 있습니다: 명시적인 세션 ID가 없을 때는 런타임이 새로 격리된 샌드박스 세션을 사용하여 관련 없는 호출이 상태를 공유하지 않습니다.

지원되는 호스팅 계획

서버리스 에이전트 런타임은 다음과 같은 Azure Functions 호스팅 계획을 지원합니다:

Plan	서버리스 스케일링	Notes
Flex 사용량	Yes	0까지 스케일링, 초당 청구, 자동 스케일링. 대부분의 에이전트 업무에 권장됩니다.
전용(App Service)	No	수동 또는 규칙 기반 확장이 가능한 항상 켜진 인스턴스입니다. 이미 사용 가능한 용량이 있는 앱 서비스 플랜 인스턴스가 있을 때 사용하세요.

두 요금제 모두 관리형 신원, 가상 네트워크 통합, 애플리케이션 인사이트를 지원합니다.

피드백

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

Last updated on 2026-07-23