Workflows como código
Visão geral
Um workflow é armazenado como um grafo de nós e arestas. Escrever esse grafo manualmente significa que você precisa manter IDs de arestas, listas edge_order e objetos de condição consistentes por conta própria. O construtor Workflow nos SDKs de Python e JavaScript permite descrever o mesmo grafo com chamadas de método encadeadas. Em seguida, ele gera o valor de workflow que agents.create() e agents.update() já aceitam.
Use-o para:
- Criar um workflow em código e revisá-lo como qualquer outra alteração de código.
- Carregar o workflow de um agente, alterar um nó e enviá-lo de volta sem afetar o restante do grafo.
- Armazenar workflows como JSON no controle de versão e validá-los em CI.
O construtor é executado inteiramente no SDK. Ele não chama novos endpoints de API, e tudo o que ele cria pode ser aberto e editado no editor visual do dashboard.
Requisitos
- Python: o pacote
elevenlabs. O construtor é importado deelevenlabs.agent_workflows. - JavaScript: o pacote
@elevenlabs/elevenlabs-js. O construtor é exportado da raiz do pacote.
Crie um workflow
O objeto Workflow representa o nó inicial. Cada verbo adiciona um nó e o retorna, para que você possa encadear a próxima etapa a partir dele:
Os métodos de roteamento determinam qual aresta leva ao próximo nó:
Verbos chamados diretamente no workflow criam ramificações a partir do nó inicial com uma aresta incondicional. Este exemplo direciona as pessoas que ligam para uma consulta de pedido, tenta novamente a identificação se a consulta falhar e transfere pessoas VIP ou frustradas:
build() valida todo o grafo e retorna o modelo de solicitação. Ele também:
- Atribui ao nó inicial o ID
start_node, exigido pela API. - Gera IDs de aresta no formato
source__target. - Preenche o
edge_orderde cada nó na ordem em que você adicionou as arestas. - Posiciona qualquer nó sem posição para que o grafo seja organizado da esquerda para a direita no editor visual.
Escreva um workflow como uma única cadeia
up() retorna o nó do qual o atual foi encadeado, para que você possa descrever um workflow inteiro em uma única expressão, em vez de manter cada nó em uma variável. Dentro de uma única cadeia, use go_to() / goTo() com um ID de nó, pois não há variável para passar:
Para um identificador de nó de wf.node(id), up() retorna o nó de onde vem a primeira aresta que entra nele. Para o nó inicial, retorna o próprio nó inicial.
Opções de nó
As configurações opcionais são passadas como argumentos de palavra-chave em Python e em um objeto de opções ao final em JavaScript. Os nomes correspondem aos campos do nó na API:
Todo verbo também aceita position se você quiser posicionar o nó manualmente. Workflow(prevent_subagent_loops=True) em Python, ou new Workflow({ preventSubagentLoops: true }) em JavaScript, impede que a conversa entre novamente em um subagente que já visitou.
Destinos de transferência
Condições
when() aceita uma string simples, uma Condition ou um Expr:
- Uma string é uma condição de LLM: a LLM decide se ela é atendida.
Condition.llm(text, label=...)é igual, com um rótulo exibido na aresta no editor visual. UseCondition.expr(expr, label=...)para rotular uma expressão.- Um
Expré avaliado em relação a variáveis dinâmicas, sem chamar a LLM.
Crie expressões com Expr.variable(name) e Expr.literal(value). Compare-as com eq, neq, gt, gte, lt e lte, e faça operações aritméticas com add, sub, mul e div. Combine-as com all_of / allOf, any_of / anyOf e if_else / ifElse. Valores simples são encapsulados em Expr.literal() automaticamente. Expr.llm(description) pede à LLM para extrair um valor da conversa; passe type e enum para obter uma string, um número ou um de um conjunto fixo em vez de um booleano.
Loops e arestas de retorno
A API permite uma aresta entre quaisquer dois nós, em qualquer direção. Para permitir que a conversa retorne pelo caminho de onde veio, dê à aresta uma condição de retorno com back:
go_to() / goTo() lida com o caso comum para você. Quando o nó de destino já tem uma aresta que leva até aqui, a nova aresta se torna a condição de retorno dessa aresta. No primeiro exemplo, failed.go_to(identify) é enviado como a condição de retorno da aresta identify → lookup_order. Qualquer outra segunda aresta entre os mesmos dois nós, e qualquer aresta de um nó para ele mesmo, falha na validação.
Edite um agente existente
Workflow.from_agent() / Workflow.fromAgent() carrega o workflow de um agente retornado por agents.get(). IDs de nós, IDs de arestas, posições no editor e ordem das arestas são mantidos, portanto, enviá-lo de volta altera apenas o que você modificou.
insert_between() / insertBetween() passa à sua função uma ramificação que carrega a condição da aresta substituída. A função retorna o último nó que adicionou, que então é conectado ao destino original. O método retorna esse nó, ou None / undefined se não houver aresta entre os dois nós.
Armazene workflows no controle de versão
to_json_string() / toJSONString() grava o workflow no formato de transmissão da API: chaves em snake_case, ordenadas em todos os níveis, com indentação de 2 espaços. É a mesma estrutura usada pela API REST e pela CLI, e ambos os SDKs gravam arquivos idênticos byte a byte para o mesmo workflow, mantendo os diffs pequenos. Workflow.from_json() / Workflow.fromJSON() o lê de volta e também aceita uma configuração completa de agente com uma chave workflow, como um arquivo no diretório agent_configs/ da CLI.
Uma configuração típica:
Crie o arquivo inicial
Carregue o agente com from_agent() / fromAgent() e grave-o, ou obtenha-o com elevenlabs agents pull.
Edite
Altere o JSON diretamente ou carregue-o com from_json() / fromJSON() e edite-o com o
builder em um script.
Visualize um workflow
A CLI desenha um arquivo de workflow como um fluxograma, para que você possa verificar o que seu código criou sem abrir o dashboard. Ela aceita um arquivo de workflow simples gravado por to_json_string() / toJSONString() ou uma configuração de agente com uma chave workflow:
Por padrão, ela desenha caixas e setas no terminal, com cada condição de aresta numerada na própria aresta e detalhada em uma legenda abaixo. Use --format mermaid para imprimir o código-fonte Mermaid ou --format mermaid-md para envolvê-lo em um bloco de código delimitado que o GitHub renderiza, por exemplo, em um comentário de pull request:
O comando lê apenas arquivos locais, portanto não precisa de chave de API e pode ser executado em CI.
Validação
Chamadas encadeadas nunca falham por conta própria. build(), to_json() / toJSON() e to_json_string() / toJSONString() verificam todo o grafo e geram ou lançam um único WorkflowValidationError, cuja lista issues contém todos os problemas, cada um com um code, uma message e o node_id / nodeId ao qual se refere.
Os erros incluem:
- Duas arestas entre o mesmo par de nós ou uma aresta de um nó para ele mesmo.
- Uma aresta que entra no nó inicial ou sai de um nó final.
- Uma aresta de um nó de ferramenta que não é uma aresta de sucesso ou falha, ou uma aresta de sucesso ou falha de qualquer outro tipo de nó.
- Dois nós com o mesmo ID ou uma aresta para um nó que não existe.
Nós que não podem ser alcançados a partir do nó inicial são informados como avisos, por meio de on_warning / onWarning, e não impedem a criação.
Tipos de nó mais recentes que seu SDK
Um workflow carregado da API ou de um arquivo pode conter tipos de nó que a versão do seu SDK ainda não conhece. Eles passam inalterados por from_json() / fromJSON() e to_json_string() / toJSONString(), e build() informa cada um como um aviso. O modelo de solicitação tipado não pode incluí-los, então atualize o SDK ou envie o formato de transmissão diretamente: