코드로 도구 관리
Python 및 JavaScript SDK로 에이전트 도구를 구축, 편집 및 버전 관리
개요
도구는 매개변수용 중첩 JSON 스키마가 포함된 구성으로 저장됩니다. 이 구성을 직접 작성하려면 경로 매개변수를 URL과 일치시키고, required 목록을 해당 속성과 일치시키며, 모든 매개변수에 정확히 하나의 값 소스를 지정해야 합니다. Python 및 JavaScript SDK의 도구 빌더를 사용하면 메서드 체이닝으로 동일한 도구를 설명할 수 있습니다. 그러면 tools.create() 및 tools.update()가 이미 수락하는 요청을 생성합니다.
다음과 같은 작업에 사용하세요.
- 웹훅, 클라이언트 및 시스템 도구를 코드로 정의하고 다른 코드 변경과 마찬가지로 검토합니다.
- 도구를 로드하고 매개변수 하나를 변경한 뒤 나머지 구성은 건드리지 않고 다시 푸시합니다.
- 도구를 JSON으로 버전 관리에 저장하고 CI에서 검증합니다.
빌더는 SDK 내에서 완전히 실행됩니다. 새 API 엔드포인트를 호출하지 않으며, 빌드한 모든 항목은 대시보드에서 열고 편집할 수 있습니다.
요구 사항
- Python:
elevenlabs패키지. 빌더는elevenlabs.agent_tools에서 가져옵니다. - JavaScript:
@elevenlabs/elevenlabs-js패키지. 빌더는 패키지 루트에서 내보냅니다.
웹훅 도구 구축
Tool.webhook(name, description)은 웹훅 도구를 시작합니다. 이름과 설명은 LLM이 도구 호출 여부를 결정할 때 확인하는 정보입니다. 이 예시는 발신자가 제공한 번호로 주문을 조회하고, 워크스페이스의 시크릿에서 API 키를 전송하며, 주문 상태를 동적 변수에 저장합니다.
요청 메서드는 HTTP 메서드와 URL을 설정합니다. URL의 {name} 자리 표시자는 경로 매개변수로 채워집니다.
이미 존재하는 이름의 매개변수나 헤더를 설정하면 해당 항목을 대체하되 위치는 유지합니다. remove_path_param(), remove_query_param(), remove_header(), remove_assignment()(JavaScript에서는 removePathParam() 등)을 사용하면 항목을 제거할 수 있습니다. 매개변수 이름은 경로, 쿼리, 본문 전체에서 고유해야 합니다.
본문은 속성을 하나씩 추가해 구성하는 객체 스키마입니다.
매개변수 스키마
Schema는 웹훅 및 클라이언트 도구에서 사용하는 매개변수 스키마를 빌드합니다. 모든 메서드는 새 스키마를 반환하고 호출된 기존 스키마는 변경하지 않으므로, 스키마를 한 번 정의해 여러 도구에서 사용할 수 있습니다.
값의 출처
모든 리터럴에는 위치와 관계없이 정확히 하나의 값 소스가 필요합니다. 매개변수, 본문, 응답 스키마, 객체 또는 배열 내부 모두 마찬가지입니다. 객체나 배열 자체에도 값 소스를 하나 지정할 수 있으며, 이 경우 전체 값을 제공합니다.
객체나 배열에서 describe()는 LLM을 위해 컨테이너를 문서화하며, 각 속성이나 요소에는 여전히 자체 소스가 필요합니다.
기타 스키마 메서드
헤더 및 인증
헤더 값은 네 곳 중 하나에서 가져옵니다. 민감한 정보에는 시크릿 또는 환경 변수를 사용해 값이 도구 구성에 표시되지 않도록 하세요.
AuthConnection.id(id)는 ID로 워크스페이스의 인증 연결을 사용합니다. AuthConnection.env_var(label) / AuthConnection.envVar(label)는 환경 변수에서 인증 연결을 선택하므로, 동일한 도구 구성이 각 환경에서 서로 다른 연결을 사용할 수 있습니다.
클라이언트 도구 구축
Tool.client(name, description)은 서버가 아닌 애플리케이션에서 실행되는 클라이언트 도구를 시작합니다. param(name, schema)로 매개변수를 추가하세요. 에이전트가 애플리케이션 결과를 기다려야 하는 경우 expects_response / expectsResponse를 설정하세요.
시스템 도구 구축
시스템 도구는 플랫폼에 내장되어 있습니다. 각 도구에는 해당 도구의 설정을 받는 SystemTool 전용 생성자가 있습니다.
두 전송 도구는 transfer(condition, destination, options)에서 목적지를 받습니다. 조건은 LLM에 언제 해당 위치로 전송할지 알려 주며, 목적지는 코드로 워크플로 관리와 동일한 Destination을 사용합니다. SIP URI로 전송하려면 SIP REFER 전송이 필요합니다.
도구 옵션
모든 유형의 도구에서 공유하는 설정은 Python에서는 키워드 인수로, JavaScript에서는 객체로 options()에 전달합니다. 이름은 API의 도구 구성 필드와 일치합니다.
웹훅 도구의 응답 시간 제한은 5300초입니다. 클라이언트 도구는 1120초이며, 완료될 때까지 기다리려면 -1로 설정할 수 있습니다. 이 경우 expects_response / expectsResponse가 필요합니다. follow_redirects / followRedirects에는 허용된 도메인 목록이 필요합니다.
에이전트에 도구 연결
웹훅 및 클라이언트 도구는 tools.create()로 개별 생성하고 ID로 에이전트에 연결하므로 하나의 도구를 여러 에이전트와 공유할 수 있습니다. 시스템 도구는 에이전트 구성의 일부입니다. build_config() / buildConfig()는 에이전트의 내장 도구 항목을 반환합니다.
도구 구성을 인라인으로 보관하는 에이전트의 prompt.tools 필드는 더 이상 사용되지 않습니다. 이 필드는
tool_ids와 함께 사용할 수 없으며, 요청에 이 필드가 포함되면 에이전트의 내장 도구는 해당 필드에 포함된
시스템 도구로 대체됩니다. 대신 tools.create()로 도구를 생성하고 ID로 연결하세요.
기존 도구 편집
Tool.from_response() / Tool.fromResponse()는 tools.get()이 반환한 도구를 로드합니다. 빌더가 모델링하지 않는 필드와 API가 채우는 기본값은 유지되므로, 다시 푸시할 때 변경한 내용만 바뀝니다. as_webhook(), as_client(), as_system()(JavaScript에서는 asWebhook() 등)은 편집할 수 있는 타입 지정 도구를 반환하며, 다른 유형인 경우 None / undefined를 반환합니다.
본문 속성을 변경하려면 본문 스키마를 읽고, 속성을 다시 설정한 다음 본문을 설정하세요.
버전 관리에 도구 저장
to_json_string() / toJSONString()은 API의 와이어 형식으로 도구를 작성합니다. 즉, snake_case 키를 사용하고 모든 수준에서 정렬하며 2칸 들여쓰기를 적용합니다. 이는 CLI가 tool_configs/ 디렉터리에 보관하는 것과 동일한 형식이며, 두 SDK는 같은 도구에 대해 바이트 단위로 동일한 파일을 작성하므로 diff가 작게 유지됩니다. Tool.from_json() / Tool.fromJSON()으로 다시 읽어 올 수 있습니다.
일반적인 설정은 워크플로와 같습니다. elevenlabs tools pull로 파일을 초기화하고, 직접 또는 빌더로 편집한 뒤, 모든 풀 리퀘스트에서 CI로 Tool.from_json(file).build() / Tool.fromJSON(file).build()를 실행하고, 병합 시 tools.update() 또는 elevenlabs tools push로 푸시합니다.
검증
메서드 체이닝 호출 자체는 실패하지 않습니다. build(), build_config() / buildConfig(), to_json() / toJSON(), to_json_string() / toJSONString()는 전체 도구를 검사하고 단일 ToolValidationError를 발생시키거나 throw합니다. 이 오류의 issues 목록에는 모든 문제가 포함되며, 각 문제에는 body.reason과 같은 해당 부분의 code, message, path가 있습니다.
오류에는 다음이 포함됩니다.
- 경로 매개변수가 없는 URL 자리 표시자 또는 자리 표시자가 없는 경로 매개변수.
{{system__env_api_host}}와 같은 환경 변수 템플릿은 자리 표시자가 아닙니다. - 값 소스가 없거나 둘 이상인 리터럴.
GET의 본문 또는POST,PUT,PATCH의 본문 누락.- 경로, 쿼리, 본문 중 둘 이상의 위치에 같은 매개변수 이름이 있는 경우.
- 필수 속성의
omit(), 문자열이 아닌 스키마의choices(), 또는 스키마 유형과 일치하지 않는 상수. - 목적지가 없는 전송 도구, 잘못된 종류의 목적지 또는 SIP REFER 전송이 없는 SIP URI 목적지.
- 도구 유형에 적용되지 않는 옵션 또는 범위를 벗어난 시간 제한.
SDK보다 새로운 도구 유형
API 또는 파일에서 로드한 도구는 MCP 도구처럼 빌더가 편집할 수 없는 유형일 수 있습니다. 이러한 도구는 "other" 유형으로 로드되며, from_json() / fromJSON() 및 to_json_string() / toJSONString()을 거쳐도 변경되지 않습니다. build()는 on_warning / onWarning을 통해 이를 경고로 보고합니다.