Ú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
.
Configuração do projeto
Para criar ferramentas, seuhsproject.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órioworkflow-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.
Campo | Tipo | Descrição |
---|---|---|
uid * | String | Um identificador exclusivo interno para a ação de fluxo de trabalho. |
type * | String | O tipo de componente, que deve ser workflow-action neste caso. |
actionUrl * | String | O 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 * | String | A categoria de funcionalidade da ferramenta. As opções são:
|
llmDescription * | String | Uma descrição que ajuda o LLM a entender o que a ferramenta faz. |
isPublished | Booleano | Determina se a definição está visível nas contas que instalaram seu aplicativo. Isso é definido por padrão como false . |
supportedClients * | Matriz | Uma 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:
|
inputFields | Matriz | Os valores para as entradas que o usuário preencheu. Saiba mais sobre as práticas recomendadas de quantidade de campo. |
typeDefinition.name | String | O nome ou a chave do campo de entrada. |
typeDefinition.type | String | O tipo de valor esperado para o campo de entrada. |
typeDefinition.fieldType | String | O tipo de campo que aparece para os usuários que criam o fluxo de trabalho. |
typeDefinition.options | Matriz | Para 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. |
inputFieldDependencies | Matriz | Uma lista de regras que definem os relacionamentos entre duas ou mais entradas, com base em dependencyType . Saiba mais neste exemplo. |
labels.<locale> * | String | Chave 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>.inputFieldDescriptions | Objeto | Um 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>.inputFieldOptionLabels | Objeto | Um 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>.outputFieldLabels | Objeto | Um objeto que mapeia as definições de outputFields aos rótulos correspondentes mostrados na ferramenta de fluxos de trabalho. |
labels.<locale>.actionName * | String | O nome da ação, conforme mostrado no painel Escolha uma ação no editor de fluxo de trabalho. |
labels.<locale>.appDisplayName * | String | O 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>.actionCardContent | String | Uma descrição resumida exibida no cartão de ação. |
labels.<locale>.executionRules | Objeto | Um 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. |
objectTypes | Matriz | Os 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. |
outputFields | Matriz | Os 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. |
executionRules | Objeto | Uma 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.
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 deactionName
, 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')"
- 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 dePOST
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.