도구와 에이전트

3.1 에이전트와 도구 호출

세부 학습 목표

• 에이전트의 역할·목표·대화·도구 스키마와 종료 조건을 정한다.
• 모델의 도구 요청과 앱의 인수·권한 검사·실행·결과 반환을 구별한다.
• API·검색·CU·사용자 함수·MCP를 필요한 도구 경계에 연결한다.

개요

• 모델: 사용할 도구와 인수를 제안.
• 앱: 허용 도구·인수 형식·사용자 권한을 검사한 뒤 실행.
• 결과 반환: 실제 도구 응답을 모델에 전달해 최종 답변 생성.

모델의 요청을 업무 실행으로 연결하기

• 일반 채팅 앱은 모델의 답을 보여 주는 데서 끝날 수 있습니다.

  에이전트는 필요에 따라 검색·계산·외부 API를 도구로 선택하고 결과를 받아 다음 행동을 결정합니다. 이때 “어떤 작업을 맡길지”와 “어떤 실행을 허용할지”를 각각 정의해야 합니다.

• 예를 들어 “내 주문 배송 상태를 알려줘”라는 요청에는 주문 조회 도구가 필요합니다.

  도구에는 이름, 목적, 인수의 구조와 반환값을 설명합니다. 모델이 get_order 호출과 order_id를 만들면 앱은 허용된 함수인지, 인수가 유효한지, 현재 사용자가 그 주문을 볼 수 있는지 검사한 뒤 실행합니다.

• 함수 호출 구조는 원격 프로시저 호출을 요청하는 메시지와 비슷하게 이해할 수 있습니다.

  메시지를 받았다는 사실과 서버가 작업을 완료했다는 사실은 구분됩니다. 모델이 호출 의도를 표현해도 주문 서비스의 권한 검사를 건너뛰지 않습니다.

스키마와 실행 계약

• JSON 스키마가 올바른 문자열을 요구하더라도 그 문자열이 현재 사용자의 주문 번호인지는 서버가 판단해야 합니다.

  사용자 ID와 관리자 여부 같은 권한 정보는 모델이 만든 인수에서 신뢰하지 않고 인증된 실행 문맥에서 가져옵니다.

로컬에서 도구 실행 경계를 확인하기

다음 코드는 모델 호출 응답을 가정한 교육용 시뮬레이션입니다. 외부 API나 실제 주문 데이터는 사용하지 않습니다.

import json
 
orders = {"ORDER-7": {"owner": "user-a", "status": "배송 중"}}
 
def get_order(order_id, authenticated_user):
    row = orders.get(order_id)
    if row is None or row["owner"] != authenticated_user:
        raise PermissionError("조회할 수 없는 주문")
    return {"order_id": order_id, "status": row["status"]}
 
def execute_tool(call, authenticated_user):
    if not isinstance(call, dict) or call.get("name") != "get_order":
        raise ValueError("허용하지 않은 도구")
    raw = call.get("arguments")
    if not isinstance(raw, str):
        raise ValueError("인수는 JSON 문자열이어야 함")
    try:
        args = json.loads(raw)
    except json.JSONDecodeError as error:
        raise ValueError("잘못된 JSON 인수") from error
    if not isinstance(args, dict) or set(args) != {"order_id"}:
        raise ValueError("order_id만 포함한 객체가 필요함")
    if not isinstance(args["order_id"], str) or not args["order_id"].strip():
        raise ValueError("주문 번호 형식 오류")
    return get_order(args["order_id"], authenticated_user)
 
call = {"name": "get_order", "arguments": '{"order_id":"ORDER-7"}'}
result = execute_tool(call, authenticated_user="user-a")
assert result["status"] == "배송 중"
 
for invalid in ('[]', 'null', '42', '{', '{}',
                '{"order_id":7}', '{"order_id":""}',
                '{"order_id":"ORDER-7","admin":true}'):
    try:
        execute_tool({"name": "get_order", "arguments": invalid}, "user-a")
    except ValueError:
        pass
    else:
        raise AssertionError("잘못된 인수가 실행됨")
 
