Azure Functions 서버리스 에이전트 런타임은 AI 에이전트를 Azure Functions 앱으로 빌드하기 위한 markdown 우선 프로그래밍 모델입니다. 호스팅, 트리거, 모델 클라이언트, 도구, 세션 스토리지, ID 및 관찰 가능성을 함께 연결하는 대신 파일에 에이전트를 .agent.md 정의하고 함수 앱으로 배포합니다.
런타임은 이벤트에 반응하고, 도구를 호출하고, 서버리스 인프라에서 실행되는 에이전트를 위해 설계되었습니다. 에이전트는 HTTP 요청, 일정, 큐, 메시지, 데이터베이스 변경 내용 및 기타 이벤트에서 시작할 수 있습니다. 원격 MCP 서버, 커넥터 네임스페이스에서 호스트되는 MCP 서버, 재사용 가능한 기술 및 샌드박스 실행 사용 및 다른 Azure Functions 앱에서 사용하는 동일한 배포, ID, 모니터링 및 크기 조정 기능을 사용하여 실행합니다. 앱별 논리의 경우 동일한 함수 앱에서 사용자 지정 도구를 작성할 수 있습니다.
메모
서버리스 에이전트 런타임은 미리 보기 상태입니다. 기능, 구성 이름 및 지원되는 커넥터는 일반 공급 전에 변경할 수 있습니다.
Azure Functions 에이전트를 빌드하는 이유는 무엇인가요?
프로덕션 에이전트에는 프롬프트와 모델 이상이 필요합니다. 작업을 시작하고, 외부 시스템을 호출하고, 대화 기록을 유지하며, 신뢰할 수 없는 코드를 안전하게 실행하고, 비밀 없이 인증하고, 원격 분석을 내보내고, 주문형으로 확장하는 신뢰할 수 있는 방법이 필요합니다.
Azure Functions 이미 이러한 운영 문제에 대한 이벤트 기반 컴퓨팅 모델을 제공합니다. 서버리스 에이전트 런타임은 해당 모델을 에이전트에 적용합니다.
- 에이전트는 작업 단위입니다. 파일은
.agent.md하나의 에이전트에 대한 트리거 및 지침을 정의합니다. - 이벤트가 에이전트를 시작시킵니다. 함수 트리거를 사용하면 에이전트가 일정에 따라 실행되거나, 큐 및 이벤트에 반응하거나, HTTP 엔드포인트를 노출할 수 있습니다.
- 필요한 경우 코드와 함께 기능이 먼저 구성됩니다. 에이전트는 구성에서 원격 MCP 서버, 커넥터 네임스페이스에 호스트된 MCP 서버, 기술 및 샌드박스 코드 실행을 사용할 수 있습니다. 앱별 논리에 사용자 지정 도구를 사용합니다.
- 호스팅은 서버리스입니다. Flex Consumption는 초당 0으로 크기 조정, 초당 청구, 관리 ID, 가상 네트워크 통합 및 Application Insights를 지원합니다.
- 운영 배관이 내장되어 있습니다. 런타임은 에이전트 검색, 트리거 등록, 도구 어셈블리, 세션 기록 및 선택적 기본 제공 엔드포인트를 처리합니다.
프로젝트 구조
서버리스 에이전트 앱은 일반 Functions 프로젝트 파일 옆에 에이전트별 파일이 있는 Python Azure Functions 앱입니다.
| 파일 또는 폴더 | 필수 | Purpose |
|---|---|---|
function_app.py |
Yes |
create_function_app() 가져오고 구성된 Azure Functions 앱을 반환합니다. |
*.agent.md |
Yes | 에이전트를 정의합니다. YAML 프론트매터는 에이전트를 설정하고, 마크다운 본문은 지침이 됩니다. |
agents.config.yaml |
No | 모델, 시간 제한 및 샌드박스 설정과 같은 앱 전체 런타임 기본값을 정의합니다. |
mcp.json |
MCP 서버 또는 커넥터 도구를 사용하는 경우 | 메일 보내기 또는 Teams 작업과 같은 작업을 위한 커넥터 도구를 포함하여 에이전트가 도구로 사용할 수 있는 원격 HTTP MCP 서버를 정의합니다. |
tools/ |
No | MCP 서버, 연결, 기술 또는 샌드박스 실행에서 다루지 않는 기능에 대한 사용자 지정 Python 도구를 포함합니다. |
skills/ |
No | 에이전트가 필요에 따라 로드할 수 있는 재사용 가능한 SKILL.md 프롬프트 자산을 포함합니다. |
host.json |
Yes | Azure Functions 호스트를 구성합니다. |
requirements.txt |
Yes | 서버리스 에이전트 런타임 패키지 및 앱별 Python 종속성을 포함합니다. |
infra/ |
No | 와 같은 azd배포 도구에서 사용하는 코드로서의 인프라 파일을 포함합니다. |
최소 프로젝트에는 function_app.py, host.json, requirements.txt, 그리고 최소 하나의 .agent.md 파일이 포함됩니다. 앱에 앱 전체 런타임 기본값이 필요한 경우 추가 agents.config.yaml 합니다.
에이전트 파일
에이전트 파일은 YAML 프런트 매터와 markdown 지침을 사용합니다. 이 예제에서는 타이머 트리거 에이전트를 정의합니다.
---
name: Daily Tech News Email
description: Fetches top tech news and emails a summary daily.
trigger:
type: timer_trigger
args:
schedule: "0 0 15 * * *"
---
You are a news assistant. When triggered, do the following:
1. Gather today's top technology news from reputable sources.
1. Summarize the stories in a concise HTML email body.
1. Email the summary to $TO_EMAIL with the subject "Daily Tech News Summary".
문서 서두에서는 에이전트가 어떻게 호출되는지를 선언합니다. markdown 본문은 런타임이 실행 중에 모델에 전달하는 명령 블록입니다. 환경 변수 대체를 사용하면 명령 및 구성 값이 앱 설정(예: .) $TO_EMAIL을 참조할 수 있습니다.
각 .agent.md 파일은 하나의 에이전트를 정의합니다. 파일 이름은 Azure 함수 이름과 기본 제공 엔드포인트의 경로 세그먼트를 파생하는 데 사용됩니다.
name 필드는 로그, 레이블 및 설명서에 사용되는 표시 이름입니다.
다음 프런트 매터 필드를 사용하여 에이전트를 구성합니다.
| Field | 필수 | Description |
|---|---|---|
name |
Yes | 에이전트의 표시 이름입니다. |
description |
Yes | 에이전트가 수행하는 작업 및 사용 시기에 대한 간단한 설명입니다. |
trigger |
예, builtin_endpoints이(가) 활성화되어 있지 않은 한 그렇습니다. |
에이전트를 호출하는 방법을 정의합니다. 에이전트 파일당 하나의 트리거만 허용됩니다. |
model |
No |
agents.config.yaml 또는 앱 설정에 구성된 기본 모델을 재정의합니다. |
timeout |
No | 기본 실행 시간 제한(초)을 재정의합니다. |
builtin_endpoints |
No | 기본 제공 디버그 및 컴퍼지션 엔드포인트를 사용하도록 설정합니다. 모든 기본 제공 엔드포인트를 사용하도록 설정하려면 true를 사용하거나 debug_chat_ui, chat_api, mcp를 개별적으로 구성하세요. |
logger |
No | 에이전트에 대해 런타임 로깅을 사용할 수 있는지 여부를 제어합니다. 기본값은 true입니다. |
mcp |
No | 에서 mcp.json검색된 MCP 서버에 대한 액세스를 제어합니다. 이 에이전트에 대해 MCP 서버를 사용하지 않도록 설정하거나 특정 서버를 제거하는 데 사용합니다 falseexclude . |
skills |
No | 검색된 기술에 대한 액세스를 제어합니다. 이 에이전트에 대한 기술을 사용하지 않도록 설정하거나 특정 기술을 제거하는 데 사용합니다 falseexclude . |
tools |
No | 검색된 사용자 지정 Python 도구에 대한 액세스를 제어합니다. 이 에이전트에 대한 사용자 지정 도구를 사용하지 않도록 설정하거나 특정 도구를 제거하는 데 사용합니다 falseexclude . |
system_tools |
No | 에이전트가 샌드박스 실행과 같은 구성된 시스템 도구를 옵트아웃할 수 있습니다. |
input_schema |
No | HTTP 트리거 에이전트에 대한 HTTP 요청 본문의 유효성을 검사하는 데 사용되는 JSON 스키마입니다. |
response_schema |
No | HTTP 트리거 에이전트에서 반환된 구조적 응답의 유효성을 검사하는 데 사용되는 JSON 스키마입니다. |
response_example |
No | HTTP 트리거 에이전트의 구조적 응답을 안내하는 데 사용되는 응답 셰이프 예제입니다. |
metadata |
No | 사용자 고유의 조직 또는 도구에 대한 사용자 지정 메타데이터입니다. |
substitute_variables |
No | 환경 변수 대체가 전면 문제 및 지침에 적용되는지 여부를 제어합니다. 기본값은 true입니다. |
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에서 대체를 비활성화하지 않습니다.
런타임에서 앱을 시작하는 방법
Azure Functions 호스트가 앱을 가져오면 create_function_app() 프로젝트 파일에서 구성된 FunctionApp 빌드합니다.
- 앱 루트를 확인합니다.
-
agents.config.yaml을 로드합니다. - 각
.agent.md파일을 로드합니다. - MCP 서버, 기술 및 사용자 지정 도구를 검색합니다.
- 앱 전체 기본값 및 에이전트별 구성을 작성합니다.
- 확인된 에이전트 구성의 유효성을 검사합니다.
- 각 에이전트에 대한 최종 도구 및 기술 기능을 빌드합니다.
- Azure Functions 트리거 및 선택적 기본 제공 엔드포인트를 등록합니다.
시작 후 Azure Functions 호스트는 다른 함수 앱과 마찬가지로 등록된 트리거를 인덱싱합니다. 트리거가 실행되면 런타임은 지침, 모델 설정, 도구, 기술 및 세션 기록을 사용하여 에이전트를 빌드한 다음 Microsoft Agent Framework를 통해 실행합니다.
이벤트에서 에이전트 트리거
서버리스 에이전트는 작업을 시작하는 이벤트가 모델 호출만큼 중요한 경우에 유용합니다. 런타임은 에이전트 파일당 하나의 트리거를 지원합니다.
트리거 정의에는 type 개체와 args 개체가 있습니다. 트리거 type 바인딩을 식별하고 에이전트 args 를 시작하는 이벤트를 구성하는 트리거별 설정을 포함합니다.
trigger:
type: timer_trigger
args:
schedule: "0 0 15 * * *"
일반적인 트리거 형식에는 http_trigger,timer_trigger, queue_triggerblob_triggerevent_grid_trigger및 .service_bus_trigger 기본 제공 Azure Functions 트리거의 경우 Python v2 트리거 및 바인딩 문서 및 트리거에 대한 바인딩 참조를 사용하여 args 포함할 설정을 찾습니다. 예를 들어 타이머 트리거는 schedule 설정을 사용하고, 큐 트리거는 queue_name 및 connection와 같은 설정을 사용하며, blob 트리거는 path 및 connection와 같은 설정을 사용합니다. 런타임은 생성된 함수 진입점을 제공하므로 에이전트 파일에는 이벤트 원본을 식별하는 트리거 설정만 필요합니다.
일반적인 트리거 패턴은 다음과 같습니다.
| 패턴 | 예시 |
|---|---|
| HTTP 에이전트 | 요청을 수신하고, 도구를 호출하고, 구조화된 응답을 반환합니다. |
| 예약된 에이전트 | 매일 보고서, 다이제스트, 정리 또는 조정 워크플로를 실행합니다. |
| 큐 또는 메시지 에이전트 | 모델 추론 또는 도구 호출이 필요한 작업 항목을 처리합니다. |
| 스토리지 또는 데이터베이스 이벤트 에이전트 | 변경된 파일, 레코드 또는 이벤트에 반응합니다. |
| 커넥터로 트리거되는 에이전트 | 커넥터에서 지원되는 경우 Teams 메시지, Outlook 메일 또는 일정 이벤트와 같은 연결된 서비스의 이벤트에 대응합니다. |
각 에이전트는 Azure 함수로 등록되므로 앱은 크기 조정 규칙, 관리 ID, 네트워킹 및 모니터링과 같은 Functions 호스팅 기능을 사용할 수 있습니다.
에이전트 도구 제공
에이전트는 작동할 수 있을 때 유용합니다. 구성된 기능(원격 MCP 서버, 커넥터 네임스페이스에서 호스트되는 MCP 서버, 기술 및 샌드박스 실행)으로 시작합니다. 이러한 옵션에 맞지 않는 앱별 기능에 사용자 지정 Python 도구를 사용합니다.
원격 MCP 서버
앱에서 원격 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를 사용하려면 이 필드를 생략합니다. |
에이전트가 다른 서비스에서 호스트하는 도구를 호출하거나 앱 경계를 넘어 에이전트 및 도구를 작성해야 하는 경우 원격 MCP 서버를 사용합니다.
Azure 커넥터
커넥터를 사용하면 에이전트가 사용자 지정 API 클라이언트 코드 없이 외부 서비스로 작업할 수 있습니다. 예를 들어 Microsoft 365 Outlook 커넥터는 전자 메일을 보낼 수 있고, Teams 커넥터는 메시지로 작업할 수 있으며, 다른 커넥터는 Salesforce, SAP 또는 SQL과 같은 시스템에서 작업을 호출할 수 있습니다. 커넥터 네임스페이스는 앱에서 이러한 통합을 사용할 수 있도록 하는 연결, 트리거 및 MCP 서버를 호스트합니다.
서버리스 에이전트 앱에서 커넥터 기능을 사용하려면 먼저 커넥터 네임스페이스를 만들고, 서비스에 대한 연결을 만들고, 해당 연결에 권한을 부여합니다. 그런 다음 에이전트에서 연결을 사용하는 방법을 선택합니다.
- 커넥터는 연결된 서비스에서 새 전자 메일, Teams 메시지 또는 일정 이벤트와 같은 문제가 발생할 때 에이전트를 시작합니다. 이를 사용하려면 커넥터 네임스페이스에서 권한 있는 연결을 사용하는 트리거를 만든 다음 해당 커넥터 트리거 정의의 트리거 이름 및 인수를 사용하여 에이전트를 구성합니다.
-
커넥터 MCP 도구를 사용하면 에이전트가 전자 메일 보내기 또는 레코드 업데이트와 같은 서비스 작업을 호출할 수 있습니다. 이를 사용하려면 커넥터 네임스페이스에 권한 있는 연결을 사용하는 MCP 서버를 만든 다음 MCP 서버 엔드포인트를 추가합니다
mcp.json.
커넥터 MCP 도구의 경우 MCP 서버 항목은 mcp.json 엔드포인트 및 관리 ID 인증 설정을 저장합니다. 에이전트가 커넥터 네임스페이스에서 관리되는 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 서버를 호출할 수 있어야 합니다.
기술
기술은 아래에 skills/저장된 재사용 가능한 프롬프트 자산입니다. 필요한 경우 도메인별 지침을 사용할 수 있도록 하면서 기본 에이전트 지침을 작게 유지하는 데 도움이 됩니다. 런타임은 에이전트 기술 형식을 사용합니다.
런타임은 함수 앱 프로젝트 루트에서 skills/를 검색하고, SKILL.md를 포함하는 폴더를 재귀적으로 찾아냅니다.
skills/
incident-response/
SKILL.md
triage-checklist.md
escalation-policy.md
파일에는 SKILL.md YAML 프런트 매터와 markdown 지침이 포함되어 있습니다.
---
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 파일을 참조하세요. - markdown 파일만 서버리스 에이전트 런타임에서 기술 콘텐츠로 지원됩니다. 기술에 실행 동작이 필요한 경우 해당 코드를 사용자 지정 Python 도구로 패키지하고 기술 지침에서 이름으로 도구를 참조합니다.
에이전트는 기본적으로 검색된 모든 기술을 상속합니다. 특정 에이전트가 사용하지 않아야 하는 경우 에이전트 파일에서 기술을 사용하지 않도록 설정하거나 제외합니다.
skills: false
skills:
exclude:
- incident-response
샌드박스 실행
코드 실행 또는 브라우저 자동화의 경우 런타임은 Azure Container Apps 동적 세션 사용할 수 있습니다. 동적 세션은 세션 풀에서 격리된 환경을 제공합니다. 런타임은 코드 인터프리터 세션을 사용하여 에이전트에 도구를 제공합니다 execute_python .
agents.config.yaml에서 샌드박스 실행을 구성합니다:
system_tools:
dynamic_sessions_code_interpreter:
endpoint: $ACA_SESSION_POOL_ENDPOINT
다음 샌드박스 요구 사항을 사용합니다.
- 세션 풀은
--container-type PythonLTS사용하여 만든 풀과 같은 Python 코드 인터프리터 세션 풀이어야 합니다. - 값은
endpoint세션 풀 관리 엔드포인트입니다. - Azure 함수 앱에서 사용하는 관리 ID에는 세션 풀에서 코드를 실행하는 데 필요한 역할 할당이 있어야 합니다. 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를 사용할 수 없는 경우 런타임은 새 샌드박스 세션을 사용하므로 관련 없는 실행이 상태를 공유하지 않습니다.
에이전트는 전역적으로 구성된 경우 샌드박스 실행을 상속합니다. 해당 에이전트가 코드를 실행하지 않아야 하는 경우 특정 에이전트에 대해 사용하지 않도록 설정합니다.
system_tools:
dynamic_sessions_code_interpreter: false
사용자 지정 Python 도구
MCP 서버, 커넥터 네임스페이스, 기술 또는 샌드박스 실행에서 호스트되는 MCP 서버에 맞지 않는 앱별 기능에 사용자 지정 Python 도구를 사용합니다. 사용자 지정 도구를 사용하면 동일한 함수 앱에서 Azure Functions 및 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를 고정하거나 런타임에서 공급자를 유추하도록 할 수 있습니다(예: AZURE_OPENAI_ENDPOINT, FOUNDRY_PROJECT_ENDPOINT또는 OPENAI_API_KEY.).
모델 선택에서는 다음과 같은 일반적인 우선 순위를 사용합니다.
- 에이전트 또는 런타임 호출에서 요청한 모델입니다.
- 공급자별 설정(예:
AZURE_OPENAI_DEPLOYMENT또는FOUNDRY_MODEL. -
AZURE_FUNCTIONS_AGENTS_MODEL; - 공급자 기본값입니다.
프로덕션 앱의 경우 지원되는 관리 ID를 선호합니다. 앱에서 사용자 할당 관리 ID를 사용해야 하는 경우 모델 공급자와 샌드박스 실행에서 해당 ID를 사용하도록 설정합니다 AZURE_CLIENT_ID .
관리되는 ID 구성
런타임은 Microsoft Entra 인증을 지원하는 Azure 리소스에 관리 ID를 사용합니다. 앱의 기본 ID 선택기로 사용합니다 AZURE_CLIENT_ID . 커넥터 네임스페이스 및 Blob 지원 세션 기록에 호스트되는 MCP 서버는 보다 구체적인 ID 설정을 사용할 수 있습니다.
모델 공급자 및 샌드박스 실행의 경우, 런타임에서 사용자 할당 관리 ID를 사용하도록 하려면 AZURE_CLIENT_ID를 설정합니다.
AZURE_CLIENT_ID 설정되지 않은 경우 런타임은 표준 Azure SDK 자격 증명 동작을 사용합니다. 이 동작은 사용 가능한 경우 시스템 할당 관리 ID를 포함할 수 있습니다.
다음 설정을 사용하여 관리 ID를 선택합니다.
| 런타임 기능 | ID 설정 | 폴백 |
|---|---|---|
| Azure OpenAI 모델 공급자 | AZURE_CLIENT_ID |
기본 자격 증명 작동 방식 |
| Azure AI Foundry 모델 공급자 | AZURE_CLIENT_ID |
기본 자격 증명 작동 방식 |
| Azure Container Apps 동적 세션 샌드박스 | system_tools.dynamic_sessions_code_interpreter.client_id |
AZURE_CLIENT_ID, 다음으로 기본 자격 증명 동작 |
| 커넥터 네임스페이스에서 호스트되는 MCP 서버 |
auth.client_id의 서버 항목에 있는 mcp.json 값 |
AZURE_CLIENT_ID, 다음으로 기본 자격 증명 동작 |
| Blob 기반 세션 기록 |
AzureWebJobsStorage__clientId ID 기반 스토리지를 사용하는 경우 |
AZURE_CLIENT_ID, 다음으로 기본 자격 증명 동작 |
Azure OpenAI의 경우 이러한 ID 설정은 AZURE_OPENAI_API_KEY 설정되지 않은 경우에만 적용됩니다. API 키가 구성된 경우 모델 공급자는 관리 ID 대신 키를 사용합니다.
세션 기록은 Azure Functions 호스트와 동일한 스토리지 ID 구성을 사용합니다.
AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri, 및 AzureWebJobsStorage__clientId를 사용하여 Blob 기반 기록에 대한 ID 기반 저장소를 구성합니다. 런타임은 세션 기록에 별도의 에이전트별 ID 설정을 사용하지 않습니다.
세션 및 상태
다중 턴 에이전트 상호 작용에는 세션 기록이 필요합니다. Azure 런타임은 함수 앱의 AzureWebJobsStorage 계정을 사용하여 세션 기록을 Blob Storage 저장합니다. 이 디자인은 많은 앱에 대해 별도의 세션 데이터베이스를 방지하고 연결 문자열 또는 ID 기반 스토리지 구성에서 작동합니다.
Azure 스토리지 구성이 없는 로컬 개발의 경우 런타임은 로컬 에이전트 구성 디렉터리의 파일 기반 세션 기록으로 대체됩니다.
샌드박스 실행도 세션을 인식합니다. 런타임은 명시적 세션 ID 없이 샌드박스 도구를 만들 때 관련 없는 에이전트 실행 간에 상태를 공유하는 대신 호출에 대해 격리된 세션을 사용합니다.
기본 제공 엔드포인트
런타임은 추가 애플리케이션 코드 없이 기본 제공 디버그 및 컴퍼지션 엔드포인트를 노출할 수 있습니다. 기본 프로덕션 애플리케이션 인터페이스가 아닌 개발, 테스트 및 진단에 채팅 UI 및 채팅 API를 사용합니다.
| 표면 | 경로 | Azure 키 |
|---|---|---|
| 채팅 UI |
/agents/<AGENT_NAME>/ 때 builtin_endpoints.debug_chat_ui: true |
Azure 호스트되는 경우 함수 키를 묻는 메시지를 표시합니다. |
| HTTP 채팅 API |
POST /agents/<AGENT_NAME>/chat 때 builtin_endpoints.chat_api: true |
함수 키입니다. |
| 스트리밍 채팅 API |
POST /agents/<AGENT_NAME>/chatstream 때 builtin_endpoints.chat_api: true |
함수 키입니다. |
| MCP 엔드포인트 | /runtime/webhooks/mcp |
mcp_extension 시스템 키입니다. |
모든 에이전트 파일은 프론트매터의 builtin_endpoints 설정을 통해 활성화할 수 있습니다.
<AGENT_NAME> 경로 세그먼트는 표시 .agent.md 필드가 아니라 name 파일 이름에서 파생됩니다. 예를 들어, main.agent.md에서는 /agents/main/을 사용합니다.
Azure 호스팅되는 경우 채팅 UI는 메시지를 보내기 전에 함수 키를 묻는 메시지를 표시합니다. 이 키를 사용하여 HTTP 채팅 API를 직접 호출할 수도 있습니다.
az functionapp keys list \
--resource-group <RESOURCE_GROUP> \
--name <FUNCTION_APP_NAME> \
--query "functionKeys.default" \
--output tsv
키를 x-functions-key 헤더 또는 code 쿼리 문자열 매개변수로 전달합니다. MCP 클라이언트를 연결하려면 MCP 확장 시스템 키를 대신 가져옵니다.
az functionapp keys list \
--resource-group <RESOURCE_GROUP> \
--name <FUNCTION_APP_NAME> \
--query "systemKeys.mcp_extension" \
--output tsv
앱이 익명 액세스를 구성하지 않는 한 MCP 엔드포인트에는 이 시스템 키가 필요합니다.
서버리스 에이전트 런타임을 사용하는 경우
에이전트가 이벤트 기반이거나 도구가 많거나 운영상 Azure Functions 워크로드에 가까운 경우 서버리스 에이전트 런타임을 사용합니다.
적합한 경우는 다음과 같습니다.
- 요약, 모니터링, 조정 또는 보고하는 예약된 백그라운드 에이전트입니다.
- 메시지, 전자 메일, 경고, 큐 메시지 또는 데이터 변경에 반응하는 이벤트 기반 도우미입니다.
- 커넥터를 사용하여 SaaS 및 엔터프라이즈 애플리케이션에서 작업을 조정하는 시스템 간 에이전트입니다.
- HTTP, 채팅 UI 또는 MCP를 통해 동일한 에이전트를 노출하는 대화형 프런트 엔드입니다.
- 0으로 확장하고 관리 ID, 모니터링, 배포 슬롯 및 기타 Azure 호스팅 기능을 사용해야 하는 에이전트입니다.
결정적 함수를 다른 AI 클라이언트의 도구로만 노출해야 하는 경우 Azure Functions MCP 확장이 더 나은 시작점이 될 수 있습니다. 자세한 내용은 Azure Functions에서 AI 도구 및 모델 사용을 참조하세요.
시작하기
빠른 시작 가이드부터 시작하여 채팅 에이전트, 타이머로 트리거되는 블로그 요약 에이전트, 모델 배포, 샌드박스 실행, 그리고 커넥터 네임스페이스에서 제공되는 선택적 MCP 도구를 포함한 서버리스 에이전트 앱을 배포하세요.
관련 콘텐츠
Azure Functions Azure Functions - Azure Functions MCP 서버를 Foundry 에이전트 서비스에 연결합니다
- Flex 사용 계획 호스팅