탐색으로 건너뛰기

코드로 워크플로 구축

Python 및 JavaScript SDK로 에이전트 워크플로 구축, 편집 및 버전 관리

개요

워크플로는 노드와 엣지의 그래프로 저장됩니다. 이 그래프를 직접 작성하려면 엣지 ID, edge_order 목록 및 조건 객체의 일관성을 직접 유지해야 합니다. Python 및 JavaScript SDK의 Workflow 빌더를 사용하면 메서드 호출을 체이닝하여 동일한 그래프를 설명할 수 있습니다. 그러면 agents.create()와 agents.update()가 이미 허용하는 workflow 값을 생성합니다.

다음과 같은 작업에 사용하세요.

  • 코드로 워크플로를 구축하고 다른 코드 변경 사항처럼 검토합니다.
  • 에이전트의 워크플로를 불러와 하나의 노드를 변경하고, 그래프의 나머지 부분에 영향을 주지 않고 다시 푸시합니다.
  • 워크플로를 JSON으로 버전 관리에 저장하고 CI에서 검증합니다.

빌더는 전적으로 SDK에서 실행됩니다. 새 API 엔드포인트를 호출하지 않으며, 빌더로 생성한 모든 항목은 대시보드의 시각적 편집기에서 열고 편집할 수 있습니다.

요구 사항

  • Python: elevenlabs 패키지. 빌더는 elevenlabs.agent_workflows에서 가져옵니다.
  • JavaScript: @elevenlabs/elevenlabs-js 패키지. 빌더는 패키지 루트에서 내보냅니다.

워크플로 빌드

Workflow 객체는 시작 노드를 나타냅니다. 각 동사는 노드를 추가하고 해당 노드를 반환하므로, 이를 통해 다음 단계를 연결할 수 있습니다.

PythonJavaScript추가 항목
converse(id, prompt, **options)converse(id, prompt, options?)서브 에이전트 노드입니다. 에이전트는 지침에 prompt를 추가하여 대화를 진행합니다.
tool(id, tool_ids, **options)tool(id, toolIds, options?)지정된 도구를 실행하는 디스패치 도구 노드입니다. 코드로 도구 정의하기를 참고하세요.
transfer(id, destination, **options)transfer(id, destination, options?)전화번호, SIP URI 또는 다른 에이전트로 연결을 전환합니다.
end(id="end")end(options?)종료 노드입니다. ID 없이 호출한 모든 end()는 하나의 "end" 노드를 공유합니다.

라우팅 메서드는 다음 노드로 이어지는 엣지를 결정합니다.

PythonJavaScript생성 항목
when(condition)when(condition)조건부 엣지입니다. 문자열은 LLM 조건이고, Expr는 표현식입니다.
on_success() / on_failure()onSuccess() / onFailure()도구 호출 성공 또는 실패 시 선택되는 도구 노드의 엣지입니다.
on_result(success=..., failure=...)onResult({ success, failure })두 도구 결과 엣지를 한 번에 설정합니다.
go_to(node)goTo(node)병합과 루프를 위해 이미 존재하는 노드로 연결하는 엣지입니다.
up()up()엣지를 만들지 않습니다. 현재 노드가 연결된 원래 노드를 반환하여 그 노드에서 계속 연결할 수 있게 합니다. 하나의 체인으로 워크플로 작성하기를 참고하세요.

워크플로에서 직접 호출하는 동사는 무조건 엣지로 시작 노드에서 분기합니다. 다음 예시는 발신자를 주문 조회로 라우팅하고, 조회에 실패하면 식별을 다시 시도하며, VIP 또는 불만이 있는 발신자는 연결을 전환합니다.

from elevenlabs import ElevenLabs
from elevenlabs.agent_workflows import Destination, Expr, Workflow
elevenlabs = ElevenLabs()
wf = Workflow()
triage = wf.converse("triage", "Greet the caller and find out why they're calling")
identify = triage.when("Caller wants to check an order").converse(
"identify", "Ask for the order number and the email on the account"
)
lookup = identify.when("Caller gave an order number").tool("lookup_order", ["tool_get_order"])
lookup.on_result(
success=lambda ok: ok.converse("resolve", "Explain the order status")
.when("Caller is satisfied")
.end(),
failure=lambda failed: failed.go_to(identify),
)
triage.when(Expr.variable("tier").eq("gold")).transfer("vip", Destination.agent("agent_vip"))
triage.when("Caller wants a human").transfer("human", Destination.phone("+15551234567"))
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

