Última modificação: 11 de setembro de 2025
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.
├──src
   ├── hsproject.json
   ├── app/
   └── app-hsmeta.json
   └── ...
   └── workflow-actions/
     └── agent-tool-action-hsmeta.json
└──

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.
{
  "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": true
      },
      {
        "typeDefinition": {
          "name": "priority",
          "type": "enumeration",
          "fieldType": "select",
          "options": [
            {
              "value": "high",
              "label": "High Priority"
            },
            {
              "value": "normal",
              "label": "Normal Priority"
            },
            {
              "value": "low",
              "label": "Low Priority"
            }
          ]
        },
        "supportedValueTypes": ["STATIC_VALUE"],
        "isRequired": true
      }
    ],
    "labels": {
      "en": {
        "actionName": "My custom agent tool",
        "actionDescription": "A description of the tool.",
        "actionCardContent": "Send {{priority}} priority notification",
        "inputFieldLabels": {
          "message": "Notification Message",
          "priority": "Priority Level"
        },
        "inputFieldDescriptions": {
          "message": "Enter the message to be sent in the notification",
          "priority": "Select the priority level for this notification"
        }
      }
    },
    "objectTypes": ["CONTACT"]
  }
}

Campos marcados com * são obrigatórios.

CampoTipoDescrição
uid*StringUm identificador exclusivo interno para a ação de fluxo de trabalho.
type*StringO tipo de componente, que deve ser workflow-action neste caso.
actionUrl*StringO URL em que a ferramenta solicitará POST. O URL deve ser um ponto de extremidade com acesso público e não pode ser uma função sem servidor definida no projeto do desenvolvedor.
toolType*StringA categoria de funcionalidade da ferramenta. As opções são:
  • GET_DATA: recupera informações da HubSpot ou de fontes externas.
  • GENERATE: gera conteúdo, resumos, análises ou sugestões com base nas entradas fornecidas.
  • TAKE_ACTION: realiza ações de CRM, como criação de notas ou atribuições de tarefas aos proprietários.
llmDescription*StringUma descrição que ajuda o LLM a entender o que a ferramenta faz.
isPublishedBooleanoDetermina se a definição está visível nas contas que instalaram seu aplicativo. Isso é definido por padrão como false.
supportedClients*MatrizUma matriz de objetos que especifica quais clientes a ação de fluxo de trabalho personalizada aceita. Cada objeto na matriz deve ter uma chave client com um valor de string que indica o tipo de cliente. Os valores incluem:
  • WORKFLOWS: habilita a ação para fluxos de trabalho.
  • AGENTS: habilita a ação para agentes.
inputFieldsMatrizOs valores para as entradas que o usuário preencheu. Saiba mais sobre as práticas recomendadas de quantidade de campo.
typeDefinition.nameStringO nome ou a chave do campo de entrada.
typeDefinition.typeStringO tipo de valor esperado para o campo de entrada.
typeDefinition.fieldTypeStringO tipo de campo que aparece para os usuários que criam o fluxo de trabalho.
typeDefinition.optionsMatrizPara tipos de enumeração, este campo fornece uma lista de opções. Cada opção deve ter um value, com base nos dados fornecidos pelo usuário, e um label, que identifica a opção na ferramenta de fluxos de trabalho.
inputFieldDependenciesMatrizUma lista de regras que definem os relacionamentos entre duas ou mais entradas, com base em dependencyType. Saiba mais neste exemplo.
labels.<locale>*StringChave de local que mapeia à definição do local. No mínimo, um rótulo em inglês (en) e sua definição devem ser incluídos.
labels.<locale>.inputFieldDescriptionsObjetoUm objeto que define os detalhes para as entradas da sua ação. No exemplo acima, este objeto inclui os campos message e priority.
labels.<locale>.inputFieldOptionLabelsObjetoUm objeto obrigatório se seus campos de entrada tiverem opções. Fornece um mapa de rótulos de opções de campo de entrada, indexado pelo valor ou rótulo da opção.
labels.<locale>.outputFieldLabelsObjetoUm objeto que mapeia as definições de outputFields aos rótulos correspondentes mostrados na ferramenta de fluxos de trabalho.
labels.<locale>.actionName*StringO nome da ação, conforme mostrado no painel Escolha uma ação no editor de fluxo de trabalho.
labels.<locale>.appDisplayName*StringO nome da seção no painel Escolher uma ação, em que todas as ações do aplicativo são exibidas. Se appDisplayName for definido para várias ações, a primeira ação encontrada será usada.
labels.<locale>.actionCardContentStringUma descrição resumida exibida no cartão de ação.
labels.<locale>.executionRulesObjetoUm objeto que mapeia as definições do seu executionRules às mensagens que serão exibidas para resultados de execução no histórico do fluxo de trabalho.
objectTypesMatrizOs tipos de objeto do CRM disponíveis com os quais esta ação pode ser usada. Se estiver vazio, a ação estará disponível para todos os tipos de objeto.
outputFieldsMatrizOs valores que a ação enviará e que poderão ser usados por ações posteriores no agente ou no fluxo de trabalho. Uma ação personalizada pode ter 0, 1 ou muitas saídas.
executionRulesObjetoUma lista de definições que você pode especificar para revelar erros do seu serviço ao usuário que cria o fluxo de trabalho.

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.