Fontes de ferramentas (MCP)

Uma fonte de ferramentas é um serviço externo que a plataforma conecta ao seu agente para ampliar o que ele consegue fazer: buscar na web, consultar um sistema interno, ler documentos, criar registros. Cada fonte fala o padrão aberto MCP (Model Context Protocol) e expõe uma ou mais ferramentas, que o agente aciona durante a conversa.

Esta página explica como uma fonte de ferramentas é configurada, como o agente faz referência às ferramentas dela e — o ponto principal — como a plataforma se autentica na fonte para usá-la em seu nome.

Como o agente usa uma ferramenta

Cada especialista lista, no campo tools, as ferramentas que pode acionar, no formato fonte.ferramenta:

tools:
  - tavily.tavily_search
  - tavily.tavily_extract

• fonte é o nome da fonte de ferramentas conectada à plataforma (aqui, tavily).
• ferramenta é a capacidade específica que aquela fonte expõe (aqui, tavily_search).

Só listar a ferramenta não garante que o agente a use no momento certo — descreva no prompt quando e como acioná-la. Veja a configuração do especialista para o campo tools no contexto do arquivo completo.

Anatomia de uma fonte de ferramentas

Uma fonte é definida por poucos atributos:

Atributo	Obrigatório	Descrição
Nome	✅	Identificador da fonte. É o prefixo usado em tools (nome.ferramenta). Use apenas letras, números, - e _ — sem ponto.
Endereço	✅	O endereço (URL https://) onde a fonte MCP responde.
Autenticação	—	Como a plataforma se autentica na fonte. Padrão: nenhuma. Veja abaixo.
Acesso anônimo	—	Se a fonte pode ser usada em conversas anônimas (sem usuário identificado). Padrão: não.

O catálogo de ferramentas (quais ferramentas existem e o que cada uma recebe) é descoberto automaticamente a partir da fonte — você não precisa declará-lo. Se a fonte estiver fora do ar quando o agente tentar usá-la, a chamada da ferramenta falha; a conversa continua e o agente segue com o que tem.

Modos de autenticação

A maioria das fontes exige credencial. A plataforma oferece quatro modos — escolha conforme de quem é a credencial e como ela chega até a fonte.

Credencial gerenciada pela plataforma

Uma credencial única, guardada pela plataforma e compartilhada por todas as conversas. É o modo mais simples: todos os usuários acessam a fonte com a mesma identidade de aplicação.

Usado em fontes de alcance geral, mantidas centralmente pela plataforma (por exemplo, uma busca na web comum a todos os agentes). Fontes específicas da sua organização não usam este modo — para elas, use uma das opções abaixo.

Sua própria chave

A plataforma usa uma chave de API sua para acessar a fonte. Você fornece a chave uma vez por um canal seguro; a partir daí, as chamadas àquela fonte usam essa credencial.

Use quando a fonte é um serviço em que você tem conta e cobrança próprias (sua conta de busca, seu provedor de dados) e quer que o consumo corra por ela.

Conectar sua conta (OAuth)

A fonte pede que cada usuário autorize o acesso à própria conta, no mesmo modelo dos "conectores": na primeira vez que o agente precisa da ferramenta, o usuário é levado à tela de login do provedor, concede a autorização e a plataforma passa a agir em nome dele.

A autorização é por usuário: dois usuários da mesma organização podem estar conectados a contas diferentes do mesmo serviço (por exemplo, espaços de trabalho distintos), cada um com seu próprio acesso.

Depois de conectada, a autorização é renovada automaticamente enquanto continuar válida. Se ela expirar ou for revogada no provedor, o agente pede a reconexão da mesma forma — basta autorizar de novo.

Identidade do usuário da conversa

A plataforma repassa à fonte a própria credencial do usuário que está na conversa. Serve quando a fonte é um serviço que já conhece esse usuário e deve aplicar exatamente as permissões dele.

Diferente de "conectar sua conta", aqui não há uma tela de autorização separada: a identidade que já autentica a conversa é reaproveitada na chamada à ferramenta.

Sem autenticação

Fontes públicas podem dispensar credencial. Nesse caso, nenhuma identidade é enviada.

Resumo

Modo	De quem é a credencial	Quando usar
Gerenciada pela plataforma	Da plataforma, compartilhada	Fontes gerais mantidas centralmente.
Sua própria chave	Sua (uma chave, por organização)	Serviço com sua conta e cobrança próprias.
Conectar sua conta (OAuth)	De cada usuário (login no provedor)	Fonte que age na conta pessoal de cada usuário.
Identidade do usuário	Do usuário da conversa	Fonte que já conhece o usuário e aplica as permissões dele.
Sem autenticação	Nenhuma	Fontes públicas.

Credenciais são somente-escrita

Qualquer credencial que você fornece (uma chave própria, um segredo de OAuth) é somente-escrita: a plataforma a guarda de forma cifrada e nunca a devolve em telas ou respostas. Ao consultar uma fonte, você vê apenas o tipo de autenticação e se há uma credencial configurada — nunca o valor. Para trocar uma credencial, basta enviar a nova.

Acesso anônimo

Algumas conversas acontecem sem um usuário identificado (por exemplo, um agente público). Por padrão, uma fonte de ferramentas não é usada nessas conversas. Ative o acesso anônimo apenas em fontes seguras para uso sem identificação — em geral, as sem autenticação ou com credencial gerenciada pela plataforma. Modos que dependem da identidade do usuário (conectar sua conta, identidade do usuário) não funcionam em conversas anônimas, porque não há usuário para autorizar.

Exemplo completo

Um especialista de pesquisa que usa uma fonte de busca na web:

id: pesquisador-web
version: "1.0.0"
kind: specialist

model:
  default: default
  fallback: default

tools:
  - tavily.tavily_search
  - tavily.tavily_extract

prompt: |
  Você é um assistente de pesquisa. Quando a pergunta exigir informação atual,
  use `tavily_search` para buscar e `tavily_extract` para ler URLs específicas.
  Escreva uma resposta concisa e sempre cite as fontes (URLs).

installed_skills: []

cost_cap:
  per_conversation: 1.00

A fonte tavily é configurada uma vez (endereço + modo de autenticação) e fica disponível para qualquer especialista referenciá-la no campo tools.

Perguntas frequentes

O agente respondeu que precisa de autorização — o que fazer? A ferramenta usa o modo conectar sua conta e ainda não foi autorizada (ou a autorização expirou). Faça o login no provedor quando a plataforma oferecer, e o agente retoma de onde parou.

Adicionei uma ferramenta em tools e o agente não a usa. Verifique se o nome está no formato fonte.ferramenta e se o prompt orienta quando usá-la. Se a fonte referenciada não existir, aquela ferramenta é ignorada e a conversa segue sem ela.

Posso apontar uma fonte para um endereço interno? Não. O endereço precisa ser um https:// acessível publicamente; endereços de rede interna são recusados por segurança.