> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Procedimentos estruturados ## Visão geral Um procedimento estruturado é um [procedimento](/docs/pt/eleven-agents/customization/procedures) que executa uma sequência fixa de etapas. Um [procedimento de formato livre](/docs/pt/eleven-agents/customization/procedures/free-form-procedures) é uma orientação em linguagem natural que o agente interpreta e adapta à situação. Um procedimento estruturado é uma lista ordenada de etapas tipadas que o agente executa em ordem sempre que o procedimento se aplica. Use um procedimento estruturado quando etapas específicas precisarem ocorrer da mesma forma em todas as chamadas: verificar a identidade de quem ligou, escalar um ticket ou receber um pagamento. Você o cria como uma lista curta de etapas em linguagem simples. Como todo procedimento, um procedimento estruturado tem um gatilho que descreve quando ele se aplica. Quando uma conversa corresponde ao gatilho, o agente executa as etapas do procedimento em ordem e depois retorna ao restante da conversa. ![Editor de procedimento estruturado](/docs/_fern-img/bc996f67b2afad8f1de5abe8febcf8af3766b4f098627b0ae60e0456b3c2703b.webp) ## Quando usar um procedimento estruturado Use um procedimento estruturado quando etapas específicas precisarem ser executadas da mesma forma sempre, mas você ainda quiser criar rapidamente usando etapas simples. Procedimentos estruturados são mais fáceis de escrever do que um workflow, mas menos expressivos. Para saber como eles se comparam a procedimentos de formato livre, workflows e ao prompt do sistema, consulte [Quando usar procedimentos](/docs/pt/eleven-agents/customization/procedures#when-to-use-procedures). ## Anatomia de um procedimento estruturado Um procedimento estruturado tem três partes: um nome, um gatilho e uma lista ordenada de etapas. ### Nome Um rótulo curto que identifica o procedimento no painel. O nome nunca é enviado ao LLM, portanto não afeta o comportamento do agente. ### Gatilho Uma descrição em linguagem simples de quando o agente deve executar este procedimento, por exemplo, *Quando o usuário pedir o reembolso de um pedido*. O agente compara a intenção do usuário com o gatilho de cada procedimento e executa o correspondente, portanto os gatilhos devem ser concretos e distintos. O agente vê apenas o texto do gatilho, nunca o nome ou o ID do procedimento. Um gatilho funciona da mesma forma que em qualquer procedimento; consulte [Como escrever gatilhos](/docs/pt/eleven-agents/customization/procedures/free-form-procedures#writing-triggers). Deixe o gatilho vazio para tornar o procedimento um subprocesso que só é executado quando outro procedimento o chama. ### Etapas O corpo do procedimento é uma lista ordenada de etapas tipadas. Há vários tipos de etapa, que você combina para descrever a tarefa. | Etapa | O que faz | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Perguntar** | Pede informações ao usuário e aguarda. Continua perguntando até que o usuário responda. Esta é a única etapa que pausa para o usuário. | | **Informar** | Faz o agente transmitir algo com suas próprias palavras e depois segue para a próxima etapa. | | **Dizer** | Faz o agente falar uma mensagem exata, palavra por palavra, e depois segue para a próxima etapa. Uma etapa Dizer pode ter uma tradução configurada especificamente para cada idioma compatível com o agente. | | **Ferramenta** | Chama uma ferramenta específica. Você pode instruir o LLM em linguagem simples sobre como chamar a ferramenta ou definir explicitamente valores de parâmetros quando for necessário o máximo de determinismo. Também é possível definir etapas a executar caso a chamada da ferramenta falhe. | | **Se** | Avalia uma ou mais condições em ordem e executa as etapas da primeira correspondência. Um Senão opcional é executado quando não há correspondência. | | **Subprocesso** | Executa outro procedimento estruturado. Quando suas etapas são concluídas, o controle retorna à próxima etapa deste procedimento (chamador). | | **Ferramenta do sistema** | Executa uma ação integrada do sistema. No momento, apenas encerrar a chamada é compatível. | | **Tentar novamente** | Executa novamente o manipulador de falha de uma etapa Ferramenta, incluindo a chamada da ferramenta, até três vezes. Disponível apenas dentro do manipulador de falha de uma etapa Ferramenta. | ![Menu de tipos de etapa de procedimento estruturado ](/docs/_fern-img/14976a6b9979d21fd7c77541a49e7475f8aa0764af4940746d3390804e7c4598.webp) Nem todas as etapas podem aparecer em qualquer lugar. Dentro de uma ramificação Se, você pode usar qualquer etapa, exceto outro Se ou Tentar novamente. Dentro do manipulador de falha de uma etapa Ferramenta, você pode usar qualquer etapa, exceto Se ou outra Ferramenta. ## Referência de etapas da API O `content` de um procedimento estruturado é um documento codificado em JSON que contém uma matriz `steps`. Cada etapa é um objeto identificado por seu `type`. O gatilho é um campo separado de nível superior no procedimento, não faz parte de `content`. As cargas úteis da API e do SDK usam `type: "deterministic"` para o próprio procedimento. ### Perguntar Uma etapa Perguntar instrui o agente a solicitar informações e aguardar até que o usuário forneça uma resposta adequada. * Tipo da API: `ask` * `instruction`: string obrigatória e não vazia. ```json focus={1-4} { "type": "ask", "instruction": "Ask the user for their order ID." } ``` ### Informar Uma etapa Informar instrui o agente a gerar uma única mensagem com suas próprias palavras. Ela não aguarda uma resposta do usuário antes de continuar. * Tipo da API: `tell` * `instruction`: string obrigatória e não vazia. ```json focus={1-4} { "type": "tell", "instruction": "Explain that the refund normally takes five to ten business days." } ``` ### Dizer Uma etapa Dizer fala o texto fornecido exatamente como está escrito e depois continua. Forneça `message_translations` para dar ao agente uma mensagem exata para cada idioma adicional compatível, identificada pelo código do idioma. * Tipo da API: `say` * `message`: string obrigatória e não vazia. * `message_translations`: objeto opcional que mapeia um código de idioma para `{ "value": "..." }`. ```json focus={1-7} { "type": "say", "message": "Your refund has been submitted.", "message_translations": { "es": { "value": "Su reembolso ha sido enviado." } } } ``` ### Se, senão se e senão Uma etapa Se contém uma ou mais ramificações condicionais ordenadas. A primeira ramificação correspondente é executada. A matriz opcional `fallback` é a ramificação Senão. * Tipo da API: `branch` * `branches`: lista obrigatória e não vazia de ramificações condicionais. * `fallback`: lista opcional de etapas Senão. * Cada ramificação exige uma `condition` e uma lista `steps` não vazia. ```json focus={1-23} { "type": "branch", "branches": [ { "condition": { "type": "llm", "condition": "The user is on an annual plan." }, "steps": [ { "type": "say", "message": "Your annual plan is eligible for a prorated refund." } ] } ], "fallback": [ { "type": "tell", "instruction": "Explain that the account's plan could not be determined." } ] } ``` Isso funciona como if/else-if/else: 1. As condições são avaliadas em ordem. 2. A primeira ramificação correspondente é executada. 3. Se nenhuma condição corresponder, `fallback` é executado. 4. Depois que uma ramificação termina, o procedimento retorna à sequência principal. O exemplo acima usa uma condição de texto, que o modelo avalia em linguagem natural. As condições também podem ser expressões sobre variáveis dinâmicas: ```json focus={1-14} { "type": "expression", "expression": { "type": "eq_operator", "left": { "type": "dynamic_variable", "name": "plan_tier" }, "right": { "type": "string_literal", "value": "annual" } } } ``` Uma condição de expressão testa variáveis dinâmicas, que são preenchidas por resultados de ferramentas ou definidas quando a conversa começa. Ela não pode ler a resposta mais recente do usuário. Para criar uma ramificação com base no que o usuário disse, use uma condição de texto. Todas as ramificações em uma etapa Se devem usar o mesmo tipo de condição: `llm` ou `expression`. ### Ferramenta Uma etapa Ferramenta chama uma ferramenta específica. * Tipo da API: `tool_call` * `tool_id`: ID de ferramenta obrigatório e não vazio. A ferramenta deve estar vinculada ao agente. * `tool_name`: nome obrigatório da ferramenta, correspondente à ferramenta. * `instruction`: instrução opcional que descreve como chamar a ferramenta. * `schema_overrides`: valores fixos opcionais para os parâmetros da ferramenta. * `on_failure`: manipulador de falha opcional. ```json focus={1-6} { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "lookup_order", "instruction": "Look up the order using the order ID provided by the user." } ``` #### Valores fixos de parâmetros Use `schema_overrides` quando um parâmetro sempre precisar assumir um valor específico. O modelo não vê nem escolhe um parâmetro substituído. As chaves são caminhos de parâmetros no esquema da ferramenta; cada valor indica uma origem: | `source` | Campos | Comportamento | | ------------------ | ------------------- | ------------------------------------------------------------------------------ | | `constant` | `constant_value` | Sempre envia o valor informado. | | `dynamic_variable` | `dynamic_variable` | Envia o valor atual da variável dinâmica nomeada. | | `llm` | `prompt` (opcional) | Permite que o modelo escolha o valor, com uma substituição opcional de prompt. | | `omit` | | Omite o parâmetro da chamada. | ```json focus={1-9} { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "update_ticket", "schema_overrides": { "request_body.status": { "source": "constant", "constant_value": "pending" }, "request_body.ticket_id": { "source": "dynamic_variable", "dynamic_variable": "ticket_id" } } } ``` #### Tratamento de falhas Sem `on_failure`, uma chamada de ferramenta com falha encerra a conversa. Adicione `on_failure` para executar etapas de recuperação. * `fallback`: lista obrigatória e não vazia de etapas executadas quando a ferramenta falha. * `branches`: reservado para tratamento condicional de falhas. Deixe vazio. ```json focus={1-14} { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "lookup_order", "on_failure": { "branches": [], "fallback": [ { "type": "tell", "instruction": "Explain that the order could not be retrieved and offer to connect the user with support." } ] } } ``` Um manipulador de falha pode conter etapas Perguntar, Informar, Dizer, Subprocesso, Ferramenta do sistema e Tentar novamente. Ele não pode conter etapas Ferramenta ou Se. Depois que o manipulador é executado, o procedimento continua com a etapa após a etapa Ferramenta. ### Tentar novamente Uma etapa Tentar novamente executa novamente o manipulador de falha que a contém, incluindo a chamada da ferramenta. Cada tentativa chama a ferramenta novamente e, se ela falhar outra vez, executa todas as etapas do manipulador novamente. Quando as tentativas se esgotam, a conversa é encerrada. * Tipo da API: `retry` * `max_retries`: inteiro opcional de 1 a 3. O padrão é 1. * O valor conta as tentativas após a chamada original da ferramenta. * Tentar novamente é válido apenas dentro de `on_failure`. * Tentar novamente deve ser a etapa final em seu manipulador de falha, pois as etapas posteriores seriam inalcançáveis. ```json focus={1-4} { "type": "retry", "max_retries": 2 } ``` ### Subprocesso Uma etapa Subprocesso executa outro procedimento estruturado. Quando as etapas desse procedimento terminam, a execução retorna à etapa após a etapa Subprocesso. * Tipo da API: `sub_procedure` * `procedure_id`: ID de procedimento obrigatório e não vazio. * O destino deve existir no mesmo agente. * O destino deve ser um procedimento estruturado. * Um procedimento não pode chamar a si mesmo. ```json focus={1-4} { "type": "sub_procedure", "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3" } ``` ### Ferramenta do sistema Uma etapa Ferramenta do sistema executa uma ação integrada do sistema. * Tipo da API: `system_tool` * `system_tool_name`: nome obrigatório da ferramenta do sistema. * No momento, apenas `end_call` é compatível. Mais ferramentas do sistema poderão ser adicionadas futuramente. * Como `end_call` é terminal, ele deve ser a etapa final na sequência, ramificação ou manipulador de falha que o contém. ```json focus={1-4} { "type": "system_tool", "system_tool_name": "end_call" } ``` ## Regras de validação Publicar o agente ou salvar o rascunho do agente rejeita um procedimento estruturado que viole qualquer uma destas regras. O erro nomeia a etapa com problema por seu caminho. * Duas etapas Se não podem ser colocadas consecutivamente. * Etapas Se não podem ser aninhadas. * Uma etapa Se com condições de expressão não pode vir diretamente após uma etapa Perguntar. * Todas as condições em uma etapa Se devem ser do mesmo tipo: `llm` ou `expression`. * Tentar novamente pode aparecer apenas dentro de `on_failure` e deve ser a última etapa ali. * `end_call` deve ser a última etapa em qualquer lista em que apareça. * O `fallback` de um manipulador de falha deve conter pelo menos uma etapa. * Um Subprocesso deve apontar para um procedimento estruturado existente no mesmo agente e não para si mesmo. * `tool_id` deve ser uma ferramenta do agente, `tool_name` deve corresponder, e `schema_overrides` deve corresponder ao esquema da ferramenta. * A lista `steps`, toda `instruction` e toda `message` devem ser não vazias. Para saber como reestruturar um procedimento que encontra uma destas regras, consulte [Boas práticas](#best-practices). ## Exemplo completo da API Este exemplo processa o cancelamento de um pedido com base no status de envio. Ele fixa um parâmetro de ferramenta, recupera-se de uma chamada de ferramenta com falha, chama outro procedimento estruturado e então encerra a chamada. ```json maxLines=30 { "steps": [ { "type": "ask", "instruction": "Ask the user for their order ID." }, { "type": "branch", "branches": [ { "condition": { "type": "llm", "condition": "The user says the order has already shipped." }, "steps": [ { "type": "tell", "instruction": "Explain that shipped orders must be returned before they can be refunded." } ] }, { "condition": { "type": "llm", "condition": "The user says the order has not shipped." }, "steps": [ { "type": "tool_call", "tool_id": "tool_abc123", "tool_name": "cancel_order", "instruction": "Cancel the order using the order ID provided by the user.", "schema_overrides": { "request_body.notify_customer": { "source": "constant", "constant_value": true } }, "on_failure": { "branches": [], "fallback": [ { "type": "tell", "instruction": "Apologize that the cancellation did not go through and say you will try once more." }, { "type": "retry", "max_retries": 1 } ] } } ] } ], "fallback": [ { "type": "ask", "instruction": "Ask whether the order has already shipped." } ] }, { "type": "sub_procedure", "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3" }, { "type": "say", "message": "Thank you for contacting us. Goodbye.", "message_translations": { "es": { "value": "Gracias por contactarnos. Adiós." } } }, { "type": "system_tool", "system_tool_name": "end_call" } ] } ``` ## Como um procedimento estruturado é executado Transformar as etapas de um procedimento estruturado no formato que o agente executa é chamado de compilação. A plataforma compila todos os procedimentos estruturados quando você publica; você não precisa compilar nada. Atualmente, o resultado compilado fica visível como nós somente leitura na aba **Workflow**. Quando a solicitação do usuário corresponde ao gatilho de um procedimento, o agente entra no procedimento e executa suas etapas em ordem. Enquanto está dentro do procedimento estruturado, o agente se concentra em cada etapa isoladamente. Ao chegar ao fim, ele retorna ao restante da conversa. As regras a seguir descrevem como as etapas se comportam durante a execução. #### Apenas Perguntar aguarda o usuário Todas as etapas, exceto Perguntar, são executadas imediatamente, e o controle passa para a próxima etapa dentro do mesmo turno. Uma etapa Informar ou Dizer transmite sua mensagem e continua. Não há etapa que pause a conversa além de Perguntar, nem etapa que encerre o turno atual. Se você precisar de informações do usuário, use uma etapa Perguntar. Se a conversa precisar terminar, use a ferramenta do sistema `end_call`. #### Chegar ao fim de um procedimento não encerra o turno Quando a última etapa é concluída, o procedimento termina e o agente retorna ao restante da conversa com o turno ainda aberto, portanto ele pode dizer mais. Quando um subprocesso é concluído, o controle retorna à próxima etapa do procedimento que o chamou. #### Etapas Ferramenta distinguem apenas sucesso de falha Uma etapa Ferramenta não pode criar uma ramificação com base em um código de status ou no corpo da resposta. Se a ferramenta for bem-sucedida, o procedimento continua. Se ela falhar e a etapa não tiver manipulador de falha, a conversa será encerrada. Se houver um, as etapas do manipulador serão executadas e o procedimento continuará para a próxima etapa. Uma etapa Tentar novamente dentro do manipulador executa novamente a ferramenta e, se ela falhar outra vez, todas as etapas do manipulador, até que a ferramenta seja bem-sucedida ou as tentativas se esgotem. Se elas se esgotarem, a conversa será encerrada. #### Etapas Se continuam quando não há correspondência As condições são avaliadas em ordem, e a primeira correspondência é executada. A ramificação Senão é executada quando não há correspondência. Se não houver Senão e nada corresponder, o procedimento continuará com a etapa após o Se. Um caso não tratado não é um erro. #### Ramificações Se não levam o estado adiante Nada que seja decidido dentro de uma ramificação Se é lembrado pelas etapas posteriores. Se algo aprendido em uma ramificação for necessário mais tarde, persista-o explicitamente com uma chamada de ferramenta ou uma variável dinâmica. #### Etapas Perguntar, Informar e Dizer não têm ferramentas Somente etapas Ferramenta podem chamar ferramentas. Não é necessário dizer a uma etapa Perguntar, Informar ou Dizer para não chamar ferramentas; ela não consegue. ## Gerenciar um procedimento estruturado #### Criar pelo painel Abra seu agente no [painel](https://elevenlabs.io/app/agents) e selecione **Procedures**. Use **+** para criar um procedimento estruturado. Adicione um gatilho, selecione um tipo para cada etapa e publique as alterações do agente. O painel valida os procedimentos estruturados enquanto você edita. Se um procedimento violar uma [regra de validação](#validation-rules), o botão **Publish** exibirá um estado de erro, a aba **Procedures** exibirá um selo de erro e a prévia não poderá iniciar até que o procedimento seja corrigido. Selecione o indicador de erro para ver qual procedimento e etapa são afetados. ![Editor de procedimentos estruturados com o botão Publicar no estado de erro e um selo de 1 erro](/docs/_fern-img/e406c33fac3966fab26d5d07e10d364a475fc4a56fd75aad2e23edbb0d1940d5.webp) ![Caixa de diálogo de detalhes da validação listando o procedimento com falha e a etapa que precisa de uma mensagem](/docs/_fern-img/a1cc889b2d0e68ce23725609b531938d0f7c417b1c6f4375103531eaae4ada63.webp) #### Gerenciar pela CLI A [CLI da ElevenLabs](/docs/pt/eleven-agents/operate/cli) cria e publica procedimentos estruturados com os mesmos comandos usados para procedimentos de formato livre. Defina `type` como `deterministic` e passe as etapas como uma string codificada em JSON em `content`. ```bash CONTENT=$(jq -n '{ trigger: "When the user asks to refund an order", steps: [{ type: "ask", instruction: "Ask for the order ID." }] }') elevenlabs agents procedures create \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json "$(jq -n --arg content "$CONTENT" '{ name: "Refund request", type: "deterministic", trigger: "When the user asks to refund an order", content: $content }')" elevenlabs agents update \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json '{"version_description": "Publish refund procedure"}' ``` A publicação valida todos os procedimentos estruturados na ramificação. Se algum for inválido, o comando termina com um código diferente de zero e imprime os erros identificados pelo ID do procedimento. Corrija o rascunho do procedimento e publique novamente. #### Gerenciar pela API As cargas úteis da API e do SDK usam `type: "deterministic"` para procedimentos estruturados. Seu `content` é um documento codificado em JSON. ### Pré-requisitos * Uma chave de API da ElevenLabs na variável de ambiente `ELEVENLABS_API_KEY`. * Os valores `agent_id` e `branch_id` de destino. Consulte [Controle de versões de agentes](/docs/pt/eleven-agents/operate/versioning) para operações de ramificação. * Versão `2.60.0` ou mais recente do pacote Python `elevenlabs` ou do pacote JavaScript `@elevenlabs/elevenlabs-js`. As edições pela API são privadas para seu usuário na ramificação selecionada até que você publique uma nova versão do agente. ### Criar ou atualizar um rascunho Crie um procedimento estruturado com `POST /procedures` e defina `type` como `deterministic`. Atualize um procedimento existente com `PATCH /procedures/{procedure_id}/draft`, como mostrado abaixo. Defina `trigger` como um campo de nível superior. Codifique o documento de etapas em JSON no campo `content`, em vez de enviar um objeto aninhado. ```python focus={6-18} import json from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.procedures.drafts.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", procedure_id="agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3", name="Refund request", type="deterministic", trigger="When the user asks to refund an order", content=json.dumps( { "steps": [{"type": "ask", "instruction": "Ask for the order ID."}], } ), ) ``` ```typescript focus={5-17} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.procedures.drafts.update( "agent_7101k5zvyjhmfg983brhmhkd98n6", "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3", { name: "Refund request", type: "deterministic", trigger: "When the user asks to refund an order", content: JSON.stringify({ steps: [{ type: "ask", instruction: "Ask for the order ID." }], }), } ); ``` ```bash focus={1-9} curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures/agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3/draft" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Refund request", "type": "deterministic", "trigger": "When the user asks to refund an order", "content": "{\"steps\":[{\"type\":\"ask\",\"instruction\":\"Ask for the order ID.\"}]}" }' ``` Salvar um rascunho de procedimento não valida suas etapas. A validação é executada quando você publica ou quando salva o rascunho do agente com `POST /v1/convai/agents/{agent_id}/drafts`. ### Publicar as alterações Publique com [Atualizar agente](/docs/pt/api-reference/agents/update). A publicação valida todos os procedimentos estruturados na ramificação, compila-os e armazena o resultado com a nova versão. A solicitação não precisa de um campo `workflow`; a compilação ocorre como parte da publicação. Consulte [Como um procedimento estruturado é executado](#how-a-structured-procedure-runs) para entender o que compilar significa. ```python focus={5-8} from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t", ) ``` ```typescript focus={5-7} import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t", }); ``` ```bash focus={1-5} curl -X PATCH \ "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` Se um procedimento estruturado for inválido, a publicação retornará `400` e nada será gravado: ```json { "detail": { "status": "procedure_validation_failed", "message": "Structured procedures failed validation.", "data": { "errors": { "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3": [ { "path": "steps[0].ask.instruction", "message": "Step 1: Ask step requires an instruction" } ] } } } } ``` `errors` é identificado pelo ID do procedimento. Cada entrada nomeia o campo e a etapa com falha. Corrija o rascunho do procedimento e publique novamente. > **Note** > > O endpoint `/procedures/compile` de versões anteriores desta API ainda funciona, mas é > legado e acabará sendo descontinuado. A publicação realiza a compilação; não chame o > endpoint de compilação em código novo. Consulte [Gerenciar procedimentos](/docs/pt/eleven-agents/customization/procedures#manage-procedures) para saber sobre remoção e descarte de rascunhos, ou a [referência da API de procedimentos](/docs/pt/api-reference/agents/procedures/) para ver os esquemas completos dos endpoints. ## Práticas recomendadas Cada tipo de etapa já impõe seu próprio comportamento, então você raramente precisa especificá-lo. Escreva a intenção de cada etapa e deixe o tipo de etapa fazer o resto. As orientações abaixo abordam os casos que vale a pena acertar. Para testar um procedimento estruturado, siga [Iteração em um procedimento](/docs/pt/eleven-agents/customization/procedures/free-form-procedures#iterating-on-a-procedure). ### Como escolher tipos de etapa #### Faça uma pergunta por etapa Ask Uma etapa Ask espera uma resposta. Se você reunir várias perguntas em uma única instrução, o agente tende a ignorar algumas ou juntá-las. Use uma etapa Ask para cada informação. #### Use Tell para afirmações e Ask para perguntas Uma etapa Tell transmite sua mensagem e segue adiante sem esperar. Uma etapa Tell formulada como pergunta nunca recebe resposta. Se uma etapa precisa de uma resposta do usuário, ela é uma etapa Ask. #### Dê à etapa Ask uma condição clara de saída quando apenas a pergunta não for suficiente Uma etapa Ask avança quando recebe uma resposta adequada. Se o que conta como resposta não estiver claro na pergunta, diga isso na instrução, por exemplo, \_Peça o ID do pedido; um ID válido tem oito dígitos \_. #### Escolha Tell para formulação e Say para palavras exatas Use uma etapa Tell quando o agente deve compor a mensagem por conta própria e uma etapa Say quando a redação deve ser literal ou traduzida. Ambas enviam exatamente uma mensagem, portanto não é necessário instruir uma etapa a enviar uma única mensagem. #### Não diga a etapas sem ferramentas para evitar ferramentas As etapas Ask, Tell e Say não podem chamar ferramentas. Escrever *não chame nenhuma ferramenta* nelas adiciona ruído à instrução sem mudar o comportamento. ### Como estruturar o procedimento #### Não preencha o espaço entre duas etapas If Duas etapas If não podem ser colocadas uma após a outra. Inserir uma etapa Tell ou Say sem relação entre elas para cumprir a regra faz o agente dizer algo que não deveria. Em vez disso, incorpore a segunda decisão à primeira etapa If como ramificações Else if adicionais ou mova-a para um subprocedimento. #### Coloque decisões aninhadas em um subprocedimento Etapas If não podem ser aninhadas. Quando uma decisão depende de outra, coloque a decisão interna em seu próprio procedimento estruturado e chame-o com uma etapa Sub-procedure a partir da ramificação que precisa dele. #### Adicione um Else quando 'nenhuma das opções acima' for importante Uma etapa If sem Else segue para a próxima etapa quando nada corresponde. Se o caso sem correspondência precisar se comportar de forma diferente, adicione uma ramificação Else para ele. #### Persista tudo de que uma etapa posterior precisa Decisões tomadas dentro de uma ramificação If não são lembradas depois. Se uma etapa posterior depender de algo aprendido em uma ramificação, registre isso com uma chamada de ferramenta ou uma variável dinâmica dentro da ramificação. #### Posicione condições de expressão após a ferramenta que as preenche Condições de expressão testam variáveis dinâmicas. Coloque uma etapa If que as utiliza logo após a etapa Tool que define essas variáveis. Para criar ramificações com base no que o usuário disse, use uma condição de texto. #### Extraia etapas compartilhadas para um subprocedimento Quando vários procedimentos estruturados compartilham a mesma sequência, como encaminhar para uma pessoa, coloque-a em um procedimento estruturado com um gatilho vazio e chame-o de cada um. Sequências copiadas se distanciam com o tempo. ### Como trabalhar com ferramentas #### Controle uma etapa Tool com uma etapa If, não com sua instrução Uma etapa Tool sempre chama sua ferramenta. Uma condição escrita na instrução, como \_pule isto se o tíquete já estiver marcado \_, não consegue impedir a chamada. Se a chamada nem sempre deve acontecer, coloque a condição em uma etapa If antes da etapa Tool. #### Defina valores de parâmetros em vez de descrevê-los Quando um parâmetro deve sempre assumir um valor específico, defina-o com uma substituição `constant` em `schema_overrides`. Uma instrução como *sempre defina o status como pendente* pede que o modelo cumpra isso; uma substituição é aplicada e não pode ser ignorada. #### Dê a cada etapa Tool um manipulador de falhas Sem `on_failure`, qualquer falha de ferramenta encerra a conversa. Adicione um manipulador que diga ao usuário o que aconteceu e tente novamente, encaminhe ou continue. #### Mantenha as etapas Tool restritas à chamada da ferramenta Uma etapa Tool apenas executa a ferramenta; o agente não pode falar nem tomar uma decisão durante ela. Para falar com o usuário ou criar ramificações com base no retorno da ferramenta, coloque isso em uma etapa separada antes ou depois da etapa Tool. ### Como escrever instruções #### Descreva apenas a etapa atual O procedimento controla o que é executado a seguir, e o agente não conhece as etapas posteriores enquanto executa a atual. Deixe a ordem das etapas fazer o sequenciamento. #### Não tente encerrar o turno com texto Frases escritas nas instruções da etapa, como *esta é a última mensagem deste turno*, pedem que o agente aplique um limite que a plataforma não aplica. Use uma etapa Ask para esperar pelo usuário ou a ferramenta de sistema `end_call` para encerrar a conversa. #### Mantenha regras globais no prompt de sistema Tom, formatação, despedidas e políticas de recusa devem ficar no [prompt de sistema](/docs/pt/eleven-agents/best-practices/prompting-guide). Uma instrução de etapa deve dizer apenas o que é específico daquela etapa. ### Como compor procedimentos As orientações gerais para compor procedimentos também se aplicam a procedimentos estruturados; consulte [Como compor procedimentos](/docs/pt/eleven-agents/customization/procedures/free-form-procedures#composing-procedures) na página de procedimentos de formato livre. Um padrão é específico para combinar tipos: um procedimento de formato livre pode fazer referência a um estruturado. Mantenha o tratamento de situações abertas em um procedimento de formato livre e delegue as partes que precisam ser executadas da mesma forma todas as vezes, como verificação de identidade ou encaminhamento, a um procedimento estruturado. ## Limitações * Etapas If não podem ser aninhadas, e duas etapas If não podem ser colocadas uma após a outra. * A única ferramenta de sistema compatível é `end_call`. * Procedimentos estruturados não podem fazer referência a documentos da base de conhecimento. * Não há como encerrar o turno atual quando um procedimento é concluído; o agente mantém o turno aberto e pode continuar falando. * Não é possível iniciar um procedimento estruturado a partir de um nó específico do workflow no painel. * Iniciar um procedimento adiciona latência: o agente faz uma chamada de ferramenta para entrar nele e depois avança pelo workflow gerado. ### Suporte de provedores de modelo Procedimentos estruturados forçam chamadas de ferramentas internas ao entrar em um subprocedimento e ao concluir um procedimento. As principais famílias de modelos OpenAI, Anthropic, Gemini e Grok oferecem suporte à escolha forçada de ferramenta. Outros modelos ou provedores personalizados podem não garantí-la, o que pode tornar as transições de subprocedimentos ou a conclusão de procedimentos menos confiáveis. Verifique o suporte à escolha forçada de ferramenta ao usar outro provedor de modelo. Consulte [Procedimentos](/docs/pt/eleven-agents/customization/procedures#limitations) para ver limites aplicáveis a todos os procedimentos, incluindo o limite de tamanho do conteúdo e como os procedimentos estruturados diferem dos de formato livre.