Procedimentos | ElevenLabs Documentation

Visão geral

Um procedimento contém instruções para uma tarefa específica. Cada procedimento tem um gatilho que descreve quando ele se aplica e um conteúdo que descreve o que fazer. Quando uma conversa corresponde ao gatilho, o agente carrega o procedimento.

Use procedimentos quando seu agente precisar lidar com muitas tarefas distintas. Um exemplo de uso é um agente de suporte ao cliente, em que cada procedimento abrange um tipo de solicitação: reembolsos, verificação de identidade, recuperação de conta ou solução de problemas de conexão.

Tipos de procedimento

Há dois tipos de procedimentos:

Procedimentos livres são escritos como instruções em linguagem natural que o agente interpreta e adapta à situação.
Procedimentos estruturados são uma lista ordenada de etapas tipadas que o agente executa da mesma forma todas as vezes.

Você pode usar ambos os tipos no mesmo agente. O agente escolhe o procedimento relevante com base no gatilho, independentemente do tipo.

Os procedimentos podem chamar uns aos outros. Um procedimento livre chama outro procedimento com uma referência embutida, e um procedimento estruturado chama outro procedimento estruturado com uma etapa de subprocedimento. Um padrão comum é manter o tratamento aberto em um procedimento livre e transferir as partes que precisam ser executadas da mesma forma todas as vezes para um procedimento estruturado.

Um agente pode ter procedimentos, um workflow ou ambos. Quando ambos estão presentes, todos os procedimentos estão disponíveis em todos os pontos do workflow; não é possível limitar um procedimento a nós específicos do workflow. A maioria dos agentes é criada em torno de uma abordagem ou outra, mas as duas podem ser combinadas.

Quando usar procedimentos

Todo agente tem um prompt de sistema. Procedimentos e workflows são duas formas de adicionar estrutura a ele, e um agente pode usar ambos. Escolha um ponto de partida com base no quanto a conversa pode variar.

Requisito	Use	Motivo
Agente simples de prova de conceito	Apenas prompt de sistema	É a forma mais rápida de configurar e iterar, mas um único prompt fica difícil de gerenciar à medida que o escopo do agente cresce.
Tarefa em que o agente pode adaptar a redação e a ordem	Procedimento livre	Mantém toda a conversa no contexto de um único LLM, para que o agente adapte a redação e a ordem e possa lidar com rumos inesperados. Usa mais da janela de contexto.
Tarefa cujas etapas devem ser executadas sempre da mesma forma	Procedimento estruturado	Cada etapa é executada na ordem que você definir, sempre da mesma forma, e você a cria como uma lista curta de etapas.
Controle total sobre ramificações complexas e casos extremos	Workflow	É executado como um grafo de subagentes que você projeta e conecta, com controle total sobre as ramificações e o modelo usado em cada etapa.

Procedimentos livres são a escolha padrão. Eles são os mais rápidos de escrever, parecem um documento para que equipes não técnicas possam administrá-los, e o agente consegue se recuperar quando uma conversa sai do roteiro. Use um procedimento estruturado quando o custo de pular ou reordenar uma etapa for alto, como em autenticação, escalonamento ou uma transação financeira. Use um workflow quando precisar de lógica de roteamento ou controle do modelo por etapa que nenhum dos tipos de procedimento oferece.

Gerenciar procedimentos

O painel é a forma recomendada de criar procedimentos. Use a CLI ou a API para gerenciar procedimentos programaticamente ou integrá-los às ferramentas de implantação.

Criar pelo painel

Gerenciar pela CLI

Gerenciar pela API

Abra seu agente no painel e selecione Procedimentos. Use + para criar um procedimento livre ou estruturado. Os procedimentos podem ser agrupados em pastas pelo mesmo menu. Consulte Procedimentos livres e Procedimentos estruturados para orientações de criação.

Escolher procedimentos por conversa

Por padrão, toda conversa pode usar todos os procedimentos do agente, e o agente só carrega um procedimento depois que a conversa corresponde ao gatilho dele. Muitas vezes, sua aplicação sabe mais antes de a conversa começar: quem é o usuário, em qual região ele está ou sobre o que ligou. Passe IDs de procedimentos nos dados de cliente da iniciação da conversa para usar esse conhecimento. Você decide quais procedimentos o agente pode usar e quais ele segue desde o primeiro turno.

