Skip to main content
Os agentes da HubSpot são assistentes com inteligência artificial com os quais os usuários podem conversar para executar tarefas. Cada agente inclui uma série de ações, chamadas ferramentas, que são usadas de acordo com as instruções do usuário. Como desenvolvedor, você pode criar ferramentas de agente personalizadas para executar tarefas específicas e bem definidas, dependendo do caso de uso pretendido do agente. Em segundo plano, as ferramentas são ações personalizadas de fluxo de trabalho configuradas para estarem disponíveis no contexto do agente. As ferramentas podem ser usadas em vários agentes e configuradas para funcionar em agentes e fluxos de trabalho. De forma geral, a criação de uma ferramenta de agente consiste em:
  • Adicionar um componente de ação de fluxo de trabalho a um aplicativo incluindo um diretório workflow-actions no projeto, juntamente com um arquivo de configuração de *-hsmeta.json para a ferramenta. Cada ferramenta e ação de fluxo de trabalho que forem criadas deverão ter seu próprio arquivo de configuração de *-hsmeta.json.
  • Configurar a ação que será disponibilizada nos agentes de IA através do campo supportedClients.
Ao desenvolver suas ferramentas, você também deve considerar conjunto de melhores práticas para garantir um melhor desempenho.

Configuração do projeto

Para criar ferramentas, seu hsproject.json deve ter platformVersion definido como 2025.2. Essa versão é definida automaticamente em todos os modelos de início rápido, mas precisará ser atualizada manualmente para projetos em versões mais antigas. Observe que, ao atualizar um projeto para a versão 2025.2, você precisará respeitar os novos padrões de arquivo de configuração *-hsmeta.json para sua configuração de aplicativo e seus recursos. Ferramentas de agente e ações de fluxo de trabalho personalizadas estão contidas no diretório workflow-actions do aplicativo.

Definição de ferramenta de agente

O arquivo de configuração das suas ferramentas deve ser colocado no diretório workflow-actions para poder funcionar. As opções de configuração para ferramentas de agente são as mesmas que as ações de fluxo de trabalho personalizadas, com a exigência adicional de que o campo supportedClients deve incluir o cliente AGENTS.

Campos marcados com * são obrigatórios.

Práticas recomendadas

Ao criar ferramentas de agente, leve em consideração a seguinte lista de verificação de práticas recomendadas:
  • Inicie com campos opcionais e defina como obrigatório somente quando estiver estável.
  • Rotule e descreva campos para humanos e IA.
  • Primeiro, teste com menos instruções do agente para entender como a IA interpreta uma ferramenta.
  • Mantenha as ferramentas focadas e preste atenção na quantidade de campos.
  • Use as descrições de campo para controlar a criatividade do agente.
Saiba mais sobre cada prática recomendada nas seções abaixo.
Observação:Embora algumas das orientações a seguir contenham informações sobre como testar ferramentas de agentes, esses recursos de teste ainda estão em desenvolvimento. A documentação das ferramentas do agente será atualizada quando os métodos de teste estiverem disponíveis.

Desenvolver com campos opcionais

Não defina campos de ação (inputFields) durante o desenvolvimento ativo. Depois definir um campo como obrigatório e carregar o projeto, não será possível remover ou atualizar o campo. Você só deve definir um campo como obrigatório quando estiver confiante nos detalhes do campo, como name e type. O motivo dessa limitação é que a alteração dos campos obrigatórios quebraria os fluxos de trabalho ativos que incluíssem a ação.

Desenvolver para a compreensão humana e de IA

actionName, inputFields e labels devem comunicar claramente o seu uso e utilidade para os seres humanos e o agente. Esses campos, em especial, são usados pelo agente para saber quando chamar a ação e como transmitir dados para a ferramenta. Ao construir suas ferramentas, lembre-se de que LLMs podem precisar de descrições mais explícitas do que usuários humanos. Por exemplo, enquanto um ser humano pode entender intuitivamente um campo rotulado Date, um LLM pode preferir Event start date (YYYY-MM-DD). O ideal é criar ferramentas para que os agentes não precisem de instruções adicionais para usá-las. No entanto, há casos em que os detalhes de campo por si só podem não ser suficientes para o agente. Por exemplo, ele pode não entender a ordem pretendida de operações para executar ferramentas que dependem da saída de outras ferramentas (por exemplo, uma ferramenta “Enviar e-mail” pode depender da execução de uma ferramenta “Obter informações de contato”). Ao criar uma ferramenta, você deve testá-la no agente sem adicionar às instruções do agente para compreender melhor como ele interpreta a ferramenta. Ao testar, você poderá determinar se o mecanismo de raciocínio funciona corretamente sozinho ou se precisa de instruções adicionais.

Preste atenção ao número de campos de entrada

Os agentes podem lidar com um grande número de campos de entrada em cada ferramenta (máximo de 26 entradas exclusivas). No entanto, quanto mais campos de entrada uma ferramenta tiver, mais nítida será a necessidade de atribuir valores de actionName, inputField e label. As ferramentas são mais eficazes e confiáveis quando projetadas para tarefas específicas com um conjunto focado de parâmetros. Para operações complexas, considere se seria mais eficaz criar várias ferramentas mais simples em vez de uma com um número excessivo de entradas.
Observação:A HubSpot poderá restringir o número de entradas futuramente com base no feedback sobre a qualidade dos agentes que manipulam grandes números de entradas.

Controle de criatividade e improvisação de agentes

Em alguns cenários, talvez você queira que um agente seja criativo e improvisado. No entanto, pode haver situações em que você não queira improvisações. Experimente instruir o LLM sobre os nomes, rótulos e descrições dos campos de entrada. Se você precisar de orientação mais rigorosa, adicione instruções ao agente para definir expectativas claras. Por exemplo, você dá ao agente a tarefa de gerar um post do blog, com um dos campos sendo o título do post do blog. Dependendo de quanta improvisação você quer permitir ao agente, o campo pode ser rotulado de forma mais permissiva ou mais restritiva:
  • Permissivo: "Blog title"
  • Restritivo: "Blog title (must include the product name 'HubSpot CRM')"
Como outro exemplo, considere os seguintes rótulos de campo de entrada destinados a conteúdo de post de mídia social:
  • Permissivo: "Social post content"
  • Moderado: "Social post content (keep under 280 characters)"
  • Restritivo: "Social post content (must mention our Q4 sale, include #HubSpot, and stay under 280 characters)"

Verificação da origem da solicitação de ferramenta de agente

Quando um agente usa uma ferramenta para fazer uma solicitação, ele faz uma solicitação de POST para o actionUrl. A invocação da ferramenta do agente é autenticada pela validação do cabeçalho X-HubSpot-Signature enviado com a solicitação. Este é o mesmo sistema que o HubSpot usa para validar solicitações de webhook.
Observação:Você não deve criar campos de entrada para segredos ou chaves de API, pois isso não é seguro e não segue o padrão de autenticação pretendido, especialmente porque o LLM precisaria receber o segredo/chave de API em suas instruções ou de outra ferramenta.
Última modificação em 10 de fevereiro de 2026