Hoppa till navigering

Verktyg som kod

Bygg, redigera och versionshantera agentverktyg med Python- och JavaScript-SDK:erna

Översikt

Ett verktyg lagras som en konfiguration med kapslade JSON-scheman för sina parametrar. Om du skriver konfigurationen för hand måste du hålla sökvägsparametrar synkroniserade med URL:en, required-listor synkroniserade med sina egenskaper och ge varje parameter exakt en värdekälla. Verktygsbyggaren i Python- och JavaScript-SDK:erna låter dig beskriva samma verktyg med kedjade metodanrop. Den skapar sedan begäran som tools.create() och tools.update() redan accepterar.

Använd den för att:

  • Definiera webhook-, klient- och systemverktyg i kod och granska dem som alla andra kodändringar.
  • Läsa in ett verktyg, ändra en parameter och skicka tillbaka det utan att påverka resten av konfigurationen.
  • Lagra verktyg som JSON i versionshantering och validera dem i CI.

Byggaren körs helt i SDK:n. Den anropar inga nya API-slutpunkter, och allt den bygger kan öppnas och redigeras i kontrollpanelen.

Krav

  • Python: paketet elevenlabs. Byggaren importeras från elevenlabs.agent_tools.
  • JavaScript: paketet @elevenlabs/elevenlabs-js. Byggaren exporteras från paketets rot.

Bygg ett webhook-verktyg

Tool.webhook(name, description) startar ett webhook-verktyg. Namnet och beskrivningen är vad LLM:en ser när den avgör om verktyget ska anropas. Det här exemplet slår upp en order utifrån numret som den som ringer uppger, skickar en API-nyckel från arbetsytans hemligheter och lagrar orderns status i en dynamisk variabel:

from elevenlabs import ElevenLabs
from elevenlabs.agent_tools import Header, Schema, Tool
elevenlabs = ElevenLabs()
get_order = (
Tool.webhook("get_order", "Look up an order by the number the caller gives")
.get("https://api.example.com/orders/{order_id}")
.path_param("order_id", Schema.string().describe("The order number, e.g. A-1042"))
.query_param("include", Schema.string().constant("items"))
.header("Authorization", Header.secret("sec_orders_api"))
.assign("order_status", "order.status")
.options(response_timeout_secs=10)
)
tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())

Begärandemetoderna anger HTTP-metod och URL. {name}-platshållare i URL:en fylls i från sökvägsparametrar:

PythonJavaScriptAnger
get(url), post(url), put(url), patch(url), delete(url)sammaMetoden och URL:en. POST, PUT och PATCH behöver en brödtext; GET kan inte ha någon.
path_param(name, schema)pathParam(name, schema)En sökvägsparameter för {name}-platshållaren i URL:en.
query_param(name, schema)queryParam(name, schema)En frågeparameter.
body(schema)body(schema)Begärandetexten. Måste vara ett objektschema.
response(schema)response(schema)Schemat för svarstexten. Måste vara ett objektschema.
header(name, value)header(name, value)Ett begärandehuvud. Se Headers och autentisering.
auth(connection)auth(connection)Den autentiseringsanslutning som ska användas.
assign(variable, path)assign(variable, path)Lagrar värdet vid path i svaret (punktnotation) i en dynamisk variabel.

Om du anger en parameter eller header vars namn redan finns ersätts den och behåller sin position. remove_path_param(), remove_query_param(), remove_header() och remove_assignment() (removePathParam() och så vidare i JavaScript) tar bort en. Parameternamn måste vara unika mellan sökväg, fråga och brödtext.

En brödtext är ett objektschema som byggs egenskap för egenskap:

refund = (
Tool.webhook("issue_refund", "Refund an order the caller asked to return")
.post("https://api.example.com/refunds")
.body(
Schema.object()
.property("order_id", Schema.string().from_variable("order_id"))
.property(
"reason",
Schema.string().describe("Why the caller wants a refund").choices(["damaged", "late", "other"]),
)
.property("note", Schema.string().describe("Anything else the caller said").optional())
)
)

