코드 도구

코드 도구를 사용하면 자체 웹훅 엔드포인트를 구축하고 호스팅하지 않아도 샌드박스 처리된 서버 측 환경에서 에이전트가 맞춤 JavaScript를 실행할 수 있습니다. 내장 코드 편집기에서 로직을 한 번 작성하면 에이전트가 도구를 호출할 때마다 ElevenLabs가 이를 실행합니다.

개요

코드 도구는 에이전트가 호출할 때 실행되는 JavaScript 함수입니다. 함수 본문 전체를 작성하므로 작업에 따라 도구가 많은 작업을 수행할 수도, 적은 작업만 수행할 수도 있습니다.

• 맞춤 계산: 도구 호출 파라미터만 사용하여 가격 규칙, 단위 변환, 점수 산정 로직 또는 날짜 계산을 적용합니다. 네트워크 액세스가 필요하지 않습니다.
• 외부 API 호출: 허용 목록에 있는 도메인에서 fetch를 사용하며, 워크스페이스 시크릿과 인증 연결이 함수 컨텍스트에 삽입됩니다.
• 여러 소스 결합: 2~3개의 API를 호출하고 결과를 병합, 비교 또는 조정한 뒤 단일 응답을 반환합니다.
• 조건부 분기: 분기마다 별도의 도구가 필요하지 않도록 도구 호출 파라미터에 따라 서로 다른 로직을 실행합니다.
• 데이터 재구성: 원본 업스트림 응답 대신 에이전트에 표시할 구조를 정확히 반환합니다.

작동 방식

코드는 단일 기본 비동기 함수를 내보내는 JavaScript 모듈입니다. 이 함수는 ctx 객체를 받고 도구 결과를 반환합니다.

export default async (ctx) => {
  // ctx.args.<paramName> — the parameters the agent passed to this tool call
  const { city } = ctx.args;
  return { message: `Hello from ${city}!` };
};

반환하는 값은 도구 결과가 됩니다. 이 값은 에이전트에 다시 전달되고, 대화 트랜스크립트에 표시되며, 동적 변수 할당에 사용할 수 있습니다.

ctx 객체

ctx는 호출 시 도구가 액세스할 수 있는 모든 항목의 진입점입니다. 에이전트가 제공하는 파라미터는 항상 ctx.args로 전달됩니다. 시크릿, 구성 값, 인증 연결은 선택 사항이며 도구의 Context object 섹션에서 매핑한 경우에만 표시됩니다.

파라미터 구성

파라미터는 에이전트가 도구를 호출할 때 제공하는 값이며 ctx.args로 전달됩니다. 도구 구성 양식의 Parameters 섹션 또는 코드 편집기의 Params 탭 내 Define Params 하위 탭에서 정의하세요. 각 파라미터에는 데이터 유형, 식별자, 그리고 에이전트가 대화에서 올바른 값을 판단하는 데 사용하는 설명이 필요합니다. 코드는 아래의 ctx.args.appointment_datetime처럼 식별자 아래에서 해당 값을 읽습니다.

컨텍스트 객체 구성

도구의 Context object 섹션에서 시크릿, 구성 값 및 인증 연결을 추가하세요. 각 항목에는 유형과 이름이 필요합니다. 패널에는 아래의 ctx.secrets.DEMO_KEY처럼 각 항목에 대한 정확한 접근자가 표시됩니다.

네트워크 액세스

샌드박스에서 실행되는 코드는 워크스페이스에서 명시적으로 허용한 도메인에만 연결할 수 있습니다. 코드에서 호출해야 하는 도메인을 ElevenAgents Settings의 Code Tool Network Access에서 추가하세요. 다른 도메인에 대한 요청은 실패합니다.

실행 제한

• 타임아웃: 각 실행은 1초에서 최대 30초까지로 설정된 도구의 응답 타임아웃 내에 완료되어야 합니다.
• 외부 패키지 없음: 코드 도구는 현재 npm 종속성 없이 실행됩니다.

코드 테스트

저장하기 전에 코드 편집기의 Run을 사용하여 샘플 파라미터 값으로 코드를 실행하세요.