try:
    execute_tool(call, authenticated_user="user-b")
except PermissionError:
    pass
else:
    raise AssertionError("다른 사용자의 주문을 조회함")
print(result["status"])

기대 출력은 배송 중입니다. 배열·null·잘못된 JSON·추가 필드는 ValueError로 거절하고, 올바른 인수라도 다른 사용자의 주문이면 PermissionError로 거절합니다. authenticated_user는 모델 인수가 아닌 앱의 인증 문맥에서 가져옵니다. 실제 앱에서는 성공 또는 실패 결과를 해당 도구 호출 ID에 연결해 모델에 반환하고 최종 응답을 받습니다.

외부 도구 연결 방식

• 직접 함수, OpenAPI로 설명한 REST API, MCP 서버, 검색 도구처럼 연결 방식은 여러 가지입니다.

  MCP는 모델이 외부 기능을 사용하도록 도구를 제공하는 프로토콜입니다. 연결 방식이 달라져도 허용 동작·인증·입출력·실패 처리를 확인하는 책임은 남습니다.

• 도구가 실패하면 성공한 값처럼 꾸미지 말고 구별 가능한 실패 결과를 전달합니다.

  변경 도구에는 승인과 중복 실행 방지도 필요하며, 이 흐름은 3.3에서 다룹니다.

에이전트 실행 루프와 종료 조건

• 에이전트 실행기는 현재 상태를 모델에 제공하고 도구 요청을 검증·실행하며 결과를 다시 전달합니다.

  반복과 예산을 제한하지 않으면 도구 호출이 계속될 수 있습니다.

• 상황: 반품 에이전트가 고객 정보를 찾지 못해 같은 검색 도구를 계속 호출합니다.

• 적용: 반복 횟수·시간·비용·동일 오류 연속 발생 등 예산과 중단 이유를 기록하도록 정합니다.

함수 스키마와 도구 계약

• 모델이 반환하는 도구 호출 인자는 제안입니다.

  앱은 파싱과 스키마 검증을 한 뒤 사용자 권한·업무 제약을 확인하고 함수를 실행해야 합니다.

• 상황: 모델이 refund(amount=500000) 함수 호출을 요청했는데 고객에게 허용된 상한은 200000원입니다.

• 적용: 모델의 함수 인자는 실행 제안입니다.

  서버에서 타입·필수 값·범위·소유권·금액 상한·중복 실행 여부를 확인한 뒤 도구를 호출합니다.

외부 도구 실행과 재시도

• 조회는 보통 반복해도 부작용이 작지만 결제·전송처럼 상태를 바꾸는 작업은 재시도가 중복 효과를 만들 수 있습니다.

  멱등성 키 또는 확인 조회 등 서비스별 대책이 필요합니다.

• 상황: 예약 API 호출 뒤 연결이 끊겨 성공 여부를 알 수 없습니다.

• 적용: 이미 예약이 완료됐을 수 있습니다.

  요청 ID로 상태를 조회하고 중복 요청 방지 기능을 활용해야 합니다.

확인 문제

사용자: "상태만 확인해 줘"
tools:
  manage_order(order_id, action="cancel")
  description: "주문 처리"
model call: manage_order(O17)  # action 생략
executor: 기본값 cancel 적용

호출 요청: id=c7 / get_order({"order_id":"O17"})
전제: 아직 함수는 실행되지 않았고 서비스 오류가 없음
범위: 도구 한 번 실행 후 추가 호출 없이 최종 답변 생성

서버 계약: GET /orders/{order_id} / OAuth audience=orders-api
도구 정의: GET /orders?id={order_id} / audience=project-api
시험1(도구 정의): HTTP 401 invalid audience
시험2(audience 수정): HTTP 404 route not found
직접 계약대로 호출: HTTP 200

참고 자료

• Agents in Microsoft Foundry 
• Use function calling with Microsoft Foundry agents 
• Integrate custom tools into your agent 
• Connect agents to Model Context Protocol servers 

자료 확인: 2026-10-21 · 적용 사례 교정: 2026-10-23. 사례는 교육용이며 Azure API 호출·요금은 실행 검증하지 않았습니다.