Parameterscheman

Schema bygger parameterscheman som webhook- och klientverktyg använder. Varje metod returnerar ett nytt schema och lämnar det den anropades på oförändrat, så du kan definiera ett schema en gång och använda det i flera verktyg.

KonstruktorBygger
Schema.string(), Schema.integer(), Schema.number(), Schema.bool()Ett bokstavligt värde
Schema.object()Ett objekt. Lägg till egenskaper med property().
Schema.array(items)En matris vars element matchar schemat items

Var ett värde kommer från

Varje bokstavligt värde behöver exakt en värdekälla, oavsett var det förekommer: i en parameter, i en brödtext, i ett svarsschema eller inuti ett objekt eller en matris. Ett objekt eller en matris kan också ha en, som då tillhandahåller hela värdet.

PythonJavaScriptVärdet
describe(text)describe(text)Tillhandahålls av LLM:en, vägledd av text.
from_variable(name)fromVariable(name)Läses från en dynamisk variabel när verktyget körs.
constant(value)constant(value)Är alltid value.
system_provided()systemProvided()Fylls i av systemet när verktyget körs. Endast bokstavliga värden.
omit()omit()Utelämnas från begäran. Endast för en valfri egenskap.

På ett objekt eller en matris dokumenterar describe() behållaren för LLM:en, och varje egenskap eller element har fortfarande sin egen källa.

Andra schemametoder

PythonJavaScriptGör
optional()optional()Gör en egenskap valfri. Egenskaper är obligatoriska om de inte markeras som valfria.
choices(values)choices(values)Begränsar en sträng till en fast uppsättning värden som LLM:en väljer från.
allowed_from(variable)allowedFrom(variable)Avvisar ett LLM-värde som inte finns i listan i en dynamisk variabel. Kräver describe().
property(name, schema) / without(name)property(name, schema) / without(name)Lägger till, ersätter eller tar bort en objektegenskap. En ersatt egenskap behåller sin position.
require_any_of(names) / require_all_of(names)requireAnyOf(names) / requireAllOf(names)Kräver minst en eller alla i en grupp av valfria egenskaper.

Headers och autentisering

Ett header-värde kommer från en av fyra platser. Använd en hemlighet eller en miljövariabel för allt känsligt, så att värdet aldrig visas i verktygskonfigurationen:

KonstruktorHeader-värdet är
Header.value(text)Fast text.
Header.secret(id)En hemlighet från arbetsytans hemlighetslager.
Header.variable(name)En dynamisk variabel som läses när verktyget körs.
Header.env_var(label) / Header.envVar(label)En miljövariabel för arbetsytan, som löses för den aktuella miljön.

AuthConnection.id(id) använder en autentiseringsanslutning från arbetsytan via ID. AuthConnection.env_var(label) / AuthConnection.envVar(label) väljer den från en miljövariabel, så att samma verktygskonfiguration kan använda en annan anslutning i varje miljö.

from elevenlabs.agent_tools import AuthConnection, Header
update_profile = (
Tool.webhook("update_profile", "Update the caller's email address")
.put("https://api.example.com/profiles/{profile_id}")
.path_param("profile_id", Schema.string().from_variable("profile_id"))
.body(Schema.object().property("email", Schema.string().describe("The new email address")))
.header("X-Api-Key", Header.env_var("profiles_api_key"))
.auth(AuthConnection.env_var("profiles_oauth"))
)

Bygg ett klientverktyg

Tool.client(name, description) startar ett klientverktyg, som körs i din applikation i stället för på en server. Lägg till dess parametrar med param(name, schema). Ange expects_response / expectsResponse när agenten ska vänta på resultatet från din applikation:

show_map = (
Tool.client("show_store_map", "Show the caller a map of the nearest store")
.param("store_id", Schema.string().describe("The store to show"))
.options(expects_response=False)
)

Bygg ett systemverktyg

Systemverktyg är inbyggda i plattformen. Varje verktyg har en egen konstruktor på SystemTool, som tar verktygets inställningar:

PythonJavaScript
SystemTool.end_call()SystemTool.endCall()
SystemTool.skip_turn(wait_timeout_secs=...)SystemTool.skipTurn({ waitTimeoutSecs })
SystemTool.language_detection(...)SystemTool.languageDetection(options?)
SystemTool.play_keypad_touch_tone(...)SystemTool.playKeypadTouchTone(options?)
SystemTool.voicemail_detection(voicemail_message=...)SystemTool.voicemailDetection({ voicemailMessage })
SystemTool.knowledge_base(enabled_strategies=...)SystemTool.knowledgeBase({ enabledStrategies })
SystemTool.transfer_to_number(...)SystemTool.transferToNumber(options?)
SystemTool.transfer_to_agent()SystemTool.transferToAgent()

De två överföringsverktygen hämtar sina destinationer från transfer(condition, destination, options). Villkoret anger för LLM:en när överföringen ska göras, och destinationen använder samma Destination som workflows som kod. En överföring till en SIP-URI kräver en SIP REFER-överföring:

from elevenlabs.agent_tools import SystemTool
from elevenlabs.agent_workflows import Destination
transfer = (
SystemTool.transfer_to_number()
.transfer("Caller asks for billing", Destination.phone("+15551234567"))
.transfer("Caller is a reseller partner", Destination.sip("sip:partners@pbx.example.com"), transfer_type="sip_refer")
)
to_sales = SystemTool.transfer_to_agent().transfer(
"Caller wants to buy something", Destination.agent("agent_sales"), transfer_message="Connecting you to sales"
)

Verktygsalternativ

Inställningar som delas av alla typer av verktyg anges i options(), som nyckelordsargument i Python och ett objekt i JavaScript. Namnen matchar verktygskonfigurationens fält i API:et:

Gäller förPythonJavaScript
Alla verktygname, description, response_timeout_secs, interruption_mode, pre_tool_speech, tool_call_sound, tool_error_handling_mode, …name, description, responseTimeoutSecs, interruptionMode, preToolSpeech, toolCallSound, toolErrorHandlingMode, …
Webhook-verktygexecution_mode, content_type, response_filter, follow_redirects, follow_redirects_allowed_domains, dynamic_variable_placeholdersexecutionMode, contentType, responseFilter, followRedirects, followRedirectsAllowedDomains, dynamicVariablePlaceholders
Klientverktygexecution_mode, expects_response, dynamic_variable_placeholdersexecutionMode, expectsResponse, dynamicVariablePlaceholders

Ett webhook-verktygs svarstimeout är 5 till 300 sekunder. Ett klientverktygs är 1 till 120 sekunder, eller -1 för att vänta så länge som krävs, vilket kräver expects_response / expectsResponse. follow_redirects / followRedirects kräver en lista med tillåtna domäner.

Koppla verktyg till en agent

Webhook- och klientverktyg skapas separat med tools.create() och kopplas till agenter via ID, så att ett verktyg kan delas av flera agenter. Systemverktyg är en del av agentens konfiguration: build_config() / buildConfig() returnerar posten för agentens inbyggda verktyg.

from elevenlabs import AgentConfig, BuiltInToolsOutput, ConversationalConfig, PromptAgentApiModelOutput
order_tool = elevenlabs.conversational_ai.tools.create(request=get_order.build())
agent = elevenlabs.conversational_ai.agents.create(
name="Support line",
conversation_config=ConversationalConfig(
agent=AgentConfig(
prompt=PromptAgentApiModelOutput(
prompt="You are a support agent for Acme.",
tool_ids=[order_tool.id],
built_in_tools=BuiltInToolsOutput(
end_call=SystemTool.end_call().build_config(),
transfer_to_number=transfer.build_config(),
),
)
)
),
)

Agentens fält prompt.tools, som innehåller verktygskonfigurationer inline, är föråldrat. Det kan inte kombineras med tool_ids, och när en begäran innehåller det ersätts agentens inbyggda verktyg av systemverktygen som det innehåller. Skapa i stället verktyg med tools.create() och koppla dem via ID.

Redigera ett befintligt verktyg

Tool.from_response() / Tool.fromResponse() läser in ett verktyg som returneras av tools.get(). Fält som byggaren inte modellerar och standardvärdena som API:et fyller i behålls, så när du skickar tillbaka det ändras endast det du har ändrat. as_webhook(), as_client() och as_system() (asWebhook() och så vidare i JavaScript) ger dig det typade verktyget att redigera, eller None / undefined om det är en annan typ.

För att ändra en egenskap i brödtexten läser du brödtextschemat, anger egenskapen igen och anger brödtexten:

from elevenlabs.agent_tools import ObjectSchema
loaded = Tool.from_response(elevenlabs.conversational_ai.tools.get("tool_id")).as_webhook()
if loaded is None:
raise ValueError("Not a webhook tool")
body = loaded.body_schema
assert isinstance(body, ObjectSchema)
loaded.body(body.property("reason", Schema.string().describe("Why the caller wants a refund")))
loaded.query_param("locale", Schema.string().describe("The caller's language").optional())
elevenlabs.conversational_ai.tools.update("tool_id", request=loaded.build())

Lagra verktyg i versionshantering

to_json_string() / toJSONString() skriver verktyget i API:ets trådformat: snake_case-nycklar, sorterade på varje nivå, med indrag på två blanksteg. Det har samma form som CLI lagrar i sin katalog tool_configs/, och båda SDK:erna skriver byte-identiska filer för samma verktyg, så skillnaderna hålls små. Tool.from_json() / Tool.fromJSON() läser in det igen.

from pathlib import Path
from elevenlabs.agent_tools import Tool
Path("tool_configs/get_order.json").write_text(get_order.to_json_string())
stored = Tool.from_json(Path("tool_configs/get_order.json").read_text())
elevenlabs.conversational_ai.tools.update("tool_id", request=stored.build())

En vanlig konfiguration är densamma som för workflows: skapa filerna med elevenlabs tools pull, redigera dem direkt eller med byggaren, kör Tool.from_json(file).build() / Tool.fromJSON(file).build() i CI för varje pull request och skicka dem med tools.update() eller elevenlabs tools push vid sammanslagning.

Validering

Kedjade anrop misslyckas aldrig på egen hand. build(), build_config() / buildConfig(), to_json() / toJSON() och to_json_string() / toJSONString() kontrollerar hela verktyget och reser eller kastar ett enda ToolValidationError vars issues listar varje problem, vart och ett med en code, ett message och path till den berörda delen, till exempel body.reason.

from elevenlabs.agent_tools import ToolValidationError
try:
request = refund.build()
except ToolValidationError as err:
for issue in err.issues:
print(issue.code, issue.path, issue.message)

Fel omfattar:

  • En URL-platshållare utan sökvägsparameter, eller en sökvägsparameter utan platshållare. Mallar för miljövariabler som {{system__env_api_host}} är inte platshållare.
  • Ett bokstavligt värde utan värdekälla eller med fler än en.
  • En brödtext på en GET, eller ingen brödtext på en POST, PUT eller PATCH.
  • Samma parameternamn i fler än en av sökväg, fråga och brödtext.
  • omit() på en obligatorisk egenskap, choices() på ett schema som inte är en sträng eller en konstant som inte matchar schemats typ.
  • Ett överföringsverktyg utan destinationer, en destination av fel typ eller en SIP-URI-destination utan SIP REFER-överföring.
  • Ett alternativ som inte gäller för verktygstypen eller en timeout utanför dess intervall.

Verktygstyper som är nyare än din SDK

Ett verktyg som läses in från API:et eller från en fil kan vara av en typ som byggaren inte kan redigera, till exempel ett MCP-verktyg. Det läses in med typen "other" och går oförändrat tur och retur via from_json() / fromJSON() och to_json_string() / toJSONString(), och build() rapporterar det som en varning via on_warning / onWarning.