build()는 전체 그래프를 검증하고 요청 모델을 반환합니다. 또한 다음을 수행합니다.

  • API에서 요구하는 시작 노드 ID start_node를 지정합니다.
  • source__target 형식으로 엣지 ID를 생성합니다.
  • 엣지를 추가한 순서대로 각 노드의 edge_order를 채웁니다.
  • 위치가 없는 모든 노드를 배치하여 비주얼 에디터에서 그래프가 왼쪽에서 오른쪽으로 표시되게 합니다.

하나의 체인으로 워크플로 작성하기

up()은 현재 노드가 연결된 원래 노드를 반환하므로, 각 노드를 변수에 저장하는 대신 하나의 표현식으로 전체 워크플로를 설명할 수 있습니다. 단일 체인 내에서는 전달할 변수가 없으므로 노드 ID와 함께 go_to() / goTo()를 사용하세요.

wf = Workflow()
(
wf.converse("triage", "Find out why the customer is calling")
.when("Caller gave an order number")
.tool("lookup_order", ["tool_get_order"])
.on_result(
success=lambda ok: ok.converse("resolve", "Explain the order status").when("Customer is satisfied").end(),
failure=lambda failed: failed.go_to("triage"),
)
.up()
.when(Expr.variable("tier").eq("gold"))
.transfer("vip", Destination.agent("agent_vip_desk"))
)
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

wf.node(id)로 가져온 노드 핸들의 경우 up()은 해당 노드로 들어오는 첫 번째 엣지의 출발 노드를 반환합니다. 시작 노드에서는 시작 노드를 반환합니다.

노드 옵션

선택 설정은 Python에서는 키워드 인수로, JavaScript에서는 마지막 옵션 객체로 전달합니다. 이름은 API의 노드 필드와 일치합니다.

노드PythonJavaScript
converselabel, tool_ids, knowledge_base, conversation_config, entry_behaviorlabel, toolIds, knowledgeBase, conversationConfig, entryBehavior
toolschema_overridesschemaOverrides
transfertransfer_type, custom_sip_headers, post_dial_digits, delay_ms, transfer_message, …transferType, customSipHeaders, postDialDigits, delayMs, transferMessage, …
endidid

노드를 직접 배치하려면 모든 동사에 position을 전달할 수도 있습니다. Python의 Workflow(prevent_subagent_loops=True) 또는 JavaScript의 new Workflow({ preventSubagentLoops: true })는 대화가 이미 방문한 서브 에이전트에 다시 진입하지 못하도록 합니다.

triage = wf.converse(
"triage",
"Greet the caller and find out why they're calling",
label="Triage",
tool_ids=["tool_crm_search"],
entry_behavior="generate_immediately",
)
triage.when("Caller is a VIP").transfer(
"vip_desk",
Destination.agent("agent_vip_concierge"),
transfer_message="Connecting you to our VIP team",
delay_ms=500,
)
identify.when("Caller refuses to share details").end(id="abandoned")

연결 전환 대상

PythonJavaScript연결 전환 대상
Destination.phone(number)Destination.phone(number)전화번호
Destination.phone_variable(name)Destination.phoneVariable(name)동적 변수에 저장된 전화번호
Destination.sip(uri)Destination.sip(uri)SIP URI
Destination.sip_variable(name)Destination.sipVariable(name)동적 변수에 저장된 SIP URI
Destination.agent(agent_id)Destination.agent(agentId)다른 에이전트

조건

when()은 일반 문자열, Condition 또는 Expr를 받습니다.

  • 문자열은 LLM 조건입니다. 조건이 충족되는지 LLM이 판단합니다.
  • Condition.llm(text, label=...)도 동일하며, 비주얼 에디터에서 엣지에 표시할 라벨을 지정할 수 있습니다. 표현식에 라벨을 지정하려면 Condition.expr(expr, label=...)를 사용하세요.
  • Expr는 LLM을 호출하지 않고 동적 변수를 기준으로 평가됩니다.

