Azure Functions의 Python용 에이전트 바인딩

Python 함수 앱용 에이전트 바인딩은 기존 함수에 에이전트 행동을 추가할 수 있게 해줍니다. 함수가 실행되면 확장 기능은 Markdown 지침으로부터 Agent를 생성하고 이를 타입이 지정된 매개변수로 핸들러에 주입합니다. 코드는 결정론적 애플리케이션 논리와 함께 언제 어떻게 에이전트를 호출할지 결정합니다.

Important

Python 함수 앱의 에이전트 바인딩은 현재 프리뷰 단계입니다. 기능, 패키지 이름, 구성은 일반 제공 전에 변경될 수 있습니다.

에이전트 바인딩을 Azure Functions 호스팅 스킬 및 모델 컨텍스트 프로토콜(MCP) 도구와 같은 다른 AI 관련 기능과 비교하려면 Azure Functions의 AI 통합 옵션을 참조하세요.

에이전트 바인딩은 확장 소유의 입력 바인딩으로, Python 함수에 완전히 구성된 Agent 객체를 제공합니다. 확장 프로그램은 에이전트 명령어를 파일에서 .agent.md 원시 텍스트로 읽습니다. 애플리케이션 코드는 클라이언트 및 제공자 전용 도구 구성을 유지하며, 함수 앱 프로젝트는 파일 기반 에이전트 기술과 원격 MCP 서버를 발견할 수 있습니다.

에이전트 바인딩 아키텍처는 제공자별 확장 패키지를 통해 서로 다른 SDK의 에이전트 객체를 지원합니다. 현재 프리뷰에서 지원되는 에이전트 SDK는 Microsoft Agent Framework뿐입니다. 사용하려면 패키지를 azurefunctions-agents-extensions-agent-framework 설치하세요.

에이전트 바인딩을 사용할 때

Azure 함수가 워크플로우의 일부에 에이전트적 추론이 필요하지만, 애플리케이션이 트리거, 검증, 분기, 오류 처리, 응답 제어를 유지해야 할 때 에이전트 바인딩을 사용하세요. 일반적인 시나리오는 다음과 같습니다.

HTTP 요청을 평가하세요. 결정론적 코드로 주문을 검증하고, 에이전트에게 이행 위험을 평가하도록 요청한 뒤, 그 결과를 이용해 HTTP 응답을 구성합니다.
사건을 풍부하게 하거나 분류하세요. 큐 메시지, 이벤트 그리드 이벤트 또는 기타 트리거 페이로드를 받고, 함수가 결과를 작성하기 전에 에이전트를 사용해 데이터를 분류, 요약 또는 보충합니다.
지속적인 작업 흐름에 이성을 더하세요. Durable Functions 오케스트레이터에서 replay-safe context.call_agent() API를 통해 에이전트를 호출한 후, 이후 오케스트레이션 단계에서 결과를 활용하세요.

함수의 결정론적 코드가 코디네이터 역할을 유지해야 할 때 에이전트 바인딩은 적합하다. 에이전트는 유한한 추론 작업을 수행하고 제어권을 핸들러 또는 오케스트레이션에 반환합니다.

왜 에이전트 바인딩을 사용하나요?

많은 생산 워크플로우는 결정론적이어야 하는 단계와 모델 추론의 이점을 얻는 단계를 결합합니다. 에이전트 바인딩은 이러한 하이브리드 워크플로우에 다음과 같은 이점을 제공합니다:

기존 기능에 에이전트적 행동을 추가하세요. HTTP-, 타이머-, 큐-, 이벤트 그리드-, Service Bus- 등 트리거 함수들의 에이전트 추론을 사용하세요.
코드 내에서 에이전트 호출을 안전하게 제어하세요. 에이전트를 언제 호출할지 결정하고, 반응을 점검하며, 함수 출력을 결정합니다. 이 확장은 성공, 실패 또는 취소 시 호출 소유 자원을 종료합니다.
에이전트 설정 코드를 줄이세요. 각 호출마다 생성하고 배선하는 대신 타입이 지정된 핸들러 매개변수로 구성된 Agent 값을 받으세요.
명령어는 실행 시 설정과 분리하세요. 자연어 명령 .agent.md 어를 파일에 저장하고, 클라이언트와 제공자 전용 도구를 Python에서 명시적으로 구성하세요.
공유 에이전트 기능을 활용하세요. 확장 프로그램은 애플리케이션 루트에서 파일 기반 에이전트 기술과 HTTP 기반 MCP 서버를 발견하여 각 에이전트 바인딩에 제공한다.
내구성 있는 조율 담당자에게 연락하세요. 확장 기능은 숨겨진 활동에서 에이전트 작업을 실행하여 오케스트레이션 재생이 결정론적으로 유지되도록 합니다.
익숙한 도구로 로컬에서 디버깅하세요. 다른 Python 함수 앱처럼 로컬에서 실행하고 디버깅하세요. 브레이크포인트를 설정하고 결정론적 함수 논리와 에이전트를 호출하는 코드 모두를 단계적으로 진행할 수 있습니다.

에이전트 바인딩의 작동 원리

AgentFunctionApp는 azure.functions.FunctionApp를 확장하므로 FunctionApp와 동일한 기능을 갖습니다. 데코레이터는 markdown_agent 함수에 에이전트 입력을 추가합니다.

각 에이전트 바인딩에 대해 확장은 다음과 같은 연산을 수행합니다:

함수 앱 루트 또는 그 agents/ 디렉터리에서 요청된 .agent.md 파일을 해결합니다.
전체 파일을 원시 UTF-8 명령어로 불러옵니다.
지침과 구성된 클라이언트 팩토리, 명시적으로 설정된 제공자 도구, 발견된 에이전트 기술 및 MCP 서버를 결합합니다.
새로운 Agent을 생성하고 호출이 소유한 리소스를 엽니다.
Agent를 핸들러 매개변수에 주입합니다.
실행이 종료되면 호출 소유 자원을 닫습니다.

이 확장은 제공자 발견과 컴파일된 바인딩 정의를 캐시할 수 있습니다. 함수 호출 간에 실시간 호출 자원을 캐시하거나 재사용하지 않습니다.

에이전트 결합을 정의하세요

다음 예시는 현재 지원되는 Microsoft Agent Framework 제공자를 사용하여 HTTP 트리거 함수에 a Agent 를 추가합니다. 함수는 코드를 통해 작업을 구성하고, 에이전트를 호출하며, 에이전트 응답을 반환합니다:

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

값은 arg_name 주입된 핸들러 매개변수와 일치해야 합니다. 여러 에이전트를 동일한 함수에 주입하려면 markdown_agent 데코레이터를 여러 개 겹쳐 사용하고, 각 에이전트 바인딩마다 고유한 arg_name 값과 핸들러 매개변수를 사용하세요. 이 값은 agent_name 명령어 파일을 식별합니다. 이 예에서 는 order-fulfillment 다음 위치 중 정확히 하나로 해결되어야 한다:

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

두 파일이 모두 존재하면 정의가 모호해지고 앱 시작이 실패합니다. 에이전트 이름에는 절대 경로, 경로 구분자, 또는 순회 구성 요소가 포함될 수 없습니다. 애플리케이션 루트 외부에서 해결되는 파일은 허용되지 않습니다.

에이전트 클라이언트와 도구를 구성하세요

client_factory를 구성할 때 인수가 없는 AgentFunctionApp를 구성하세요. 공장은 제공자 패키지로 지원되는 신규 고객을 반환합니다. 또한 앱 수준에서 Microsoft Agent Framework 도구 객체나 Python 호출 가능 객체를 매개변수를 통해 tools 전달할 수도 있습니다. 바인딩은 다른 동작이 필요할 때 앱 수준의 클라이언트 팩토리와 도구를 무시할 수 있습니다.

예를 들어, 다음 HTTP 트리거 함수는 order_agent를 lookup_inventory에만 도구로 사용할 수 있게 하는 에이전트 바인딩을 사용합니다:

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

에이전트 클라이언트와 도구를 구성할 때 다음과 같은 고려사항을 염두에 두세요:

기본 에이전트 확장은 제공자 중립적입니다. 프로바이더 패키지는 특정 에이전트 SDK를 통합하고 지원되는 클라이언트 및 에이전트 유형을 정의합니다.
현재 지원되는 Microsoft Agent Framework 제공자 패키지는 애플리케이션에 대한 모델 제공자를 선택하거나 구성하지 않습니다. 클라이언트 팩토리는 지원하는 Microsoft Agent Framework 채팅 클라이언트와 에이전트가 사용하는 모델을 결정합니다.
확장 프로그램은 전체 .agent.md 파일을 에이전트 지침으로 설정된 프로바이더에 전달합니다. 모델 설정, 도구, YAML 프론트 매터, 기타 런타임 구성을 파일에서 파싱하지 않습니다.

공유 에이전트 기술과 MCP 서버

확장 기능은 애플리케이션 루트에서 공유 에이전트 기능을 자동으로 발견합니다:

Capability	위치	작동 방식
에이전트 기술	`skills/<skill-name>/SKILL.md` 또는 `Skills/<skill-name>/SKILL.md`	제공자 패키지는 파일 기반 에이전트 스킬을 로드하고 검증합니다.
원격 MCP 서버	`mcp.json`	이 확장 프로그램은 지원되는 HTTP 또는 스트리밍 가능한 HTTP 서버와 선택적 도구 허용 목록을 구성합니다.
제공자 도구	애플리케이션 또는 바인딩 구성	Microsoft Agent Framework 도구 객체나 Python 호출 가능 객체는 발견 대신 명시적으로 제공됩니다.

공유 에이전트 기능을 사용할 때 다음과 같은 고려사항을 명심하세요:

함수 앱의 모든 에이전트 바인딩은 발견된 모든 에이전트 스킬과 MCP 서버를 받습니다.
파일 기반 에이전트 기술은 에이전트가 로드할 수 있는 역량입니다. 이들은 별도의 실행 모델을 사용하는 Azure Functions 호스팅 스킬이 아닙니다.
현재 에이전트 확장 미리보기에서는 앱이나 개별 바인딩의 일부 기능을 선택하는 기능을 지원하지 않습니다.
에이전트 기술과 MCP 도구는 특권 작업을 수행할 수 있습니다. 앱 내 모든 에이전트가 사용할 수 있는 기능만 배치하고, 에이전트가 서로 다른 기능 경계를 요구할 때는 별도의 기능 앱을 사용하세요.

MCP 구성은 URL, 헤더, 인증 범위, 클라이언트 ID에 대한 환경 변수를 참조할 수 있습니다. 참조는 각 호출에 대해 해결되며, 확장이 서버에 연결되기 전에 이루어집니다. 비밀을 소스 제어 mcp.json 파일에 직접 저장하지 마세요.

로컬 프로세스 및 표준 입출력(stdio) MCP 서버는 지원되지 않습니다. MCP 지원은 선택적 의존성이며, 설치하지 않은 경우에도 일반 패키지 가져오기는 안전합니다.

Durable Functions에서 에이전트 바인딩 사용

에이전트 바인딩은 선택적 Durable Functions 통합을 통해 하이브리드 및 장기 워크플로우를 지원합니다. 동기식 제너레이터 오케스트레이터는 context.call_agent()를 호출하고 그 결과 작업을 yield합니다:

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() 에이전트 정의를 해결하고 모든 모델, 파일 시스템, 자격 증명, 도구 및 네트워크 작업을 수행하는 숨겨진 활동을 예약합니다. 오케스트레이터는 결정적적이고 JSON으로 직렬화할 수 있는 스키마-v1 요청만 생성합니다. 그 결과, 오케스트레이션 재생은 비결정적 에이전트 연산을 반복하지 않습니다.

내구성 에이전트 호출은 AgentFunctionApp에서 구성된 공급자와 공유 기능을 사용합니다. 입력과 출력은 JSON 직렬화 가능해야 합니다.

Durable Functions 지원은 선택 사항입니다. 이 기능을 사용하지 않는 애플리케이션은 Durable Functions를 설치하거나 가져올 필요가 없습니다. orchestration_trigger 및 context.call_agent()를 사용하려면 Durable 추가 종속성 옵션이 포함된 지원되는 provider 패키지를 설치하세요.

프로젝트 파일

에이전트 지원 애플리케이션은 에이전트 확장 의존성과 하나 이상의 명령어 파일을 가진 표준 Python v2 함수 앱입니다:

파일 또는 폴더	Purpose
`function_app.py`	`AgentFunctionApp`, 표준 Functions 트리거, 에이전트 바인딩, 클라이언트 팩터리 및 명시적으로 구성된 프로바이더 도구를 정의합니다.
`host.json`	Azure Functions 호스트를 구성합니다.
`requirements.txt`	지원되는 에이전트 제공자 패키지와 모든 SDK 전용 클라이언트 패키지를 포함합니다. 현재 미리보기에는 .를 사용하세요 `azurefunctions-agents-extensions-agent-framework`. 선택 사양으로 Durable Functions와 MCP 지원이 가능합니다.
`.agent.md` 또는 `agents/.agent.md`	에이전트에 대한 원시 UTF-8 명령어가 포함되어 있습니다. 참조된 각 이름은 정확히 하나의 파일을 가리켜야 합니다.
`skills/` 또는 `Skills/`	(선택 사항) 모든 에이전트 바인딩에서 공유하는 파일 기반 에이전트 스킬을 포함합니다.
`mcp.json`	(선택 사항) 모든 에이전트 바인딩이 공유하는 원격 HTTP 기반 MCP 서버를 정의합니다.

표준 Python 프로젝트 구조에 대해서는 Azure Functions Python 개발자 가이드를 참조하세요.

검증 및 진단

이 확장은 바인딩 컴파일 전이나 컴파일 중에 에이전트 정의를 검증하므로, 구성 문제는 조치 가능한 오류와 함께 실패합니다. 검증은 다음을 포함합니다:

누락되었거나 모호한 .agent.md 파일들.
부적절한 핸들러 서명, 누락되거나 일치하지 않는 주입 매개변수 등이 포함됩니다.
지원되지 않는 제공자 옵션 또는 기능.
잘못된 스킬 디렉토리와 왜곡된 MCP 구성.
지원되지 않는 MCP 전송과 누락된 환경 값들.
유효하지 않은 내구성 페이로드나 JSON 직렬화가 불가능한 값들.

가능한 경우, 이 확장은 제공자 경계에서 Azure 함수 이름, 호출 ID, 내구성 인스턴스 ID를 보존하여 상관관계 및 진단을 지원합니다.

피드백

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

Last updated on 2026-09-24