이득:
- Agent를 '모델 + 도구 + 루프'로 정의하고 필요할 때 결정
- 이름, 설명 및 input_schema를 사용하여 도구 정의 작성
- tool_use 및 tool_result 루프의 흐름 및 오류 처리 모니터링
지금까지 모델은 항상 텍스트 입력을 받고 텍스트 응답을 생성하는 한 가지 작업을 수행했습니다. 그러나 실제 작업에는 텍스트 이상의 것이 필요한 경우가 많습니다. 계산 수행, 데이터베이스 쿼리, API 호출, 현재 환율 확인. 모델은 이러한 일을 스스로 할 수는 없지만 언제 수행해야 하는지 결정하고 다른 사람에게 이를 수행하도록 요청할 수 있습니다. 이것이 도구 사용이 모델을 제공하는 것이며 이것이 AI 에이전트의 기초입니다. 이번 단원에서는 에이전트가 무엇인지, 도구가 어떻게 정의되는지, tool_use 루프가 어떻게 작동하는지 알아봅니다.
에이전트란 무엇입니까? 모델 + 도구 + 루프
AI 에이전트는 모델(결정을 내리는 두뇌), 도구(모델이 호출할 수 있는 기능: 날씨, 데이터베이스 쿼리, 이메일 보내기), 루프(루프, 모델이 도구를 호출하고 결과를 얻고 수행할 작업을 다시 결정하는 등)의 세 부분으로 구성됩니다.
중요한 차이점: 단일 패턴 호출은 에이전트가 아닙니다. 에이전트는 모델이 단계별로 진행되며 각 단계에서 도구 결과에 따라 다음 동작을 선택하는 프로세스입니다. "인간처럼 생각하고, 손을 사용하고, 결과를 보고, 다시 생각해보세요."
중요한 사실: 모델 자체가 차량을 작동하지 않습니다. 모델은 "이 입력을 사용하여 이 도구를 호출하고 싶습니다"라고 말합니다. 애플리케이션(하네스라고 함)은 도구를 실행하고 결과를 모델에 반환합니다. 이는 보안에 매우 중요합니다. 모델이 시스템에 직접 영향을 미치지 않습니다. 모든 행동은 귀하의 통제하에 있습니다.
팁: 상담원과 관련된 모든 문제를 해결하려고 하지 마세요. 대리인; 지연, 비용 및 오류의 위험이 증가합니다. 먼저 물어보세요. "이 문제가 한 번의 통화로 해결될까요, 아니면 고정된 워크플로로 해결될까요?" 대답이 '예'라면 대리인이 필요하지 않습니다. 에이전트는 단계를 미리 알 수 없는 개방형 작업에 사용됩니다.
도구 정의: 이름, 설명, input_schema
모델에 도구를 도입하려면 다음 세 가지를 제공해야 합니다.
- 이름: 차량의 신원(예: get_weather.
- 설명: 도구의 기능과 호출 시기입니다. 이는 모델이 적시에 적절한 도구를 선택할 수 있도록 하는 가장 중요한 영역입니다. "무엇을 하는지"뿐만 아니라 "언제 호출하는지"도 적으세요.
- input_schema(입력 스키마): 도구가 기대하는 매개변수와 유형을 정의하는 JSON 스키마입니다.
# 차량 정의(개념 — JSON 스키마){ "name": "get_order_status", "description": "주문의 현재 배송 상태를 검색합니다. 사용자가 주문 번호가 어디에 있는지 또는 언제 도착할지 물을 때 호출합니다.", "input_schema": { "type": "object", "properties": { "order_no": {"type": "string", "description": "주문 번호, e.g. SP-1024"} }, "필수": ["order_no"] }}
좋은 도구 설명을 위한 규칙: 명확하고 간결한 이름, "사용 시기"가 포함된 설명, 각 매개변수에 대한 설명, 실제로 필수 항목을 필수 항목으로 설정합니다. 차량 수에 집중하세요. 수십 개의 유사한 차량 모델이 놀랍습니다.
지역
그것은 무엇을 합니까?
좋은 예
나쁜 예
이름
차량번호
주문_상태_getir
가져오다
설명
기능 + 호출 시기
"화물 상태를 반환합니다. 사용자가 주문 위치를 물으면 전화하세요."
"데이터를 가져옵니다"
입력_스키마
매개변수 유형 및 요구사항
{order_no: 문자열, 주석 처리됨}
다이어그램 없음 / 설명 없음
tool_use → tool_result 루프
주기는 다음과 같이 단계별로 진행됩니다.
- 사용자 질문과 도구 설명을 모델에 보냅니다.
- 모델은 직접 응답하거나 tool_use 블록을 생성합니다. "order_no=SP-1024로 order_durumu_getir를 호출하세요."
- 귀하의 애플리케이션은 실제로 도구를 실행합니다(데이터베이스 쿼리).
- 결과를 tool_result로 모델에 다시 보냅니다.
- 이 결과를 통해 모델은 최종 답변을 생성하거나 다른 도구를 호출합니다. 모델이 "완료되었습니다"라고 말할 때까지 주기가 계속됩니다.
# 에이전트 루프(개념)messages = [user_question]while True: response = model.uret(messages, tools=tool_definitions) if response.tur == "tool_use": result = Harness.run(response.tool_name, response.entries) # APPLICATION은 메시지를 실행합니다. += [response, tool_result(result)] # 결과 반환 else: break # final response; 루프 종료
최신 SDK는 이 루프를 실행하는 도구 실행기를 제공합니다. 도구 기능만 작성하면 됩니다. 그러나 그것은 바로 뒤에서 일어나는 일입니다.
오류 관리
도구가 실패할 수 있습니다. 주문을 찾을 수 없으며 API 시간이 초과되고 입력이 유효하지 않습니다. 도구를 실행할 수 없는 경우 오류를 설명적인 tool_result("오류: 주문 번호 SP-9999를 찾을 수 없음") 및 오류 플래그로 모델에 반환합니다. 모델은 이를 보고 사용자에게 부드럽게 설명하거나 다른 방식을 시도할 수 있습니다. 오류를 무시하고 빈 결과를 반환하지 마십시오. 모델은 무엇이 잘못되었는지 알아야 합니다.
약함/강함 차량 설명
약함(부정 명사, "언제" 없음):
이름: "데이터", 설명: "데이터 가져오기"# 모델은 언제 어떻게 호출할지 모릅니다. 전혀 전화하지 않거나 잘못 전화합니다.
강력(네트 이름 + 시기 + 매개변수 설명):
name: "musteri_bakiyesi_getir"description: "고객의 현재 계정 잔액을 반환합니다. 사용자가 차변, 대변 또는 잔액을 요청할 때 호출합니다. 결제하지 않습니다."input_schema: {custeri_id: string ("Customer ID")}# 모델은 한도를 알고 올바른 매개변수를 사용하여 적시에 호출합니다.
미니 케이스 3개
사례 1 - 불필요한 에이전트. 한 팀은 다중 도구 에이전트를 사용하여 "텍스트 요약" 비즈니스를 구축했습니다. 각 요약에는 4번의 모델 호출과 9초가 소요됩니다. 그 직업은 실제로 원콜 직업이었습니다. 상담원을 없애고 단일 통화로 줄였더니 시간은 1.5초, 비용은 1/4로 줄었습니다. 교훈: 정말 필요할 때 에이전트를 사용하세요.
사례 2 — 약한 설명, 잘못된 호출. 지원 에이전트에서는 잔액 질문과 배송 질문 모두에서 fetch라는 모호한 도구가 모델에 의해 무작위로 호출되었습니다. 차량을 Balance_getir, Cargo_durumu_getir로 나누고 '콜 시' 설명을 추가한 결과 잘못된 차량 선택이 50건 중 18건에서 1건으로 줄었습니다.
사례 3 — 오류를 삼켰습니다. 주문을 찾을 수 없을 때 상담원이 빈 결과를 반환했습니다. 모델은 이를 '주문이 배송됐다'고 해석해 고객을 오도했다. 오류 메시지가 tool_result("주문을 찾을 수 없음")에 명시적으로 기록되면 모델은 "이 번호를 찾을 수 없습니다. 확인해 주시겠습니까?"라고 올바르게 말합니다. 그는 말하기 시작했습니다.
일반적인 실수
- 모든 것을 상담원에게 맡기기: 통화 한 번이면 충분하지만 상담원은 비용과 지연을 추가합니다.
- 모호한 차량 설명: 모델은 언제 호출해야 할지 모릅니다. 잘못 선택합니다.
- 모델이 차량을 운행한다고 생각하면: 하네스가 차량을 운행합니다. 모델이 원할 뿐이에요.
- 오류 삼키기: 모델은 무엇이 잘못되었는지 알아야 합니다. open tool_result로 오류를 제공합니다.
- 유사한 차량이 너무 많으면 모델이 혼란스러워집니다. 도구 세트를 집중적으로 최소화하세요.
주의: 모델이 "그 차량을 호출하세요"라고 말한다고 해서 조치를 취해야 한다는 의미는 아닙니다. 파괴적인 도구(삭제, 체크아웃, 이메일)에서는 애플리케이션이 호출을 맹목적으로 실행해서는 안 됩니다. 이것이 다음 단원의 보안 주제의 핵심입니다.
요약하면
- 에이전트 = 모델(결정) + 도구(기능) + 루프(도구 호출, 결과 얻기, 다시 결정).
- 단일 패턴 호출은 에이전트가 아닙니다. 에이전트는 단계별 프로세스입니다.
- 모델은 차량을 운행하지 않습니다. 애플리케이션이 실행되고(하네스) 결과를 tool_result로 반환합니다.
- 도구는 이름, 설명(구체적으로 "호출 시기") 및 input_schema로 식별됩니다.
- 루프는 tool_use → 하네스 실행 → tool_result → 모델이 "완료"라고 표시될 때까지 계속됩니다. 오류는 모델에 명시적으로 보고됩니다.
응용과제
귀하의 비즈니스에서 에이전트에게 제공할 수 있는 3가지 도구를 디자인하십시오. (1) 각각에 대해 "call when"으로 이름, 설명 및 input_schema를 작성합니다. 적어도 하나는 비파괴적인 읽기 도구이고 하나는 계산 도구로 두십시오. (2) 현실적인 사용자 질문을 선택하고 모델이 어떤 입력으로 호출할 도구와 도구 결과가 도착한 후 수행할 작업을 단계별로 (루프에서) 수동으로 작성합니다. (3) 도구 중 하나가 실패하는 시나리오를 설정하고 오류 메시지가 모델에 어떻게 반환되는지 보여줍니다.
체크리스트
- [ ] 에이전트를 "모델 + 도구 + 루프"로 정의하고 필요할 때 결정할 수 있습니다.
- [ ] 나는 하네스가 차량을 작동한다는 것을 알고 있으며, 모델은 단지 그것을 원합니다.
- [ ] 이름, 설명("호출 시기") 및 input_schema를 사용하여 견고한 차량 설명을 작성할 수 있습니다.
- [ ] tool_use → tool_result 주기를 단계별로 따라갈 수 있습니다.
- [ ] 도구 오류를 open tool_result로 모델에 보고합니다.