• Params — 도구에서 정의한 각 파라미터의 테스트 값을 설정합니다.
• Output — 반환된 결과 또는 실행 실패 시 오류를 확인합니다.
• Logs — console.log, console.warn 또는 console.error로 기록된 내용과 빌드 및 실행 시간을 확인합니다.

가이드

이 가이드에서는 온도를 변환하고 친숙한 형식의 문자열을 반환하는 코드 도구를 만들어 보겠습니다.

export default async (ctx) => {
  const { value, from_unit } = ctx.args;
  if (from_unit === "C") {
    const fahrenheit = (value * 9) / 5 + 32;
    return { result: `${value}°C is ${fahrenheit.toFixed(1)}°F` };
  }
  const celsius = ((value - 32) * 5) / 9;
  return { result: `${value}°F is ${celsius.toFixed(1)}°C` };
};

When the user asks to convert a temperature, call convert_temperature with the
value and its unit ("C" or "F"), and read back the result naturally.

인증 예시

시크릿으로 API 호출

export default async (ctx) => {
  const { order_id } = ctx.args;
  const response = await fetch(`https://api.example.com/orders/${order_id}`, {
    headers: {
      Authorization: `Bearer ${ctx.secrets.EXAMPLE_API_KEY}`,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

도구의 Context object 섹션에서 EXAMPLE_API_KEY를 워크스페이스 시크릿에 매핑한 다음, 요청의 이그레스를 허용하도록 Code Tool Network Access에 api.example.com을 추가하세요. 참조하는 값은 플레이스홀더입니다. 실제 시크릿은 이그레스 시 헤더에 대체되며 코드에 절대 표시되지 않습니다.

OAuth 인증 연결로 API 호출

export default async (ctx) => {
  const { customer_id } = ctx.args;
  const response = await fetch(`https://api.example.com/customers/${customer_id}`, {
    headers: {
      "X-With-Auth-Connection": ctx.authConnections.EXAMPLE_CRM,
    },
  });
  if (!response.ok) {
    throw new Error(`Upstream error: ${response.status}`);
  }
  return await response.json();
};

도구의 Context object 섹션에서 EXAMPLE_CRM을 구성된 인증 연결에 매핑하세요. 참조하는 값은 플레이스홀더입니다. 실제 자격 증명은 이그레스 시 헤더에 대체되며 코드에 절대 표시되지 않습니다.

모범 사례

상세한 설명과 함께 직관적으로 도구 이름 지정

어시스턴트가 올바른 도구를 호출하지 않는다면, 각 도구를 선택해야 하는 시점을 더 명확히 이해하도록 도구 이름과 설명을 업데이트해야 할 수 있습니다. 도구 및 인수 이름을 줄이기 위해 약어나 두문자어를 사용하지 마세요.

도구를 호출해야 하는 시점에 관한 자세한 설명을 포함할 수도 있습니다. 복잡한 도구의 경우, 어시스턴트가 해당 인수를 수집하기 위해 사용자에게 무엇을 물어봐야 하는지 알 수 있도록 각 인수의 설명을 포함해야 합니다.

상세한 설명과 함께 직관적으로 도구 파라미터 이름 지정

도구 파라미터에는 명확하고 설명적인 이름을 사용하세요. 해당하는 경우 설명에 파라미터의 예상 형식을 지정하세요(예: 날짜의 경우 YYYY-mm-dd 또는 dd/mm/yy).

어시스턴트의 시스템 프롬프트에 도구를 호출하는 방법과 시점에 관한 추가 정보 제공 고려

시스템 프롬프트에 명확한 지침을 제공하면 어시스턴트의 도구 호출 정확도를 크게 향상할 수 있습니다. 예를 들어, 다음과 같은 지침으로 어시스턴트를 안내하세요.

Use `check_order_status` when the user inquires about the status of their order, such as 'Where is my order?' or 'Has my order shipped yet?'.

복잡한 시나리오에는 컨텍스트를 제공하세요. 예를 들면 다음과 같습니다.

Before scheduling a meeting with `schedule_meeting`, check the user's calendar for availability using check_availability to avoid conflicts.

LLM 선택

함수 호출의 성공에는 LLM 선택이 중요합니다. 일부 LLM은 대화에서 관련 파라미터를 추출하는 데 어려움을 겪을 수 있습니다.