- Adicionar um componente de ação de fluxo de trabalho a um aplicativo incluindo um diretório
workflow-actionsno projeto, juntamente com um arquivo de configuração de*-hsmeta.jsonpara 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.
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.
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.
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.