3.2 대화·기억·지식 연결

세부 학습 목표

• 대화 상태·사용자 기억·외부 검색 지식을 수명·목적으로 구별한다.
• 사용자/조직 범위·갱신·삭제·문맥 예산을 정하고 오래된 기억과 현재 사실의 충돌을 처리한다.

개요

• 대화 상태: 현재 대화를 이어 가는 질문·도구 호출·결과.
• 사용자 기억: 다음 대화에도 재사용할 선호나 정보.
• 검색 지식: 외부 문서에서 가져온 업무 근거.
• 보존 기준: 사용자 범위·유효 기간·갱신·삭제 정책 지정.

세 종류의 문맥을 구분하기

• “아까 말한 주소로 보내줘”라는 요청에는 앞선 대화가 필요합니다.

  “짧게 설명해 달라”는 선호는 다음 대화에도 유용할 수 있습니다. “이번 달 배송 규정”은 최신 업무 문서를 검색해야 합니다. 이 세 정보를 같은 저장소에 무제한 쌓으면 유효 기간과 접근 범위가 섞입니다.

• Responses API에서는 이전 응답이나 대화 상태를 연결하는 방식을 사용할 수 있습니다.

  상태를 서버에서 관리하든 앱에서 메시지 목록으로 관리하든 어떤 대화의 항목이 다음 호출에 들어가는지 확인해야 합니다. 대화 식별자 하나가 모든 사용자가 공유하는 전역 기억이 되도록 구성하지 않습니다.

사용자 기억을 가져오는 경계

다음은 사용자 범위를 이해하기 위한 로컬 예제입니다. 실제 Foundry 메모리 API의 구현이 아니며 두 가상 사용자의 선호를 분리합니다.

preferences = {
    "user-a": {"language": "ko", "length": "short"},
    "user-b": {"language": "en", "length": "normal"},
}
 
def load_preferences(authenticated_user):
    return dict(preferences.get(authenticated_user, {}))
 
alice = load_preferences("user-a")
bob = load_preferences("user-b")
assert alice["language"] == "ko"
assert bob["language"] == "en"
alice["language"] = "ja"
assert preferences["user-a"]["language"] == "ko"
print("사용자별 선호 분리 확인")

• 반환한 복사본을 바꿔도 저장된 원본 선호는 변경되지 않습니다.

  이 예제의 값은 문자열이므로 얕은 복사인 dict(...)로 분리할 수 있습니다. 중첩된 사전이나 리스트까지 분리해야 한다면 별도 복사 방법이 필요합니다. 운영 서비스에서는 저장 권한과 동시 수정, 사용자 식별·삭제 정책도 구현하고 목적에 필요한 정보만 기억으로 보존합니다.

• Foundry의 관리형 기억 기능은 현재 문서에서 preview로 안내되는 부분이 있습니다.

  사용 시점의 지원 모델·저장 범위·권한·추출/검색 동작을 확인합니다. 앱 자체의 기억 저장소를 사용하더라도 같은 경계 검사가 필요합니다.

오래된 기억과 업무 사실을 충돌 없이 사용하기

• 사용자가 과거에 “서울 지점”을 선호했다고 말했어도 현재 주문의 배송지가 부산이면 주문 도구의 실제 결과를 먼저 확인해야 합니다.

  기억의 선호를 현재 업무 사실로 승격하지 않습니다. 선호·확인된 사실·추정의 출처를 구분하면 충돌을 설명할 수 있습니다.

• 긴 대화는 문맥 예산을 차지합니다.

  필요한 항목을 선별하거나 요약하되 주문 번호·승인 조건·도구 결과 같은 중요한 사실이 손실되지 않는지 검토합니다. 요약 문장이 실제 변경 실행의 증거를 대신하게 만들지 않습니다.

에이전트의 도구·지식·기억 선택

• 지식은 답변의 근거가 되는 자료이고, 대화 상태는 현재 실행 문맥이며, 기억은 이후 세션에 재사용하도록 저장한 정보입니다.

  도구는 외부 시스템을 읽거나 바꿀 수 있으므로 허용 기능과 실행 조건을 따로 정의합니다.

