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

# Início rápido

Neste guia, você aprenderá a criar seu primeiro agente conversacional. Ele servirá como base para criar fluxos de trabalho conversacionais adaptados aos casos de uso da sua empresa.

> **Tip**
>
> Use a [habilidade de agentes da ElevenLabs](https://github.com/elevenlabs/skills/tree/main/agents) para criar e gerenciar agentes de voz pelo seu assistente de programação com IA:
>
> ```bash
> npx skills add elevenlabs/skills --skill agents
> ```
>
> Você também pode conectar o [servidor MCP hospedado](/docs/pt/eleven-agents/operate/hosted-mcp) ao Claude ou a qualquer outro cliente MCP para criar e gerenciar agentes por meio de linguagem natural.

## Primeiros passos

Os Agentes da ElevenLabs podem ser gerenciados pelo [painel do ElevenAgents](https://elevenlabs.io/app/agents), pela [API da ElevenLabs](/docs/pt/api-reference/introduction), pela [CLI de Agentes](/docs/pt/eleven-agents/operate/cli) ou pelo [servidor MCP hospedado](/docs/pt/eleven-agents/operate/hosted-mcp).

![Agentes da ElevenLabs](/docs/_fern-img/62ad20de44cee44a439b138d56764c801c4eb939cf3b0f167f594d5c6a6895fb.webp)

## Criando seu primeiro agente

Neste guia de início rápido, começaremos criando um agente pela API ou pelo painel web. Em seguida, testaremos o agente, incorporando-o ao seu site ou pelo painel da ElevenLabs.

#### Criar um agente pelo painel web

Neste guia, criaremos um assistente conversacional de suporte capaz de responder a perguntas sobre seu produto, documentação ou serviço. Esse assistente pode ser incorporado ao seu site ou app para oferecer suporte em tempo real aos seus clientes.

![Agentes da ElevenLabs](/docs/_fern-img/62ad20de44cee44a439b138d56764c801c4eb939cf3b0f167f594d5c6a6895fb.webp)

#### Acesse a ElevenLabs

Acesse [elevenlabs.io](https://elevenlabs.io/app/sign-up) e entre na sua conta ou crie uma.

#### Crie um novo assistente

No **Painel da ElevenLabs**, crie um novo assistente inserindo um nome e selecionando a opção `Blank template`.

![Painel](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/61b0e1df291ea587a8ff3e116579a47f66d48c74b24f44cfcd4804a568eb0a9d/assets/images/conversational-ai/assistant-create-flow.gif)

#### Configure o comportamento do assistente

Acesse a aba **Agent** para configurar o comportamento do assistente. Defina o seguinte:

#### Primeira mensagem

Esta é a primeira mensagem que o assistente falará quando um usuário iniciar uma conversa.

**`First message`**

```plaintext First message
Hi, this is Alexis from <company name> support. How can I help you today?
```

#### Prompt de sistema

Este prompt orienta o comportamento, as tarefas e a personalidade do assistente.

Personalize o exemplo a seguir com os dados da sua empresa:

**`System prompt`**

```plaintext System prompt
You are a friendly and efficient virtual assistant for [Your Company Name]. Your role is to assist customers by answering questions about the company's products, services, and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

Tasks:
- Answer Questions: Provide clear and concise answers based on the available information.
- Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

Guidelines:
- Maintain a friendly and professional tone throughout the conversation.
- Be patient and attentive to the customer's needs.
- If unsure about any information, politely ask the customer to repeat or clarify.
- Avoid discussing topics unrelated to the company's products or services.
- Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
```

#### Adicione uma base de conhecimento

Acesse a seção **Knowledge Base** para fornecer ao seu assistente contexto sobre sua empresa.

Aqui você pode fazer upload de documentos relevantes e links para recursos externos:

* Inclua documentação, perguntas frequentes e outros recursos para ajudar o assistente a responder às dúvidas dos clientes.
* Mantenha a base de conhecimento atualizada para garantir que o assistente forneça informações precisas e atuais.

Em seguida, configuraremos a voz do seu assistente.

#### Selecione uma voz

Na aba **Voice**, escolha na [Voice Library](https://elevenlabs.io/voice-library) a voz que melhor combina com seu assistente:

![Configurações de voz](/docs/_fern-img/14aad328f468daafa9ec95d3b7a55489a8cb1a34869368020e05b207c9b0360a.webp)

> **Note**
>
> Usar vozes, modelos e LLMs de maior qualidade pode aumentar o tempo de resposta. Para uma experiência ideal para o cliente, equilibre qualidade e latência com base no caso de uso esperado do seu assistente.

#### Teste seu assistente

Clique no botão **Test AI agent** e tente conversar com seu assistente.

Configure critérios de avaliação e coleta de dados para analisar conversas e melhorar o desempenho do seu assistente.

#### Configure critérios de avaliação

Acesse a aba **Analysis** nas configurações do seu assistente para definir critérios personalizados de avaliação das conversas.

![Configurações de análise](/docs/_fern-img/fee8bc444d5436c71eae3829b9ec8d5cdb6a57c4d4efe6483d7bfed2b066e438.webp)

A transcrição de cada conversa é enviada ao LLM para verificar se objetivos específicos foram alcançados. Os resultados serão `success`, `failure` ou `unknown`, acompanhados de uma justificativa que explica o resultado escolhido.

Vamos adicionar um critério de avaliação chamado `solved_user_inquiry`:

**`Prompt`**

```plaintext Prompt
The assistant was able to answer all of the queries or redirect them to a relevant support channel.

Success Criteria:
- All user queries were answered satisfactorily.
- The user was redirected to a relevant support channel if needed.
```

#### Configure a coleta de dados

Na seção **Data collection**, configure os dados que serão extraídos de cada conversa.

Clique em **Add item** e configure o seguinte:

1. **Tipo de dados:** selecione "string"
2. **Identificador:** insira um identificador único para este dado: `user_question`
3. **Descrição:** forneça instruções detalhadas ao LLM sobre como extrair os dados específicos da transcrição:

**`Prompt`**

```plaintext Prompt
Extract the user's questions & inquiries from the conversation.
```

> **Tip**
>
> Teste seu assistente se passando por um cliente. Faça perguntas, avalie as respostas e ajuste os prompts até ficar satisfeito com o desempenho.

#### Veja o histórico de conversas

Veja os resultados das avaliações e os dados coletados de cada conversa na aba **Call history**.

![Histórico de conversas](/docs/_fern-img/fd517a080ba2c0d678c1ce34ea79afbd0dad764a19da43ca045a1c29b693ee48.webp)

> **Tip**
>
> Revise regularmente o histórico de conversas para identificar problemas e padrões comuns.

O agente recém-criado pode ser testado de várias formas, mas a maneira mais rápida é usar o [painel da ElevenLabs](https://elevenlabs.io/app/agents).

> **Info**
>
> O painel web usa nosso [SDK React](/docs/pt/eleven-agents/libraries/react) internamente para lidar com conversas em tempo real.

Se preferir testar rapidamente o agente no seu próprio site, você pode usar o widget de Agente. Basta colar o snippet HTML a seguir no seu site, substituindo `agent-id` pelo ID do seu agente.

```html
<elevenlabs-convai agent-id="agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
```

#### Criar um agente pela CLI

#### Instale a CLI

**`Homebrew (macOS)`**

```bash title="Homebrew (macOS)"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop (Windows)`**

```powershell title="Scoop (Windows)"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> Está trabalhando com um assistente de programação com IA? Execute `elevenlabs generate-skills` no seu projeto para criar um
> `SKILL.md` para cada grupo de comandos em `skills/`, para que seu assistente conheça toda a superfície da CLI
> sem que você precise colar a documentação. Use `--output-dir` para colocá-los em outro lugar. Isso lê a própria
> definição de API incorporada da CLI, portanto não precisa de chave de API e funciona off-line — além de acompanhar
> a versão da CLI que você tiver instalado.

#### Inicialize um novo projeto

```bash
elevenlabs agents init
```

Isso cria a estrutura do projeto com diretórios de configuração e arquivos de registro.

#### Autentique-se na ElevenLabs

[Crie uma chave de API no painel aqui](https://elevenlabs.io/app/settings/api-keys), que você usará para [usar a CLI](/docs/pt/api-reference/authentication) com segurança.

Depois, execute o comando a seguir para se autenticar na ElevenLabs:

```bash
elevenlabs auth login
```

Isso abrirá uma janela do navegador para autenticação via OAuth. A CLI verificará as credenciais e as armazenará com segurança.

#### Crie o agente

Crie seu primeiro agente usando o modelo de assistente:

```bash
elevenlabs agents add "My Assistant" --template assistant
```

#### Envie para a plataforma ElevenLabs

```bash
elevenlabs agents push
```

Isso envia a configuração local do seu agente para a plataforma ElevenLabs.

#### Teste o agente

O agente recém-criado pode ser testado de várias formas, mas a maneira mais rápida é usar o [painel da ElevenLabs](https://elevenlabs.io/app/agents). No painel, selecione seu agente e clique no botão **Test AI agent**.

> **Info**
>
> O painel web usa nosso [SDK React](/docs/pt/eleven-agents/libraries/react) internamente para lidar com conversas em tempo real.

Se preferir testar rapidamente o agente no seu próprio site, você pode usar o widget de Agente. Use a CLI para gerar o snippet HTML:

```bash
elevenlabs agents widget embed <agent_id>
```

O ID do agente é registrado em `agents.json` quando você envia as alterações, e `elevenlabs agents status` o lista. Isso exibirá o snippet HTML, que você poderá colar diretamente no seu site.

#### Criar um agente pela API

#### Crie uma chave de API

[Crie uma chave de API no painel aqui](https://elevenlabs.io/app/settings/api-keys), que você usará para [acessar a API](/docs/pt/api-reference/authentication) com segurança.

Armazene a chave como um segredo gerenciado e passe-a aos SDKs como uma variável de ambiente por meio de um arquivo `.env` ou diretamente na configuração do seu app, conforme sua preferência.

**`.env`**

```js title=".env"
ELEVENLABS_API_KEY=<your_api_key_here>
```

#### Instale o SDK

#### SDK

Também usaremos a biblioteca `dotenv` para carregar nossa chave de API de uma variável de ambiente.

```python
pip install elevenlabs
pip install python-dotenv
```

```typescript
npm install @elevenlabs/elevenlabs-js
npm install dotenv
```

#### CLI

Instale a CLI da ElevenLabs. Recomendamos Homebrew (macOS) e Scoop (Windows).

**`Homebrew (macOS)`**

```bash title="Homebrew (macOS)"
brew install elevenlabs/tap/elevenlabs
```

**`Scoop (Windows)`**

```powershell title="Scoop (Windows)"
scoop bucket add elevenlabs https://github.com/elevenlabs/scoop-bucket
scoop install elevenlabs
```

**`npm`**

```bash title="npm"
npm install -g @elevenlabs/cli
```

**`curl`**

```bash title="curl"
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/elevenlabs/cli/releases/latest/download/elevenlabs-cli-installer.sh | sh
```

> **Tip**
>
> Está trabalhando com um assistente de programação com IA? Execute `elevenlabs generate-skills` no seu projeto para criar um
> `SKILL.md` para cada grupo de comandos em `skills/`, para que seu assistente conheça toda a superfície da CLI
> sem que você precise colar a documentação. Use `--output-dir` para colocá-los em outro lugar. Isso lê a própria
> definição de API incorporada da CLI, portanto não precisa de chave de API e funciona off-line — além de acompanhar
> a versão da CLI que você tiver instalado.

Em seguida, autentique-se — isso abrirá seu navegador para autorizar a CLI:

```bash
elevenlabs auth login
```

#### Crie o agente

Crie um novo arquivo chamado `create_agent.py` ou `createAgent.mts`, dependendo da linguagem escolhida, e adicione o código a seguir:

```python maxLines=0
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
import os
load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

prompt = """
You are a friendly and efficient virtual assistant for [Your Company Name].
Your role is to assist customers by answering questions about the company's products, services,
and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

Tasks:
- Answer Questions: Provide clear and concise answers based on the available information.
- Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

Guidelines:
- Maintain a friendly and professional tone throughout the conversation.
- Be patient and attentive to the customer's needs.
- If unsure about any information, politely ask the customer to repeat or clarify.
- Avoid discussing topics unrelated to the company's products or services.
- Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
"""

response = elevenlabs.conversational_ai.agents.create(
    name="My voice agent",
    tags=["test"], # List of tags to help classify and filter the agent
    conversation_config={
        "tts": {
            "voice_id": "aMSt68OGf4xUZAnLpTU8",
            "model_id": "eleven_flash_v2"
        },
        "agent": {
            "first_message": "Hi, this is Rachel from [Your Company Name] support. How can I help you today?",
            "prompt": {
                "prompt": prompt,
            }
        }
    }
)

print("Agent created with ID:", response.agent_id)
```

```typescript maxLines=0
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient();

const prompt = `
    You are a friendly and efficient virtual assistant for [Your Company Name].
    Your role is to assist customers by answering questions about the company's products, services,
    and documentation. You should use the provided knowledge base to offer accurate and helpful responses.

    Tasks:
    - Answer Questions: Provide clear and concise answers based on the available information.
    - Clarify Unclear Requests: Politely ask for more details if the customer's question is not clear.

    Guidelines:
    - Maintain a friendly and professional tone throughout the conversation.
    - Be patient and attentive to the customer's needs.
    - If unsure about any information, politely ask the customer to repeat or clarify.
    - Avoid discussing topics unrelated to the company's products or services.
    - Aim to provide concise answers. Limit responses to a couple of sentences and let the user guide you on where to provide more detail.
`;

const agent = await elevenlabs.conversationalAi.agents.create({
    name: "My voice agent",
    tags: ["test"], // List of tags to help classify and filter the agent
    conversationConfig: {
        tts: {
            voiceId: "aMSt68OGf4xUZAnLpTU8",
            modelId: "eleven_flash_v2",
        },
        agent: {
            firstMessage: "Hi, this is Rachel from [Your Company Name] support. How can I help you today?",
            prompt: {
                prompt,
            }
        },
    },
});

console.log(`Agent created with ID: ${agent.agentId}`);
```

> **Note**
>
> O agente criado acima terá a tag `"test"`, que é útil para classificar e filtrar o agente. Por exemplo, para diferenciar agentes de teste de agentes de produção.

#### Execute o código

```python
python create_agent.py
```

```typescript
npx tsx createAgent.mts
```

Isso gerará um agente com algumas configurações básicas e imprimirá o ID do agente no console. Personalizaremos o agente em uma etapa posterior.

#### Teste o agente

O agente recém-criado pode ser testado de várias formas, mas a maneira mais rápida é usar o [painel da ElevenLabs](https://elevenlabs.io/app/agents). No painel, selecione seu agente e clique no botão **Test AI agent**.

> **Info**
>
> O painel web usa nosso [SDK React](/docs/pt/eleven-agents/libraries/react) internamente para lidar com conversas em tempo real.

Se preferir testar rapidamente o agente no seu próprio site, você pode usar o widget de Agente. Basta colar o snippet HTML a seguir no seu site, substituindo `agent-id` pelo ID do seu agente.

```html
<elevenlabs-convai agent-id="agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>
```

Consulte a aba SDKs para saber como incorporar o agente ao seu site ou app usando os SDKs disponíveis.

## Próximas etapas

Como continuação deste guia de início rápido, você pode tornar seu agente mais eficaz integrando:

* [Bases de conhecimento](/docs/pt/eleven-agents/customization/knowledge-base) para equipá-lo com informações específicas do domínio.
* [Ferramentas](/docs/pt/eleven-agents/customization/tools) para permitir que ele execute tarefas em seu nome.
* [Autenticação](/docs/pt/eleven-agents/customization/authentication) para restringir o acesso a determinadas conversas.
* [Avaliação de sucesso](/docs/pt/eleven-agents/customization/agent-analysis/success-evaluation) para analisar conversas e melhorar o desempenho.
* [Coleta de dados](/docs/pt/eleven-agents/customization/agent-analysis/data-collection) para coletar dados sobre conversas e melhorar o desempenho.
* [Retenção de conversas](/docs/pt/eleven-agents/customization/privacy/retention) para ver o histórico de conversas e melhorar o desempenho.