> 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 de formato livre

## Visão geral

Um procedimento de formato livre descreve uma tarefa em linguagem simples e natural. O agente interpreta as instruções e adapta a redação e a ordem à situação. Um procedimento de formato livre pode chamar ferramentas (incluindo ferramentas do sistema, como encerrar uma chamada), consultar documentos da base de conhecimento e encadear outros procedimentos.

## Quando usar um procedimento de formato livre

Use um procedimento de formato livre quando o agente puder adaptar a redação e a ordem à situação e você quiser criá-lo rapidamente em linguagem simples. Para saber como ele se compara a procedimentos estruturados, workflows e ao prompt do sistema, consulte [Quando usar procedimentos](/docs/pt/eleven-agents/customization/procedures#when-to-use-procedures).

## Anatomia de um procedimento

Veja um procedimento de reembolso no editor:

![Exemplo de procedimento de reembolso](/docs/_fern-img/e1264b7a4f94403453087d30ef0894e72d412ba69378e6b8cb1b675e53e887b7.webp)

Um procedimento tem duas partes principais: um gatilho e o conteúdo. Ambos podem conter referências inline a outros recursos, mostradas na captura de tela acima como tags com ícones de chave inglesa. Cada procedimento também tem um nome exibido no dashboard.

### Nome

Um rótulo curto que identifica o procedimento no dashboard. O nome nunca é enviado ao LLM, portanto não afeta o comportamento do agente.

### Gatilho

Uma descrição de quando o agente deve usar este procedimento, por exemplo, *Quando o usuário pedir o reembolso de um pedido*.

Deixe o gatilho vazio somente ao criar um [subprocedimento](#sub-procedures).

### Conteúdo

O corpo do procedimento, escrito em markdown. O conteúdo descreve o que o agente deve fazer: fazer uma pergunta, consultar um pedido, chamar uma ferramenta ou encerrar a chamada. Pode ser uma sequência numerada de etapas a seguir ou orientações gerais para a situação. Cada etapa ou diretriz pode ser uma única frase (*Peça ao usuário o ID do pedido*) ou um parágrafo curto explicando o que fazer e por quê.

Use etapas numeradas para ações sequenciais e marcadores para requisitos ou subitens dentro de uma etapa.

### Referências inline

Os procedimentos podem referenciar diferentes tipos de recursos inline:

* Ferramentas (por exemplo, consultar um pedido, cobrar um cartão, encerrar a chamada, transferir para uma pessoa)
* Documentos da base de conhecimento
* Outros procedimentos

Use referências inline sempre que uma etapa exigir que o agente use uma ferramenta, um documento da base de conhecimento ou outro procedimento. As referências anexam automaticamente o recurso ao procedimento para que o agente possa usá-lo. Menções em texto simples (como *use a ferramenta de calculadora aqui*) também funcionam, mas somente se o recurso já estiver anexado ao agente.

Insira uma referência digitando `/` no gatilho ou conteúdo e escolhendo o recurso no menu de barra. As referências aparecem como tags clicáveis no editor. Clique em uma tag para abrir o recurso correspondente e confirmar sua configuração.

Ao escrever conteúdo de formato livre pela API, insira referências com a seguinte sintaxe:

```text focus={1-5}
[tool id="tool_abc123"]
[kb id="kb_abc123"]
[procedure id="agtprc_abc123"]
[system_tool id="end_call"]
{{customer_id}}
```

Uma referência inline a um procedimento deve usar um procedimento do mesmo agente. Consulte [Limitações](/docs/pt/eleven-agents/customization/procedures#limitations) para saber sobre o escopo do agente e o comportamento de duplicação.

Uma referência no gatilho permite que o procedimento seja iniciado com base na saída de um recurso, por exemplo, *Quando `get_user` retornar o nível 'gold'*. Uma referência no conteúdo instrui o agente a invocar ou consultar o recurso naquela etapa.

![Menu de barra no editor de procedimentos](/docs/_fern-img/8625ffec0f5584619e6ccb97720fd86f2e8d3cd0061308ad87b57f176e5535e3.webp)

Se um recurso referenciado for excluído posteriormente ou sua conta perder o acesso a ele, a tag será exibida como inválida. O selo **Erros** no topo do editor lista essas referências: *inválida* se o recurso não existir mais, ou *indisponível* se ele existir, mas sua conta não tiver acesso. Abra o selo para ver qual etapa foi afetada e corrigir ou remover a referência.

![Caixa de diálogo Erros listando referências inválidas](/docs/_fern-img/e9ec6b19be2992da80a726883baf53265a5d5b38621373cd7e60375c944674cd.webp)

## Subprocedimentos

Um subprocedimento tem um gatilho vazio. O agente só pode executá-lo a partir de outro procedimento que o referencie.

Use subprocedimentos para [compartilhar etapas](#composing-procedures) em um mesmo agente e reduzir o número de procedimentos disponíveis ao mesmo tempo. Dê um gatilho ao procedimento de entrada, referencie subprocedimentos relacionados no conteúdo dele e deixe os gatilhos deles vazios.

Um subprocedimento de escalonamento pode conter as etapas para transferir a conversa para uma pessoa. Referencie-o nos procedimentos de reembolso e cancelamento e deixe seu gatilho vazio. O agente pode escalar como uma etapa de qualquer um dos procedimentos, mas fora deles o subprocedimento permanece indisponível.

## Importar de um documento

Você pode começar a partir de um procedimento operacional padrão (SOP) existente. Escolha **Do SOP** no menu **+** da lista de procedimentos e envie um arquivo.

Formatos compatíveis: `PDF`, `DOCX`, `TXT`, `MD`, `HTML`, `EPUB`. Os arquivos devem ter 20 MB ou menos.

O importador analisa o documento, identifica até 10 procedimentos distintos e cria um rascunho para cada um com nome, gatilho e conteúdo gerados. Abra cada rascunho para refiná-lo. Se o documento contiver mais de 10 SOPs, divida-o em arquivos menores antes de enviar.

![Caixa de diálogo para enviar SOP](/docs/_fern-img/716601fc90dea757e23971e5aabe063e6a66fc0f75878247dc9f1fc3011f5197.webp)

## Gerenciar um procedimento de formato livre

#### Criar pelo dashboard

Abra seu agente no [dashboard](https://elevenlabs.io/app/agents) e selecione **Procedimentos**.
Use **+** para criar um procedimento de formato livre. Adicione um gatilho e escreva as instruções no
editor de conteúdo. Em seguida, publique as alterações do agente.

#### Gerenciar pela API

Os procedimentos de formato livre armazenam markdown em `content`.

### Pré-requisitos

* Uma chave de API da ElevenLabs na variável de ambiente `ELEVENLABS_API_KEY`.
* O `agent_id` e o `branch_id` de destino. Consulte [Versionamento de agentes](/docs/pt/eleven-agents/operate/versioning) para operações de ramificação.
* A versão `2.60.0` ou mais recente do pacote Python `elevenlabs` ou do pacote JavaScript `@elevenlabs/elevenlabs-js`.

Os rascunhos de procedimentos são [por usuário, por ramificação](/docs/pt/eleven-agents/operate/versioning#drafts). A publicação salva suas alterações
de procedimentos em uma nova versão do agente nessa ramificação. Os rascunhos de outros usuários não são afetados.

### Criar um rascunho

```python focus={1,5-15}
from elevenlabs import CreateProcedureRequestModel, ElevenLabs

elevenlabs = ElevenLabs()

procedure = elevenlabs.conversational_ai.agents.procedures.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
    request=CreateProcedureRequestModel(
        name="Refund request",
        type="free_form",
        trigger="When the user asks to refund, return, or get money back for an order",
        content="Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
    ),
)

print(procedure.procedure_id)
```

```typescript focus={5-15}
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const procedure = await elevenlabs.conversationalAi.agents.procedures.create(
  "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
  {
    name: "Refund request",
    type: "free_form",
    trigger: "When the user asks to refund, return, or get money back for an order",
    content: "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
  }
);

console.log(procedure.procedureId);
```

```bash focus={1-8}
curl -X POST "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund request",
    "type": "free_form",
    "trigger": "When the user asks to refund, return, or get money back for an order",
    "content": "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"]."
  }'
```

A resposta inclui o novo `procedure_id`. Para atualizar o rascunho, chame
`PATCH /procedures/{procedure_id}/draft` com `name`, `content`, `type` e um
`trigger` explícito.

Use um `trigger` não vazio para um procedimento de entrada. Para um
[subprocedimento](#sub-procedures), use uma string vazia.

### Publicar as alterações

Atualize o agente na ramificação para publicar seus rascunhos de procedimentos de formato livre em uma nova versão.
A solicitação não precisa de campos no corpo; a publicação usa os rascunhos como estão.

```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 '{}'
```

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

> **Tip**
>
> O agente precisa escolher o procedimento certo com base no gatilho e seguir o conteúdo. Modelos mais capazes
> fazem isso com mais confiabilidade à medida que o número de procedimentos cresce. Consulte
> [Modelos](/docs/pt/eleven-agents/customization/llm) para ver as opções.

Escrever bons procedimentos significa escrever bem duas partes: um gatilho que executa o procedimento quando necessário e um conteúdo que o agente consegue seguir.

### Iterar em um procedimento

Recomendamos começar pequeno e usar [testes de agente](/docs/pt/eleven-agents/customization/agent-testing) para verificar cada alteração antes de fazer a próxima:

1. Escreva um gatilho e um conteúdo curto.
2. Crie testes de simulação para solicitações que devem iniciar o procedimento e para solicitações semelhantes que não devem.
3. Crie um teste de simulação que execute todo o procedimento.
4. Execute os testes. Quando um falhar, corrija o gatilho ou o conteúdo.
5. Execute os testes novamente após cada alteração.

Quando um teste ou uma conversa ao vivo falhar, pesquise conversas anteriores em busca de falhas semelhantes antes de alterar o procedimento e, então, escreva uma instrução que cubra todas elas. A causa também pode estar na base de conhecimento ou na configuração do agente. O [Architect](/docs/pt/eleven-agents/operate/architect) pode fazer essa pesquisa: abra a conversa que falhou, selecione **Architect** e peça para encontrar falhas semelhantes e propor uma correção. O Architect também pode transformar a conversa em um teste.

> **Tip**
>
> Para iterar rapidamente em um gatilho, teste-o com um teste de simulação que tenha **Máximo de turnos
> da conversa** definido como `1`. A simulação para após a primeira troca, o que é suficiente para mostrar se
> a solicitação inicial inicia o procedimento certo e mantém cada execução curta.

### Escrever gatilhos

#### Mantenha os gatilhos concretos e distintos

Gatilhos sobrepostos ou vagos fazem com que o procedimento errado seja executado. Prefira *Quando o usuário pedir para
cancelar uma assinatura* a \_Quando o usuário tiver uma pergunta sobre a conta \_.

#### Escreva pela perspectiva do usuário

Descreva o que o usuário está pedindo, não o que o agente deve fazer. Gatilhos formulados como ações do agente
são menos confiáveis. Prefira *Quando o usuário pedir para cancelar a assinatura* a \_Cancele
a assinatura do usuário \_.

#### Cubra a forma como os usuários realmente pedem

Um gatilho restrito pode não identificar solicitações reais quando o usuário formula as coisas de outro jeito. Inclua as
variações que o usuário pode dizer. *Quando o usuário pedir reembolso, devolução ou dinheiro de volta por um
pedido* é executado com mais confiabilidade do que \_Quando o usuário solicitar um reembolso \_. [Pesquise conversas anteriores](/docs/pt/eleven-agents/customization/agent-analysis/smart-search) para descobrir como os usuários
formulam a solicitação.

#### Faça a transição entre procedimentos relacionados

Às vezes, os usuários mudam a solicitação no meio de um procedimento, e apenas o gatilho pode não
iniciar o procedimento certo. Para uma mudança que você vê com frequência em conversas anteriores, adicione uma referência inline
ao outro procedimento no conteúdo do primeiro procedimento. Por exemplo, escreva *Se o usuário quiser um
reembolso em vez de uma troca, execute* seguido de uma referência inline ao procedimento de reembolso. Se
a maioria dos procedimentos precisar de uma transição, torne os gatilhos mais distintos.

### Escrever conteúdo

#### Use a forma imperativa

Escreva as etapas como instruções ao agente: *Consulte o último pedido do cliente* em vez de \_Você
deve consultar o último pedido do cliente \_. Instruções diretas são mais fáceis de seguir do que
sugestões.

#### Explique por que uma etapa é importante

O raciocínio se generaliza para casos extremos que o procedimento não enumera. Um breve *porque precisamos
do ID do pedido para emitir um reembolso* ajuda o agente a lidar com situações que as etapas não previram.
Evite DEVE em maiúsculas e scripts rígidos quando uma explicação de uma linha fizer o mesmo trabalho.

#### Diga o que fazer em vez do que evitar

Descreva o comportamento desejado. *Se não conseguir encontrar o pedido, peça ao usuário para confirmar o
ID do pedido* funciona melhor do que \_Não invente detalhes do pedido \_. Para erros com alto custo, adicione também uma
[proteção](/docs/pt/eleven-agents/best-practices/guardrails).

#### Mantenha os fatos na base de conhecimento

Um procedimento descreve o que o agente deve fazer em uma situação. Informações específicas, como
preços, detalhes de planos ou horários de funcionamento, pertencem à [base de conhecimento](/docs/pt/eleven-agents/customization/knowledge-base). Referencie o documento no
procedimento que precisa dele. Por exemplo, em vez de listar o preço de cada plano no procedimento,
escreva *Informe o preço de* seguido de uma referência inline a um documento de preços.

### Compor procedimentos

#### Escreva um procedimento por situação

Se uma situação for dividida entre vários procedimentos restritos, o agente terá mais gatilhos para
escolher e iniciará o errado com mais frequência. Se dois procedimentos forem iniciados pela mesma
solicitação, combine-os. Conteúdos com mais de cerca de 3.000 caracteres geralmente abrangem mais de uma
situação.

#### Extraia etapas compartilhadas para um subprocedimento

Se as mesmas etapas aparecerem em vários procedimentos (verificar a identidade de um cliente, consultar
um pedido, escalar para uma pessoa), extraia-as para um [subprocedimento](#sub-procedures) e
referencie-o em cada procedimento que precisar delas pelo menu de barra. Manter as etapas compartilhadas em um só
lugar garante consistência em todos os procedimentos que as usam.

#### Use subprocedimentos para ações reativas

Use um subprocedimento para uma ação que o agente deve executar somente quando outro procedimento a solicitar,
como verificação de identidade ou escalonamento. Sem um gatilho, ele não compete com procedimentos de entrada
no início da conversa. Menos opções de gatilho mantêm o roteamento focado.

#### Referencie ferramentas no procedimento que as utiliza

Referencie uma ferramenta no procedimento que a utiliza, em vez de anexá-la ao agente inteiro. Assim, a
ferramenta fica fora de conversas não relacionadas. Em um procedimento de formato livre, a ferramenta fica disponível
somente enquanto o procedimento estiver entre os cinco iniciados mais recentemente. Consulte
[Limitações](/docs/pt/eleven-agents/customization/procedures#limitations).

#### Use o prompt do sistema para comportamentos globais

Tom, identidade, políticas de recusa e proteções pertencem ao [prompt do sistema](/docs/pt/eleven-agents/best-practices/prompting-guide). Coloque etapas específicas de tarefas nos
procedimentos.

#### Os procedimentos são versionados com o agente

Os procedimentos fazem parte da configuração do agente, portanto são registrados juntos quando você publica uma
nova versão do agente. Para reverter a um conjunto anterior de procedimentos, restaure uma versão anterior do agente.
Consulte [Versionamento de agentes](/docs/pt/eleven-agents/operate/versioning).

#### Comece com a documentação existente

Se sua equipe já tem SOPs, use o importador para transformá-los em rascunhos e refine-os a partir daí.