Expr.variable(name) 및 Expr.literal(value)로 표현식을 빌드합니다. eq, neq, gt, gte, lt, lte로 비교하고, add, sub, mul, div로 산술 연산을 수행합니다. all_of / allOf, any_of / anyOf, if_else / ifElse로 결합할 수 있습니다. 일반 값은 자동으로 Expr.literal()로 감쌉니다. Expr.llm(description)은 LLM에 대화에서 값을 추출하도록 요청합니다. 불리언 대신 문자열, 숫자 또는 고정된 값 집합 중 하나를 얻으려면 type과 enum을 전달하세요.

from elevenlabs.agent_workflows import Condition, Expr
is_vip = Expr.any_of(
Expr.variable("tier").eq("gold"),
Expr.all_of(Expr.variable("orders").gte(10), Expr.variable("churn_risk").eq(True)),
)
triage.when(Condition.expr(is_vip, label="VIP")).transfer("vip_desk", Destination.agent("agent_vip"))
big_refund = Expr.variable("unit_price").mul(Expr.variable("quantity")).gt(500)
resolve.when(big_refund).transfer("finance", Destination.phone("+15551234567"))
score = Expr.llm("How satisfied the caller sounds, from 1 to 5", type="integer")
resolve.when(score.lte(2)).converse("recovery", "Apologize and offer a discount code")

루프와 역방향 엣지

API는 방향에 관계없이 두 노드 사이에 하나의 엣지를 허용합니다. 대화가 왔던 경로로 돌아갈 수 있게 하려면 back으로 엣지에 역방향 조건을 지정하세요.

faq = triage.when("Caller has a general question", back="Question answered").converse(
"faq", "Answer using the FAQ knowledge base"
)

go_to() / goTo()는 일반적인 경우를 자동으로 처리합니다. 대상 노드에 이미 이 위치로 이어지는 엣지가 있으면 새 엣지가 해당 엣지의 역방향 조건이 됩니다. 첫 번째 예시에서 failed.go_to(identify)는 identify → lookup_order 엣지의 역방향 조건으로 전송됩니다. 같은 두 노드 사이의 다른 두 번째 엣지나 노드 자신으로 연결되는 모든 엣지는 검증에 실패합니다.

기존 에이전트 편집

Workflow.from_agent() / Workflow.fromAgent()는 agents.get()이 반환한 에이전트의 워크플로를 불러옵니다. 노드 ID, 엣지 ID, 에디터 위치 및 엣지 순서는 유지되므로, 다시 푸시해도 변경한 내용만 바뀝니다.

PythonJavaScript기능
wf.node(id)wf.node(id)기존 노드를 편집하거나 해당 노드에서 연결할 수 있는 핸들을 반환합니다.
node.update(**fields)node.update(fields)노드의 프롬프트, 도구, 대상 또는 옵션을 변경합니다.
wf.insert_between(source, target, fn)wf.insertBetween(source, target, fn)기존 엣지의 조건을 유지하면서 새 노드를 그 사이에 삽입합니다.
wf.remove(id)wf.remove(id)노드와 해당 노드로 들어오거나 나가는 모든 엣지를 제거합니다.

insert_between() / insertBetween()는 대체되는 엣지의 조건을 포함한 브랜치를 함수에 전달합니다. 함수는 마지막으로 추가한 노드를 반환하고, 그 노드는 원래 대상에 연결됩니다. 이 메서드는 해당 노드를 반환하며, 두 노드 사이에 엣지가 없으면 None / undefined를 반환합니다.

agent = elevenlabs.conversational_ai.agents.get("agent_id")
wf = Workflow.from_agent(agent)
wf.node("resolve").update(prompt="Explain the status, then offer a discount code")
verify = wf.insert_between(
"identify",
"lookup_order",
lambda start: start.converse("verify", "Verify the caller's identity with a one-time code"),
)
if verify is not None:
verify.when("Caller can't verify").end(id="unverified")
wf.remove("vip")
elevenlabs.conversational_ai.agents.update("agent_id", workflow=wf.build())

버전 관리에 워크플로 저장

to_json_string() / toJSONString()은 API의 와이어 형식으로 워크플로를 작성합니다. 모든 수준에서 정렬된 snake_case 키와 2칸 들여쓰기를 사용합니다. REST API와 CLI가 사용하는 것과 동일한 구조이며, 두 SDK는 같은 워크플로에 대해 바이트 단위까지 동일한 파일을 작성하므로 diff가 작게 유지됩니다. Workflow.from_json() / Workflow.fromJSON()은 이를 다시 읽어 들이며, CLI의 agent_configs/ 디렉터리에 있는 파일처럼 workflow 키를 포함한 전체 에이전트 구성도 허용합니다.