• 상황: 출장 예약 에이전트가 고객 선호 좌석을 기억하고 항공권 비용을 확인하며 실제 예약을 진행하려 합니다.

• 적용: 회사 출장 규정은 검색 지식으로, 이번 여행의 날짜와 선택한 항공편은 대화 상태로, 다음 출장에도 쓸 좌석 선호는 사용자별 기억으로 나눕니다.

  기억에는 보존·삭제 기준을 두고, 항공권 가격 조회와 예약 실행은 각각 도구로 연결합니다. 예약 전에는 현재 가격·대상·사용자 권한을 확인하고 승인을 받습니다. 기억된 선호나 과거 요청은 이번 예약의 승인을 대신하지 않습니다.

대화 상태와 장기 기억

• 세션 상태는 현재 대화의 진행 문맥이고 장기 기억은 다음 대화에도 재사용하기 위해 저장한 정보입니다.

  둘 모두 사용자·테넌트 경계를 명확히 해야 합니다.

• 상황: 고객이 “내 배송지 기억을 삭제해 달라”고 요청했습니다.

• 적용: 세션 상태와 장기 기억 저장소의 해당 정보 및 파생 캐시·복사본 정책을 함께 점검해야 합니다.

확인 문제

user=U17 / preference=간결한 답변
memory: U17 선호, refund_days=30 (작년 저장)
current_policy: refund_days=14 (이번 달 적용)
tool get_order(order_id=O88): owner=U52 / status=200
authorization_check: skipped

참고 자료

• Create and use memory in Foundry Agent Service (preview) 
• Use the Azure OpenAI Responses API 
• What is Foundry IQ? 

자료 확인: 2026-10-21 · 적용 사례 교정: 2026-10-23. 사례는 교육용이며 Azure API 호출·요금은 실행 검증하지 않았습니다.

3.3 여러 단계의 작업 구성

세부 학습 목표

• 순차·병렬·handoff와 단일/다중 에이전트를 요구와 비용으로 선택한다.
• 자율·준자율 작업에 승인·도구 제한·반복/시간 상한을 둔다.
• 결과 불명과 실패를 구별하고 승인 내용·멱등성·업무 기록으로 중복 변경을 막는다.

개요

• 워크플로: 단계·분기·입출력·종료 조건을 명시.
• 역할 분담: 독립적인 판단이 필요한 경우 에이전트 분리.
• 외부 변경: 승인 내용과 실제 인수를 맞추고 중복 실행 방지.

역할을 나누는 이유와 비용

• 문서 조사와 사실 검토가 필요한 작업에서는 검색 담당과 검토 담당을 나눌 수 있습니다.

  순차 실행은 앞 단계의 결과를 다음 단계에 전달하고, 병렬 실행은 독립 작업을 동시에 수행한 뒤 결과를 모읍니다. Handoff는 대화나 작업의 제어를 다른 역할로 넘기는 흐름입니다.

• 에이전트를 나눌 때는 각 역할의 입력·출력, 사용할 도구, 실패 처리와 종료 조건이 있어야 합니다.

  모든 에이전트가 같은 지침과 권한으로 서로를 호출하면 비용과 지연만 늘 수 있습니다. 단일 도구 호출로 끝나는 문제라면 단순한 앱 흐름도 함께 비교합니다.

• Agent Framework의 오케스트레이션과 Foundry 워크플로는 이런 흐름을 구성하는 수단입니다.

  MCP는 도구 연결, A2A는 원격 에이전트 간 상호작용에 관련된 프로토콜로 이해하고, 앱에 필요한 경계에 맞게 도입합니다.

견적에서 발주까지

• 견적 조회는 데이터를 읽는 작업이고 발주는 외부 상태를 바꾸는 작업입니다.

  견적을 확인하고 사용자가 승인한 뒤 발주하도록 분리합니다. 승인받은 금액·수신자·품목이 바뀌면 같은 승인으로 처리해도 되는지 다시 확인해야 합니다.

