​

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 요청 시 파라미터 예시:
  Copy

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

​

에이전트의 API 호출 방식

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

{
  "location": "런던"
}

​

서버의 응답 처리

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

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