Entendendo as ferramentas e quando utilizá-las
Ferramentas (tools) são capacidades extras que o agente pode acionar de forma autônoma durante uma conversa. Em vez de apenas gerar texto com base no que sabe, o agente passa a poder interagir com sistemas externos — buscar um registro, inserir um lead, criar um evento, consultar um documento — tudo dentro do fluxo natural da conversa. A decisão de usar ou não uma ferramenta pertence ao próprio modelo de linguagem. Ao receber uma mensagem do usuário, o LLM avalia o contexto, identifica se alguma ação externa é necessária para responder bem e, em caso afirmativo, escolhe a ferramenta mais adequada. Esse mecanismo é o tool calling nativo dos grandes modelos — não exige lógica de roteamento manual nem fluxos condicionais programados por você. Ferramentas são indicadas quando a resposta ideal depende de informações que não estão no prompt e que mudam com frequência (preços, disponibilidade, histórico de um cliente), ou quando o agente precisa executar uma ação no mundo — registrar dados, agendar uma reunião, atualizar um status. Se a informação for estática e raramente mudar, basta incluí-la diretamente no prompt ou na base de conhecimento.Habilitar muitas ferramentas simultaneamente aumenta o espaço de raciocínio do modelo e pode elevar o custo por resposta. Prefira ativar apenas as ferramentas que o agente realmente precisa para o seu caso de uso específico.
Como o agente usa ferramentas
O agente não segue uma ordem fixa de chamadas. A cada turno da conversa, o modelo avalia o contexto acumulado e decide se precisa acionar alguma ferramenta. O ciclo é:- O modelo lê a mensagem do usuário e o histórico da conversa.
- Se identificar que precisa de dados externos ou precisa executar uma ação, seleciona a ferramenta mais adequada e monta os argumentos.
- A ferramenta é executada e o resultado retorna ao modelo.
- O modelo incorpora o resultado e gera a resposta ao usuário.
Tipos de ferramentas na Timely.ai
A Timely.ai oferece ferramentas de diferentes categorias, cada uma com um propósito específico:Requisição HTTP
Permite que o agente faça chamadas a APIs externas via HTTP. Você configura a URL, o método (GET, POST, PUT, PATCH, DELETE), os cabeçalhos e o corpo da requisição. O agente monta os parâmetros dinamicamente com base no contexto da conversa e injeta o retorno no contexto antes de responder.- Ideal para integrar sistemas que expõem uma API REST mas não têm suporte nativo na Timely.ai.
- Suporta autenticação via header (Bearer token, API key) configurada na definição da ferramenta.
Execução de código
Executa trechos de código gerados pelo próprio modelo em um ambiente isolado. Útil para cálculos complexos, transformações de dados e geração de relatórios dinâmicos que seriam difíceis de expressar apenas em linguagem natural.Busca na web
Permite que o agente pesquise informações atualizadas na internet durante uma conversa. O resultado da busca é incorporado ao contexto antes de o modelo formular a resposta — útil para perguntas sobre eventos recentes, preços de mercado ou qualquer dado que muda com frequência e não está na base de conhecimento.Busca na base de conhecimento
Aciona o mecanismo RAG da Timely.ai: a pergunta do usuário é convertida em um embedding vetorial (modelotext-embedding-3-small, 1.536 dimensões) e comparada com os chunks indexados na base de conhecimento do workspace. Os trechos mais relevantes são injetados no contexto antes da resposta.
Ferramentas de Datagrid
Conectam o agente às tabelas customizadas do workspace. As ações disponíveis são:semantic_search— busca por similaridade semântica nos registros da tabela.similarity_search— busca por correspondência aproximada de texto.insert_row— insere um novo registro com os campos informados pelo agente.update_row— atualiza um registro existente identificado pelorow_id.
Execução de workflow
Aciona um workflow interno da Timely.ai como parte da resposta do agente. O agente chama o workflow com os parâmetros definidos, aguarda a conclusão e usa o resultado na conversa.Follow-up
Agenda uma mensagem de acompanhamento para ser enviada ao usuário após um intervalo de tempo. O agente determina o conteúdo e o horário do follow-up com base no contexto da conversa — útil para lembretes, retomadas de contato e verificações pós-atendimento.Memória contextual
Permite que o agente persista informações sobre o contato entre conversas. O agente pode salvar preferências, histórico de interações ou qualquer dado relevante, e recuperar essas informações em sessões futuras sem que o usuário precise repetir o contexto.Leitura de PDF
Extrai e processa o conteúdo de documentos PDF enviados pelo usuário durante a conversa. O texto extraído é incorporado ao contexto para que o agente possa responder perguntas sobre o documento, resumir seu conteúdo ou executar ações baseadas nas informações presentes no arquivo.Integrações Composio
Conectam o agente a 29 apps externos através da camada de autenticação e execução da Composio — Google Calendar, Google Meet, Notion, Slack, Gmail, HubSpot, Stripe, GitHub, LinkedIn, Twitter/X, Meta Ads, Google Sheets, Browser Tool, Browse.ai e mais. Cada app expõe um conjunto de tools individuais que você pode ativar ou desativar na configuração do agente.MCP (Model Context Protocol)
Protocolo aberto da Anthropic que permite conectar o agente a qualquer servidor MCP externo — interno, de terceiros ou desenvolvido pelo seu time. Enquanto a Composio cobre apps populares com conectores prontos, o MCP permite expor ferramentas proprietárias (consultas a APIs internas, ERP, sistemas legados) sem depender de nenhum catálogo.Boas práticas
- Ative ferramentas de leitura antes de habilitar ferramentas de escrita e valide o comportamento no Playground.
- Escreva descrições claras para cada ferramenta — o modelo usa esse texto para decidir quando acioná-la.
- Ferramentas MCP e Composio injetam instruções de workflow no prompt do sistema, tornando o comportamento mais previsível.
- Monitore o consumo de tokens por sessão ao adicionar múltiplas ferramentas — cada ferramenta ativa aumenta o tamanho do contexto.