Última modificação: 11 de setembro de 2025
No HubSpot, você pode criar um agente de IA que executará várias ações com base em suas instruções. Por exemplo, você pode criar um agente para lhe enviar um e-mail todas as manhãs com observações sobre as próximas reuniões do dia. Para executar tarefas, os agentes contam com ferramentas de agente. As ferramentas são como funções em uma linguagem de programação: elas têm parâmetros que você passa para a ferramenta, e a ferramenta retorna uma saída. As ferramentas no HubSpot são semelhantes ao conceito de ferramentas no MCP (Model Context Protocol). Uma ferramenta de agente empacota chamadas de API, etapas de LLM e outros contextos de suporte para permitir que a IA realize o trabalho. As ferramentas são projetadas para executar tarefas específicas e bem definidas, como consultar um banco de dados, executar operações CRUD (criar, ler, atualizar, excluir) ou usar IA generativa para resumir o conteúdo. Em termos de implementação, uma ferramenta de agente é uma versão aprimorada de uma ação de fluxo de trabalho personalizada, que você criará usando o framework de projetos de desenvolvedor do HubSpot. Este tutorial orientará você sobre como começar a criar uma ferramenta de agente.

​
Pré-requisitos

Antes de começar, você precisará:
  • Instale a versão beta mais recente da CLI da HubSpot executando npm i -g @hubspot/cli@next.
  • Crie uma conta de teste de desenvolvedor dentro da conta de desenvolvedor que optou pela versão beta.
  • Autentique a conta de teste com a CLI executando o comando hs auth no terminal.
1

Criar um projeto

Se você estiver começando do zero, precisará primeiro criar um novo projeto. Como alternativa, se quiser usar um projeto existente, poderá ignorar a próxima seção (é necessário ter um projeto versão 2025.2).Para criar um novo projeto:
  1. No terminal, execute o comando abaixo para criar um novo projeto a partir de um dos modelos básicos de início rápido.
hs project create --platform-version 2025.2
  1. Siga os prompts do terminal para configurar o nome e o local do projeto e, em seguida, selecione um modelo. Várias opções de modelo são fornecidas dependendo de como você planeja distribuir seu aplicativo. Para os fins deste tutorial, selecione o modelo Começar projeto com aplicativo do marketplace.
  2. O modelo do projeto será baixado para o diretório de trabalho, onde você poderá exibir seu conteúdo.
Este modelo de projeto inclui todos os arquivos necessários para carregar um projeto com um aplicativo que inclui alguns recursos de exemplo. Esses recursos incluem um cartão de aplicativo básico, um webhook e uma ação de fluxo de trabalho. Para os fins deste tutorial, esses componentes não são necessários, mas podem ser úteis revisá-los, caso você queira experimentá-los mais tarde.
2

Adicionar uma ferramenta de agente ao projeto

Nos bastidores, as ferramentas de agente são ações de fluxo de trabalho personalizadas que são configuradas especificamente para o contexto do agente. Para que um agente possa executar a ferramenta (semelhante a como um fluxo de trabalho executaria uma ação), será necessário ativar a ação para que ela esteja disponível nos agentes usando o campo supportedClients.
  • No diretório workflow-actions, crie um novo arquivo JSON para a configuração da ferramenta. O arquivo pode ter qualquer nome, mas deve terminar com -hsmeta.json (por exemplo, my-agent-tool-hsmeta.json).
  • Crie a configuração da ação usando a documentação de referência das ferramentas de agente. Certifique-se de incluir o cliente AGENTS no campo supportedClients como mostrado no código de exemplo abaixo.
{
  "uid": "agent_tool_action",
  "type": "workflow-action",
  "config": {
    "actionUrl": "https://example.com",
    "toolType": "GET_DATA",
    "llmDescription": "A description that helps the LLM understand what this tool does.",
    "isPublished": false,
    "supportedClients": [
      {
        "client": "AGENTS"
      },
      {
        "client": "WORKFLOWS"
      }
    ],
    "inputFields": [
      {
        "typeDefinition": {
          "name": "message",
          "type": "string",
          "fieldType": "textarea"
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": false
      }
    ],
    "labels": {
      "en": {
        "actionName": "My custom agent tool",
        "actionDescription": "A description of the tool.",
        "actionCardContent": "Send a notification",
        "inputFieldLabels": {
          "message": "Notification Message"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}
Ao compilar sua ferramenta, lembre-se do seguinte:
  • Ao desenvolver, você não deve definir os campos de entrada como obrigatórios, pois esses campos não podem ser atualizados nem removidos depois de carregados.
  • As solicitações para os pontos de extremidade públicos serão feitas como solicitações POST.
Quando estiver pronto para carregar em sua conta de teste, salve seus arquivos e execute hs project upload. Se você começou com um novo projeto, será solicitado a pressionar y para criar o projeto na conta.

​
Observação:

A HubSpot ainda está desenvolvendo ativamente recursos para habilitar o teste de ferramenta de agente. Esta página será atualizada com mais instruções assim que esses recursos de teste estiverem disponíveis.