• 네트워크가 끊기면 서버는 발주했는데 앱이 성공 응답을 못 받았을 수 있습니다.

  이때 새 요청으로 무조건 발주하면 주문이 중복됩니다. 멱등성(idempotency)은 같은 작업을 반복 요청해도 중복 부작용을 만들지 않도록 계약하는 성질입니다. 키를 쓰는 실제 정책은 업무 서비스가 서버 측에서 보장해야 합니다.

중복 처리를 관찰하는 로컬 예제

completed = {}
 
def place_order(request_key, approved_payload):
    if request_key in completed:
        if completed[request_key]["payload"] != approved_payload:
            raise ValueError("같은 키에 다른 주문 내용")
        return completed[request_key]["order_id"]
    order_id = f"PO-{len(completed) + 1}"
    completed[request_key] = {
        "payload": dict(approved_payload), "order_id": order_id
    }
    return order_id
 
payload = {"item": "부품 A", "quantity": 2}
first = place_order("request-17", payload)
second = place_order("request-17", payload)
assert first == second
assert len(completed) == 1
print(first)

교육용 기대 출력은 PO-1입니다. 이 메모리 사전은 동시 요청·장애 복구를 처리하는 운영 구현이 아닙니다. 실제 서비스에서는 영속 저장과 동시성 제어, 사용자·작업 범위에 맞춘 키, 승인 유효성 검사를 설계합니다.

• 반복 횟수·시간·비용·도구 범위의 상한을 정하고, 계속 실패하면 사람이 확인하거나 안전하게 종료하도록 합니다.

  완료 문장뿐 아니라 실제 주문 ID·도구 결과·승인 기록이 작업 완료의 근거가 됩니다.

다중 에이전트 협업 설계

• 여러 에이전트는 독립 역할에 따른 분업이 필요할 때 유용하지만 호출 수·지연·오류 지점이 늘어납니다.

  단순한 순차 작업이라면 일반 워크플로가 더 적합할 수 있습니다.

• 상황: 계약 검토 업무를 사실 추출, 위험 분석, 최종 요약의 3단계로 나누려 합니다.

• 적용: 여러 단계가 필요한 것만으로 다중 에이전트가 필수인 것은 아닙니다.

  역할별 독립 판단이 필요한 경우에만 나누고 단순 순서 작업은 고정 워크플로를 우선 검토합니다.

사람 승인과 도구 제한

• Human-in-the-loop는 단순 확인 버튼이 아니라 승인 대상, 표시할 근거, 승인자 신원, 변경 전 최종 검사와 감사 기록까지 포함합니다.

• 상황: 계약 수정 에이전트가 외부 서비스에 변경 내용을 제출하려 합니다.

• 적용: 수정 전후 차이, 대상·영향 범위, 예상 비용, 도구 동작과 취소 가능성을 표시하고 승인 결과를 기록합니다.

확인 문제

workflow=W8 / approved_quote=Q17
request1: create_order(Q17), operation_id 없음
server: order O31 생성 / 응답 네트워크 유실
request2: create_order(Q17), operation_id 없음
server: order O32 생성

retriever output:
  {"claim":"상한 8만원","source_id":"P3","quote":"숙박 상한 8만원"}
handoff payload:
  {"claim":"상한 8만원"}
reviewer instruction: 원문 인용으로 사실 확인
reviewer result: 검증 자료 없음

검색 결과: 10월 28일 14:00 / 참석자 A,B
approval A7: 10월 28일 14:00 / 참석자 A,B
실행 인수: 10월 28일 16:00 / 참석자 A,B
tool: send_invitation
approval_id: A7

참고 자료

• Workflow concepts 
• Workflow orchestrations 
• What are hosted agents? 
• Baseline Microsoft Foundry chat reference architecture 
• Connect to an A2A agent endpoint 

자료 확인: 2026-10-21 · 적용 사례 교정: 2026-10-23. 사례는 교육용이며 Azure API 호출·요금은 실행 검증하지 않았습니다.

상담 에이전트가 담당 에이전트로 작업을 넘겼다는 메시지를 만들었습니다. 그러나 대상 에이전트의 실제 수신·실행 기록은 없습니다.