Criar e configurar um agent

O agent é o robô de atendimento. Criar o agent é rápido; o passo que costuma ser esquecido — e que faz o robô ficar mudo — é o das credenciais do Claude.

Criar o agent

Abra a organização

No painel, clique em Organizations e escolha a organização do cliente. Se ela ainda não existe, crie primeiro.

Crie o agent

Dentro da organização, use a opção de criar agent. Na primeira etapa (1. Agent setup) você preenche:

Name — o nome do agent (ex.: Atendimento Vendas).
Import agent profile — opcional. Se já existir um modelo pronto, ele copia a personalidade para você editar. Deixe em Start from scratch para começar do zero.

Ao salvar, a plataforma provisiona sozinha a inteligência daquele agent. Nenhum token passa pelo seu navegador.

Escreva a personalidade

Na seção Profile do agent você define como ele se comporta. São três campos de texto livre (em Markdown):

Soul / personalidade — quem ele é, como fala, o que pode e o que não pode fazer.
Learned adjustments — ajustes que o próprio agent registra ao longo do tempo.
User context — contexto sobre o cliente/usuário que ele atende.

Escreva a personalidade em português, com frases diretas. Exemplo de trecho:


# Personalidade
 
Você é o atendente da Oficina do João. Fala de forma simpática e objetiva,
sempre em português. Nunca promete prazo sem confirmar com um humano.

Credenciais do Claude — o passo obrigatório

Sem as credenciais do Claude, o agent não responde. O container dele sobe normal, o painel mostra tudo verde, mas toda tentativa de resposta falha em silêncio. Foi exatamente isso que aconteceu em produção: o robô ficou mudo e ninguém entendeu por quê.

São duas informações:

Variável	O que é
`CLAUDE_CODE_OAUTH_TOKEN`	O token de acesso ao Claude. É um segredo.
`CLAUDE_CODE_MODEL`	Qual modelo o agent usa.

Como o painel avisa

Quando faltam credenciais, o painel mostra, em qualquer aba do agent, um aviso vermelho:

Credenciais do Claude não configuradas — Este agent ainda não tem as credenciais do Claude (token e modelo). Sem elas, ele não consegue responder mensagens — toda tentativa de resposta falha em silêncio, mesmo com o agent no ar.

Na lista de agents da organização, o mesmo agent aparece com a etiqueta Sem credenciais. O aviso some sozinho assim que o token é gravado.

Onde as credenciais ficam gravadas

Elas moram na seção Environment do agent — é para lá que o link do aviso (“Configurar em Environment”) leva.

Hoje o formulário da seção Environment mostra apenas os campos do Telegram. As credenciais do Claude ainda não têm campo próprio na tela: elas são gravadas pela API. Isso está registrado como pendência conhecida — o aviso do painel serve para apontar o problema, não para resolvê-lo sozinho.

Gravando pela API

Peça a quem cuida da infraestrutura para rodar o comando abaixo, trocando os valores entre <> pelos reais. Nunca cole um token de verdade em conversa, ticket ou documento:


curl -X PATCH "$GATEWAY_URL/orgs/<ID_DA_ORG>/agents/<ID_DO_AGENT>/envs" \
  -H "Authorization: Bearer <SUA_CHAVE_DO_GATEWAY>" \
  -H "Content-Type: application/json" \
  -d '{
    "envs": [
      { "key": "CLAUDE_CODE_OAUTH_TOKEN", "value": "<TOKEN_DO_CLAUDE>" },
      { "key": "CLAUDE_CODE_MODEL", "value": "<NOME_DO_MODELO>" }
    ]
  }'

Depois de gravar, recarregue a página do agent: o aviso vermelho deve desaparecer.

Os valores gravados nunca voltam nas respostas da plataforma. O painel só sabe dizer se estão configurados ou não — nunca mostra o token. Se você perdeu o token, não há como recuperá-lo pela plataforma: gere um novo.

Onde ficam as outras configurações

Quero…	Vá em
Conectar o WhatsApp	Integrations — veja oficial ou não oficial
Fazer as mensagens chegarem neste agent	Inbound channels
Mandar as conversas para outro sistema	Webhooks — veja Webhooks de saída
Entrar no painel técnico do próprio agent	Dashboard access

Problemas comuns

Sintoma	Causa provável	O que fazer
O agent não responde nada, mas está “no ar”	Credenciais do Claude ausentes	Procure o aviso vermelho na página do agent e grave o token e o modelo
Aviso vermelho continua depois de gravar	O valor gravado ficou vazio	Grave de novo com um valor não vazio — string vazia conta como “não configurado”
Erro ao salvar a personalidade	Falha de comunicação com a plataforma	A mensagem aparece dentro do próprio card, em português; tente de novo em alguns instantes
O agent responde, mas fora do personagem	Personalidade genérica demais	Reescreva o campo de personalidade com regras concretas do negócio