클라이언트 함수 도구

클라이언트 코드에서는 액세스할 수 있지만 OpenAPI 또는 MCP와 같은 호스팅 도구에서는 액세스할 수 없는 기능이 있으면 클라이언트 함수 도구를 사용할 수 있습니다. 클라이언트 함수 도구는 항상 에이전트가 아닌 클라이언트 측에서 실행됩니다.

작동 방식

상담사가 클라이언트 함수 도구를 트리거하는 경우:

  1. 세션 차단: 대화 세션이 서버 측에서 효과적으로 '차단'됩니다.
  2. 클라이언트 실행: 클라이언트 애플리케이션이 도구 호출을 식별하고 로컬 환경에서 해당 로직을 실행해야 합니다.
  3. 응답 제공: 실행이 완료되면 클라이언트 애플리케이션은 toolResponses 필드를 사용하여 에이전트에게 응답을 다시 제공해야 합니다.

에이전트는 대화를 진행하기 전에 이 응답을 기다립니다.

구성

클라이언트 함수 도구를 만들 때 에이전트가 클라이언트 측 코드를 이해하고 상호작용하는 방식을 정의합니다.

  • 이름: 도구의 고유 식별자입니다 (예: open_settings).
  • 설명: 도구의 목적에 대한 간략한 설명입니다. 에이전트 모델은 이 설명을 사용하여 함수를 호출할 시기를 결정합니다.
  • 입력/출력 스키마: OpenAPI 형식으로 정의됩니다. 이는 에이전트가 전송하고 수신할 것으로 예상되는 데이터의 구조를 결정합니다.

사용 사례

클라이언트 함수 도구는 다음과 같은 경우에 적합합니다.

  • UI/UX 작업: 애플리케이션 인터페이스의 변경사항을 트리거합니다 (예: '지원 화면으로 이동').
  • 로컬 기기 데이터: 앱 컨텍스트 내에서만 사용할 수 있는 정보에 액세스합니다 (예: '현재 배터리 잔량 가져오기').
  • 비공개 API: 클라이언트 측 환경에서만 연결할 수 있는 서비스와 통합합니다.

예

다음 예는 클라이언트 애플리케이션이 함수를 호출해야 함을 나타내는 세션 응답입니다.

"outputs": [
  {
    "toolCalls": {
      "toolCalls": [
        {
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "args": {
            "zip_code": "92031"
          },
          "displayName": "get_nearest_store"
        }
      ]
    },
    "turnCompleted": true,
  }
]

다음 예는 도구 출력이 요청에 첨부된 후속 세션 실행입니다. 클라이언트 애플리케이션은 이러한 필드를 채우고 이전 메시지와 동일한 id, tool, display_name 값을 입력해야 합니다.

"inputs": [
  {
    "toolResponses": {
      "toolResponses": [
        {
          "displayName": "get_nearest_store",
          "id": "<execution id>",
          "tool": "<client function tool's resource name>",
          "response": {
            "name": "Alibaba",
            "address": "43 Alpha Road, Mountain View, CA 92039, USA"
          },
        }
      ]
    }
  }
]