> 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.

# Substituições

> **Warning**
>
> Embora as substituições ainda sejam compatíveis para substituir completamente os prompts do sistema ou as primeiras mensagens, recomendamos usar [Variáveis dinâmicas](/docs/pt/eleven-agents/customization/personalization/dynamic-variables) como a forma preferencial de personalizar
> as respostas do seu agente e inserir dados em tempo real. As variáveis dinâmicas oferecem melhor
> manutenção e uma abordagem mais estruturada para personalização.

As **substituições** permitem que seu assistente adapte o comportamento a cada interação do usuário. Você pode transmitir dados e configurações personalizados no início de cada conversa, permitindo que o assistente personalize suas respostas e conhecimentos com contexto em tempo real. As substituições substituem completamente os valores padrão do agente definidos no [painel](https://elevenlabs.io/app/agents/agents) do agente.

## Visão geral

As substituições permitem modificar o comportamento do seu agente de IA em tempo real sem criar vários agentes. Isso permite personalizar respostas com dados específicos do usuário.

As substituições podem ser ativadas para os seguintes campos nas configurações de segurança do agente:

* Prompt do sistema
* Primeira mensagem
* Idioma
* ID da voz
* LLM (Large Language Model)
* Ferramentas
* Base de conhecimento
* Modo somente texto
* Estabilidade
* Velocidade
* Impulso de similaridade
* Palavras-chave de ASR

Quando as substituições estão ativadas para um campo, fornecer uma substituição ainda é opcional. Se ela não for fornecida, o agente usará os valores padrão definidos no [painel](https://elevenlabs.io/app/agents/agents) do agente. Para a maioria dos campos, ocorrerá um erro se uma substituição for fornecida quando esse campo não estiver com substituições ativadas.

> **Warning**
>
> As **palavras-chave de ASR** usam recusa suave: se a opção de Segurança estiver desativada e o cliente ainda enviar
> `asr.keywords`, a conversa continuará e as palavras-chave serão ignoradas (sem erro). Ative a substituição de
> **palavras-chave de ASR** nas configurações de Segurança quando quiser aplicar o reforço de palavras-chave
> por conversa. São compatíveis até 50 palavras-chave por conversa.

Veja alguns exemplos em que as substituições podem ser úteis:

* **Cumprimentar usuários** pelo nome
* **Incluir detalhes específicos da conta** nas respostas
* **Ajustar o idioma** ou o tom do agente com base nas preferências do usuário
* **Transmitir dados em tempo real**, como saldos de conta ou status do pedido
* **Melhorar a transcrição** de nomes ou termos por chamada (por exemplo, nomes de empresas no CRM) por meio de palavras-chave de ASR

> **Info**
>
> As substituições são particularmente úteis para aplicativos que exigem interações personalizadas ou que lidam com
> dados confidenciais do usuário que não devem ser armazenados na configuração base do agente.

## Guia

### Pré-requisitos

* Uma [conta da ElevenLabs](https://elevenlabs.io)
* Um Agente Conversacional da ElevenLabs configurado ([crie um aqui](/docs/pt/eleven-agents/quickstart))

Este guia mostra como substituir o **prompt do sistema**, a **primeira mensagem**, o **LLM**, as **ferramentas**, a **base de conhecimento**, as **configurações de TTS** e as **palavras-chave de ASR** padrão do agente.

#### Ativar substituições

Por motivos de segurança, as substituições vêm desativadas por padrão. Ative os campos cuja substituição você deseja permitir, como `first_message`, `prompt.prompt`, `prompt.tool_ids`, `prompt.knowledge_base`, `language` ou `asr.keywords`.

#### Atualizar pelo painel

Acesse as configurações do seu agente e selecione a aba **Segurança**. Ative `First message`, `System prompt`, `Tools`, `Knowledge base`, `ASR keywords` e quaisquer outras substituições de que você precise, como `LLM`.

![Ativar substituições](/docs/_fern-img/496f20380ffe29fc46275bbfe5c6eaabdb5e211c780188243a018b38715ea779.webp)

#### Atualizar pela CLI

#### Baixar a configuração do agente

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### Editar \`agent_configs/\<agent-name>.json\`

Defina os campos em `platform_settings.overrides.conversation_config_override` como `true` para permitir substituições em tempo de execução nesse campo:

```json
{
  "platform_settings": {
    "overrides": {
      "conversation_config_override": {
        "agent": {
          "first_message": true,
          "language": true,
          "prompt": {
            "prompt": true,
            "tool_ids": true,
            "knowledge_base": true
          }
        },
        "tts": { "voice_id": true },
        "asr": { "keywords": true }
      }
    }
  }
}
```

#### Enviar suas alterações

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Atualizar pela API

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    platform_settings={
        "overrides": {
            "conversation_config_override": {
                "agent": {
                    "first_message": True,
                    "language": True,
                    "prompt": {
                        "prompt": True,
                        "tool_ids": True,
                        "knowledge_base": True,
                    },
                },
                "tts": {"voice_id": True},
                "asr": {"keywords": True},
            },
        },
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  platformSettings: {
    overrides: {
      conversationConfigOverride: {
        agent: {
          firstMessage: true,
          language: true,
          prompt: {
            prompt: true,
            toolIds: true,
            knowledgeBase: true,
          },
        },
        tts: { voiceId: true },
        asr: { keywords: true },
      },
    },
  },
});
```

#### Substituir a conversa

No seu código, onde a conversa é iniciada, transmita as substituições como um parâmetro. As substituições de ferramentas e base de conhecimento substituem os arrays padrão daquela conversa. As substituições de palavras-chave de ASR substituem a lista de palavras-chave padrão do agente naquela conversa (máximo de 50 palavras-chave).

**`Payload de início da conversa`**

```json title="Payload de início da conversa" focus={4-15}
{
  "conversation_config_override": {
    "agent": {
      "prompt": {
        "tool_ids": ["tool_7101k5zvyjhmfg983brhmhkd98n6"],
        "knowledge_base": [
          {
            "type": "file",
            "name": "Unladen Swallow Facts",
            "id": "5xM3yVvZQKV0EfqQpLrJ",
            "usage_mode": "auto"
          }
        ]
      }
    },
    "asr": {
      "keywords": ["Acme Corp", "Contoso", "Globex"]
    }
  }
}
```

> **Tip**
>
> Verifique se você tem o [SDK](/docs/pt/eleven-agents/libraries/python) mais recente instalado.

**`Python`**

```python title="Python" focus={3-28} maxLines=28
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
...
conversation_override = {
    "agent": {
        "prompt": {
            "prompt": f"The customer's bank account balance is {customer_balance}. They are based in {customer_location}.", # Optional: override the system prompt.
            "llm": "gpt-4o", # Optional: override the LLM model.
            "tool_ids": [
                "tool_7101k5zvyjhmfg983brhmhkd98n6"
            ], # Optional: replace the tools available to the agent.
            "knowledge_base": [
                {
                    "type": "file",
                    "name": "Unladen Swallow Facts",
                    "id": "5xM3yVvZQKV0EfqQpLrJ",
                    "usage_mode": "auto",
                }
            ], # Optional: replace the knowledge base available to the agent.
        },
        "first_message": f"Hi {customer_name}, how can I help you today?", # Optional: override the first_message.
        "language": "en" # Optional: override the language.
    },
    "tts": {
        "voice_id": "custom_voice_id", # Optional: override the voice.
        "stability": 0.7, # Optional: override stability (0.0 to 1.0).
        "speed": 1.1, # Optional: override speed (0.7 to 1.2).
        "similarity_boost": 0.9 # Optional: override similarity boost (0.0 to 1.0).
    },
    "conversation": {
        "text_only": True # Optional: enable text-only mode (no audio).
    },
    "asr": {
        "keywords": ["Acme Corp", "Contoso"] # Optional: boost ASR for per-call terms (max 50). Requires Security → ASR keywords.
    }
}

config = ConversationInitiationData(
    conversation_config_override=conversation_override
)
conversation = Conversation(
    ...
    config=config,
    ...
)
conversation.start_session()
```

**`JavaScript`**

```javascript title="JavaScript" focus={4-29} maxLines=29
...
const conversation = await Conversation.startSession({
  ...
  overrides: {
      agent: {
          prompt: {
              prompt: `The customer's bank account balance is ${customer_balance}. They are based in ${customer_location}.`, // Optional: override the system prompt.
              llm: "gpt-4o", // Optional: override the LLM model.
              toolIds: [
                  "tool_7101k5zvyjhmfg983brhmhkd98n6"
              ], // Optional: replace the tools available to the agent.
              knowledgeBase: [
                  {
                      type: "file",
                      name: "Unladen Swallow Facts",
                      id: "5xM3yVvZQKV0EfqQpLrJ",
                      usageMode: "auto",
                  }
              ], // Optional: replace the knowledge base available to the agent.
          },
          firstMessage: `Hi ${customer_name}, how can I help you today?`, // Optional: override the first message.
          language: "en" // Optional: override the language.
      },
      tts: {
          voiceId: "custom_voice_id", // Optional: override the voice.
          stability: 0.7, // Optional: override stability (0.0 to 1.0).
          speed: 1.1, // Optional: override speed (0.7 to 1.2).
          similarityBoost: 0.9 // Optional: override similarity boost (0.0 to 1.0).
      },
      conversation: {
          textOnly: true // Optional: enable text-only mode (no audio).
      },
      asr: {
          keywords: ["Acme Corp", "Contoso"] // Optional: boost ASR for per-call terms (max 50). Requires Security → ASR keywords.
      }
  },
  ...
})
```

**`Swift`**

```swift title="Swift" focus={3-16} maxLines=16
import ElevenLabsSDK

let promptOverride = ElevenLabsSDK.AgentPrompt(
    prompt: "The customer's bank account balance is \(customer_balance). They are based in \(customer_location).", // Optional: override the system prompt.
    llm: "gpt-4o" // Optional: override the LLM model.
)
let agentConfig = ElevenLabsSDK.AgentConfig(
    prompt: promptOverride, // Optional: override the system prompt.
    firstMessage: "Hi \(customer_name), how can I help you today?", // Optional: override the first message.
    language: .en // Optional: override the language.
)
let ttsConfig = ElevenLabsSDK.TTSConfig(
    voiceId: "custom_voice_id", // Optional: override the voice.
    stability: 0.7, // Optional: override stability (0.0 to 1.0).
    speed: 1.1, // Optional: override speed (0.7 to 1.2).
    similarityBoost: 0.9 // Optional: override similarity boost (0.0 to 1.0).
)
let conversationConfig = ElevenLabsSDK.ConversationConfig(
    textOnly: true // Optional: enable text-only mode (no audio).
)
let overrides = ElevenLabsSDK.ConversationConfigOverride(
    agent: agentConfig, // Optional: override agent settings.
    tts: ttsConfig, // Optional: override TTS settings.
    conversation: conversationConfig // Optional: override conversation settings.
)

let config = ElevenLabsSDK.SessionConfig(
    agentId: "",
    overrides: overrides
)

let conversation = try await ElevenLabsSDK.Conversation.startSession(
  config: config,
  callbacks: callbacks
)
```

**`Widget`**

```html title="Widget"
  <elevenlabs-convai
    agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
    override-language="es"         <!-- Optional: override the language -->
    override-prompt="Custom system prompt for this user"  <!-- Optional: override the system prompt -->
    override-first-message="Hi! How can I help you today?"  <!-- Optional: override the first message -->
    override-voice-id="custom_voice_id"  <!-- Optional: override the voice -->
  ></elevenlabs-convai>
```

> **Note**
>
> Ao usar substituições, omita os campos que não deseja substituir em vez de defini-los como strings vazias ou valores nulos. Inclua apenas os campos que você deseja personalizar especificamente.

> **Tip**
>
> Para encontrar a string correta do modelo LLM, consulte a [referência da API de Agentes](/docs/pt/api-reference/agents/create#request.body.conversation_config.agent.prompt.llm), que lista todos os modelos LLM compatíveis e seus identificadores de string exatos.