​
API 도구

API 도구를 활용하면 에이전트가 사용자의 HTTP 엔드포인트나 외부 API와 직접 통신하여 다양한 작업을 수행할 수 있습니다. 이를 통해 에이전트의 기능을 원하는 대로 확장하고 세밀하게 제어할 수 있습니다.

​
API 도구 설정 이해하기

API 도구를 효과적으로 설정하고 관리하기 위해 다음 주요 구성 필드들을 이해하는 것이 중요합니다. 각 필드는 API 도구가 어떻게 동작하고 에이전트와 상호작용하는지를 정의합니다.

​
주요 구성 필드:

  • 이름: 도구를 식별하는 고유한 이름입니다. 에이전트는 이 이름을 사용하여 특정 API 도구를 호출합니다. (예: get_user_details, submit_support_ticket)

  • 설명: 도구가 어떤 작업을 수행하는지, 어떤 기능을 가지고 있는지, 그리고 에이전트가 어떤 상황에서 이 도구를 사용해야 하는지를 설명하는 자연어 텍스트입니다. 명확한 설명은 에이전트가 도구를 적절히 활용하는 데 핵심적인 역할을 합니다. (예: “사용자 ID를 기반으로 사용자 세부 정보를 가져옵니다.” 또는 “제공된 요약 및 설명으로 새 지원 티켓을 제출합니다.”)

  • 엔드포인트 URL: API가 호스팅되어 요청을 수신하는 전체 URL 주소입니다. (예: https://api.example.com/users, https://your-backend.com/submit-ticket)

  • 메서드: 엔드포인트가 예상하는 HTTP 메서드입니다. 주로 "GET", "POST", "PUT", "DELETE" 등이 사용되며, 지정하지 않으면 일반적으로 "POST"로 간주됩니다.

  • 파라미터: API 엔드포인트가 필요로 하는 요청 본문(request body) 또는 쿼리 매개변수(query parameters)를 OpenAPI 3.0 사양에 따라 기술하는 객체입니다. 이를 통해 에이전트는 API 호출에 필요한 데이터를 대화 중에서 어떻게 수집해야 할지 파악할 수 있습니다.

  • 타임아웃: 에이전트가 API 엔드포인트로부터 응답을 기다리는 최대 시간(초)입니다. API의 예상 응답 시간을 고려하여 적절한 값을 설정하세요.

    POST 요청 시 파라미터 예시:

    {
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "사용자의 고유 식별자입니다."
    },
    "includeOrderHistory": {
      "type": "boolean",
      "description": "응답에 사용자의 주문 내역을 포함할지 여부입니다."
    }
  },
  "required": ["userId"]
}

​
에이전트의 API 호출 방식

에이전트가 특정 API 도구를 사용하기로 결정하면, 설정된 메서드를 사용하여 지정된 엔드포인트로 HTTP 요청을 전송합니다. 요청 본문(POST, PUT 등)이나 쿼리 매개변수(GET)는 대화에서 추출된 인수들을 포함하는 JSON 객체 형태로, 사용자가 정의한 파라미터 스키마와 일치하게 됩니다.

예를 들어, get_weather라는 이름의 도구가 있고 에이전트가 대화에서 “런던”의 날씨를 파악했다면, 서버로 전송되는 요청은 다음과 같을 수 있습니다 (메서드: "POST" 가정):

서버로 전송되는 요청 예시:

POST https://your-api-server.com/get_weather
Content-Type: application/json

{
  "location": "런던"
}

​
서버의 응답 처리

요청을 받은 서버는 해당 작업을 처리한 후 JSON 형식의 응답을 반환해야 합니다. 이 JSON 응답 내용은 에이전트에게 전달되어, 다음 행동을 결정하거나 사용자에게 관련 정보를 전달하는 데 사용됩니다.

성공적인 서버 응답 예시:

{
  "temperature": "15°C",
  "condition": "Cloudy",
  "forecast": "오늘 늦게 약한 비가 예상됩니다."
}

API 호출 중 오류가 발생했다면, 서버는 적절한 HTTP 상태 코드(예: 4xx 또는 5xx)와 함께 오류의 상세 내용이 담긴 JSON 본문을 반환하는 것이 좋습니다.

{
  "error": "잘못된 위치가 제공되었습니다.",
  "details": "지정된 위치에 대한 날씨 데이터를 찾을 수 없습니다."
}

API 도구를 명확하게 정의하고 올바르게 설정함으로써, 에이전트가 사용자의 기존 인프라 및 다양한 서비스와 효과적으로 상호작용할 수 있는 강력한 기반을 마련할 수 있습니다.