Campo	O que faz	Por que usar
`procedure_ids`	Limita a conversa a estes procedimentos. Um array vazio desativa todos os procedimentos do agente.	Dê a cada usuário apenas os procedimentos que se aplicam a ele; por exemplo, oculte procedimentos de conta de um usuário que não fez login. Use-o também quando os procedimentos tiverem gatilhos semelhantes que você não puder evitar, como um procedimento de reembolso por região. Passe apenas a região do usuário, para que o agente não possa seguir o procedimento de outra região.
`start_procedure_ids`	Inicia estes procedimentos livres junto com a conversa, para que o agente os siga desde o primeiro turno. Aceita até cinco IDs.	Responda mais rápido quando já souber a tarefa do usuário, por exemplo, pela opção escolhida em um menu IVR, pela página que hospeda o widget ou pelos dados do CRM.

Um procedimento em start_procedure_ids já é carregado quando o usuário fala pela primeira vez, então o agente ignora a chamada ao LLM que o carregaria. Qualquer procedimento ativo permanece no prompt em todos os turnos, independentemente de ter sido iniciado pelo agente ou pela sua aplicação. Um procedimento iniciado de que a conversa nunca precisa ainda adiciona seu conteúdo a todos os turnos, então inicie apenas os procedimentos que a conversa provavelmente usará.

Permitir a seleção de procedimentos

A substituição de Procedimentos vem desativada por padrão. Ative-a em cada agente que deve aceitar IDs de procedimentos do cliente.

Painel

CLI

SDK

Abra seu agente no painel, selecione a aba Segurança e ative a substituição de Procedimentos.

Passe os IDs quando a conversa começar

Se o agente não tiver a substituição de Procedimentos ativada ou se um ID for inválido, a conversa não poderá ser iniciada.

Obtenha IDs de procedimentos em Listar procedimentos. Adicione procedure_ids, start_procedure_ids ou ambos aos dados de cliente da iniciação da conversa:

Payload de iniciação da conversa

{
  "type": "conversation_initiation_client_data",
  "procedure_ids": [
    "agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b",
    "agtprc_2301k8f3xq9zfa7tkrqs6m4bdn5e",
    "agtprc_7801k8f3yt4mfzh2xbq9d0vcpw1r"
  ],
  "start_procedure_ids": ["agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b"]
}

O agente inicia a conversa com o primeiro procedimento já em execução. Ele ainda pode iniciar os outros dois quando a conversa corresponder aos gatilhos deles.

Os SDKs de conversa para Python e JavaScript não enviam procedure_ids nem start_procedure_ids. Para usar esses campos, envie você mesmo a mensagem de iniciação pelo WebSocket.

Ambos os campos seguem estas regras:

Cada ID em procedure_ids deve pertencer ao agente. Se um procedimento selecionado chamar subprocedimentos, inclua os subprocedimentos também.
Cada ID em start_procedure_ids deve ser um procedimento livre. Quando você também passa procedure_ids, cada ID também deve estar nessa lista.
procedure_ids se aplica apenas ao agente com o qual a conversa começa. Ele não se aplica após uma transferência de agente.
Procedimentos iniciados contam para o limite de cinco procedimentos ativos em Limitações. O histórico da conversa registra cada um como uma chamada de ferramenta start_procedure.

Limitações

O conteúdo de um procedimento é limitado a 50.000 caracteres.
O agente mantém os cinco procedimentos iniciados mais recentemente no contexto. Quando mais procedimentos são iniciados em uma conversa, o conteúdo, as ferramentas embutidas e os documentos da base de conhecimento dos procedimentos livres mais antigos saem do prompt. Mantenha os procedimentos focados e use subprocedimentos para que poucos estejam ativos ao mesmo tempo.
Não é possível alterar o tipo de um procedimento depois de criá-lo. Para converter entre livre e estruturado, crie um novo procedimento e atualize todas as referências a ele.
Os procedimentos pertencem a um único agente. Eles não podem ser compartilhados entre agentes nem armazenados como recursos no nível do workspace.
Duplicar um agente copia seus procedimentos em vez de compartilhá-los. As cópias recebem novos IDs de procedimento, então as referências no agente duplicado devem usar esses novos IDs.
Não é possível limitar procedimentos a nós específicos do workflow. Quando um agente tem ambos, todos os procedimentos estão disponíveis em todos os nós.
Procedimentos estruturados não podem fazer referência a documentos da base de conhecimento.