from pathlib import Path
from elevenlabs.agent_workflows import Workflow
Path("workflows/support.json").write_text(wf.to_json_string())
stored = Workflow.from_json(Path("workflows/support.json").read_text())
from_cli = Workflow.from_json(Path("agent_configs/support.json").read_text())

일반적인 설정은 다음과 같습니다.

1

파일 초기화

from_agent() / fromAgent()로 에이전트를 불러와 파일로 작성하거나, elevenlabs agents pull로 가져옵니다.

2

편집

JSON을 직접 변경하거나, from_json() / fromJSON()으로 불러온 후 스크립트에서 빌더로 편집합니다.

3

CI에서 검증

모든 풀 리퀘스트에서 Workflow.from_json(file).build() / Workflow.fromJSON(file).build()를 실행하고, 검토자가 그래프를 볼 수 있도록 elevenlabs agents workflow diagram <file> --format mermaid-md를 댓글로 게시합니다.

4

병합 시 배포

빌드된 워크플로를 agents.update()로 푸시합니다.

워크플로 시각화

CLI는 워크플로 파일을 플로차트로 그리므로, 대시보드를 열지 않고도 코드가 빌드한 결과를 확인할 수 있습니다. to_json_string() / toJSONString()으로 작성한 워크플로 파일만 사용하거나, workflow 키가 있는 에이전트 구성을 사용할 수 있습니다.

elevenlabs agents workflow diagram workflows/support.json

기본적으로 터미널에 상자와 화살표를 그리고, 각 엣지 조건에는 번호를 표시하며 아래 범례에 내용을 작성합니다. 대신 Mermaid 소스를 출력하려면 --format mermaid를 사용하세요. 풀 리퀘스트 댓글처럼 GitHub에서 렌더링되는 fenced 코드 블록으로 감싸려면 --format mermaid-md를 사용합니다.

elevenlabs agents workflow diagram workflows/support.json --format mermaid-md

이 명령어는 로컬 파일만 읽으므로 API 키가 필요 없으며 CI에서 실행할 수 있습니다.

검증

연결된 호출은 자체적으로 실패하지 않습니다. build(), to_json() / toJSON(), to_json_string() / toJSONString()은 전체 그래프를 검사하고, 모든 문제를 나열하는 단일 WorkflowValidationError를 발생시키거나 throw합니다. 각 문제에는 code, message, 그리고 관련된 node_id / nodeId가 포함됩니다.

from elevenlabs.agent_workflows import WorkflowValidationError
try:
workflow = wf.build(on_warning=lambda issue: print("warning:", issue.message))
except WorkflowValidationError as err:
for issue in err.issues:
print(issue.code, issue.message)

오류에는 다음이 포함됩니다.

  • 동일한 노드 쌍 사이의 두 엣지 또는 노드 자신으로 연결되는 엣지
  • 시작 노드로 들어오는 엣지 또는 종료 노드에서 나가는 엣지
  • 성공 또는 실패 엣지가 아닌 도구 노드의 엣지, 또는 다른 종류의 노드에서 나가는 성공 또는 실패 엣지
  • 동일한 ID를 가진 두 노드 또는 존재하지 않는 노드로 연결되는 엣지

시작 노드에서 도달할 수 없는 노드는 on_warning / onWarning을 통해 경고로 보고되며 빌드를 중단하지 않습니다.

SDK보다 최신인 노드 유형

API 또는 파일에서 불러온 워크플로에는 현재 SDK 버전이 아직 알지 못하는 노드 유형이 포함될 수 있습니다. 이러한 노드 유형은 변경 없이 from_json() / fromJSON() 및 to_json_string() / toJSONString()을 거치며, build()는 각각을 경고로 보고합니다. 타입이 지정된 요청 모델은 이를 포함할 수 없으므로 SDK를 업그레이드하거나 와이어 형식을 직접 전송하세요.

elevenlabs.conversational_ai.agents.update(
"agent_id",
request_options={"additional_body_parameters": {"workflow": wf.to_json()}},
)