> ## Documentation Index
> Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência de ferramentas do agente (BETA)

> Saiba como criar as ferramentas de agente, que são ações de fluxo de trabalho personalizadas que podem ser usadas pelo agentes de IA.

<style>
  {`
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    code {
      word-break:keep-all!important;
    }
    td code {
      text-wrap: wrap!important;
    }
    `}
</style>

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](#project-setup), 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](#agent-tool-definition) 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](#best-practices) 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](/apps/developer-platform/build-apps/create-an-app), 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](/apps/developer-platform/build-apps/app-configuration) e seus recursos.

Ferramentas de agente e ações de fluxo de trabalho personalizadas estão contidas no diretório `workflow-actions` do aplicativo.

```shell theme={null}
├──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](/apps/developer-platform/add-features/custom-workflow-actions#custom-workflow-action-definition), com a exigência adicional de que o campo `supportedClients` deve incluir o cliente `AGENTS`.

```json theme={null}
{
  "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"]
  }
}
```

<p className="table-key">
  Campos marcados com <span style={{ color: 'red' }}>\*</span> são obrigatórios.
</p>

| Campo                                                                 | Tipo     | Descrição                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid`<span style={{color:"red"}}>\*</span>                            | String   | Um identificador exclusivo interno para a ação de fluxo de trabalho.                                                                                                                                                                                                                                                                                                 |
| `type`<span style={{color:"red"}}>\*</span>                           | String   | O tipo de componente, que deve ser `workflow-action` neste caso.                                                                                                                                                                                                                                                                                                     |
| `actionUrl`<span style={{color:"red"}}>\*</span>                      | 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`<span style={{color:"red"}}>\*</span>                       | String   | A categoria de funcionalidade da ferramenta. As opções são: <ul><li>`GET_DATA`: recupera informações da HubSpot ou de fontes externas.</li><li>`GENERATE`: gera conteúdo, resumos, análises ou sugestões com base nas entradas fornecidas.</li><li>`TAKE_ACTION`: realiza ações de CRM, como criação de notas ou atribuições de tarefas aos proprietários.</li></ul> |
| `llmDescription`<span style={{color:"red"}}>\*</span>                 | 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`<span style={{color:"red"}}>\*</span>               | 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: <ul><li>`WORKFLOWS`: habilita a ação para fluxos de trabalho.</li><li>`AGENTS`: habilita a ação para agentes.</li></ul>             |
| `inputFields`                                                         | Matriz   | Os valores para as entradas que o usuário preencheu. Saiba mais sobre as [práticas recomendadas de quantidade de campo](#be-mindful-of-the-number-of-input-fields).                                                                                                                                                                                                  |
| `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](/api-reference/automation-actions-v4-v4/guide#example-%233) exemplo.                                                                                                                                                                |
| `labels.<locale>`<span style={{color:"red"}}>\*</span>                | 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`<span style={{color:"red"}}>\*</span>     | String   | O nome da ação, conforme mostrado no painel *Escolha uma ação* no editor de fluxo de trabalho.                                                                                                                                                                                                                                                                       |
| `labels.<locale>.appDisplayName`<span style={{color:"red"}}>\*</span> | 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.

Saiba mais sobre cada prática recomendada nas seções abaixo.

<Warning>
  **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.
</Warning>

### 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.

<Warning>
  **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.
</Warning>

### 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](/apps/legacy-apps/authentication/validating-requests#validate-the-v3-request-signature).

<Warning>
  **Observação:**

  Você <u>não</u> 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.
</Warning>