본문으로 건너뛰기

REST API 도구

Sinaptic® DROID+ 에이전트는 외부 HTTP 엔드포인트를 도구로 호출할 수 있습니다. 이를 통해 에이전트는 별도의 코드 작성 없이도 내부 서비스, 서드파티 API, 웹훅 등 모든 REST API와 상호작용할 수 있습니다.

설정​

에이전트의 YAML 설정 파일에 REST API 도구를 직접 추가하세요.

# configs/agents/my-agent.yaml
name: "my-agent"

tools:
  - name: "get-weather"
    type: "rest_api"
    description: "도시의 현재 날씨 정보를 가져옵니다"
    url: "https://api.weather.example.com/current?city=${city}"
    method: "GET"
    headers:
      Authorization: "Bearer ${WEATHER_API_KEY}"
    timeout: "10s"

  - name: "create-ticket"
    type: "rest_api"
    description: "지원 티켓을 생성합니다"
    url: "https://api.example.com/tickets"
    method: "POST"
    headers:
      Content-Type: "application/json"
      Authorization: "Bearer ${INTERNAL_API_KEY}"
    timeout: "15s"

필드 설명​

필드명타입필수 여부설명
namestring필수도구 식별자 (LLM이 사용)
typestring필수반드시 rest_api여야 합니다
descriptionstring권장LLM이 이 도구를 언제 사용할지 결정하는 데 도움을 주는 설명
urlstring필수엔드포인트 URL (환경 변수를 위한 ${VAR} 구문 지원)
methodstring필수HTTP 메서드: GET, POST, PUT, DELETE
headersmap선택요청에 포함할 HTTP 헤더
timeoutstring선택요청 제한 시간 (기본값: 30s)

작동 방식​

  1. LLM은 도구의 name과 description을 바탕으로 REST API 도구 호출 여부를 결정합니다.
  2. Sinaptic® DROID+는 설정된 메서드, URL, 헤더 및 LLM이 제공한 본문(body)을 사용하여 HTTP 요청을 보냅니다.
  3. 응답 결과는 도구 실행 결과로서 LLM에게 반환됩니다.
  4. LLM은 이 결과를 바탕으로 사용자에게 보낼 최종 응답을 구성합니다.

보안​

  • REST API 도구는 에이전트의 SinapticAI 설정을 준수합니다. 도구의 입출력 데이터는 개인정보(PII) 유출 및 인젝션 공격 시도에 대해 스캔됩니다.
  • 헤더에 포함되는 API 키나 보안 비밀번호 등은 반드시 환경 변수(${VAR})를 사용하세요. 코드에 직접 입력하지 마십시오.
  • timeout 필드는 느린 엔드포인트로 인해 도구가 무한히 대기 상태에 빠지는 것을 방지합니다.

예시​

내부 마이크로서비스 호출​

tools:
  - name: "lookup-order"
    type: "rest_api"
    description: "주문 ID로 주문 상태를 조회합니다"
    url: "https://internal-api.example.com/orders/${order_id}"
    method: "GET"
    headers:
      X-Service-Token: "${INTERNAL_TOKEN}"
    timeout: "5s"

웹훅 보내기​

tools:
  - name: "notify-slack"
    type: "rest_api"
    description: "Slack 채널로 알림을 보냅니다"
    url: "${SLACK_WEBHOOK_URL}"
    method: "POST"
    headers:
      Content-Type: "application/json"
    timeout: "10s"