Referencia de las herramientas del agente (BETA)

Los agentes de HubSpot son asistentes de IA con los que los usuarios pueden chatear para realizar tareas. Cada agente incluye una serie de acciones, llamadas herramientas, que utilizará según las instrucciones del usuario. Como desarrollador, puedes crear herramientas de agente personalizadas para realizar tareas específicas y bien definidas en función del caso de uso previsto del agente. Entre bastidores, las herramientas son acciones de workflow personalizadas que se configuran para que estén disponibles en el contexto del agente. Las herramientas pueden utilizarse en varios agentes, y pueden configurarse para funcionar tanto en agentes como en workflows. A gran escala, crear una herramienta de agente consiste en:

Agregar un componente de acción de workflow a una aplicación incluyendo un directorio workflow-actions en el proyecto, junto con un archivo de configuración *-hsmeta.json para la herramienta. Cada herramienta y acción de workflow que crees debe tener su propio archivo de configuración *-hsmeta.json.
Configurar la acción para que esté disponible en los agentes de IA a través del campo supportedClients.

Al crear tus herramientas, también debes tener en cuenta una serie de prácticas recomendadas para garantizar un rendimiento de mayor calidad.

Configuración del proyecto

Para construir herramientas, tu hsproject.json debe tener su platformVersion ajustado a 2025.2. Esta versión se establece automáticamente en todas las plantillas de inicio rápido, pero deberá actualizarse manualmente en los proyectos de versiones anteriores. Ten en cuenta que, al actualizar un proyecto a la versión 2025.2, tendrás que adherirte a las nuevas normas del archivo de configuración *-hsmeta.json para la configuración de tu aplicación y sus funciones. Tanto las herramientas de agente como las acciones de workflow personalizadas se encuentran en el directorio workflow-actions de la aplicación.

├──src
│   ├── hsproject.json
│   ├── app/
│   │   └── app-hsmeta.json
│   │   └── ...
│   │   └── workflow-actions/
│   │     └── agent-tool-action-hsmeta.json
└──

Definición de las herramienta de agente

El archivo de configuración de tus herramientas debe estar en el directorio workflow-actions para que funcione. Las opciones de configuración para las herramientas de agente son las mismas que las acciones de workflow personalizadas, con el requisito añadido de que el campo supportedClients debe incluir el 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"]
  }
}

Los campos marcados con * son obligatorios

Campo	Tipo	Descripción
`uid`*	Cadena	Un identificador único interno para la acción de workflow.
`type`*	Cadena	El tipo de componente, que en este caso debe ser `workflow-action`.
`actionUrl`*	Cadena	La URL a la que la herramienta hará una solicitud de `POST`. La URL debe ser un endpoint de acceso público y no puede ser una función sin servidor definida dentro del proyecto del desarrollador.
`toolType`*	Cadena	La categoría de funcionalidad de la herramienta. Puede ser una de las siguientes: `GET_DATA`: recupera información de HubSpot o de fuentes externas. `GENERATE`: genera contenido, resúmenes, análisis o sugerencias basadas en las entradas proporcionadas. `TAKE_ACTION`: realiza acciones de CRM, como crear notas o asignar tareas a los propietarios.
`llmDescription`*	Cadena	Una descripción que ayude al LLM a entender lo que hace la herramienta.
`isPublished`	Booleano	Determina si la definición es visible en las cuentas que instalaron tu aplicación. Por defecto, está configurado como `false`.
`supportedClients`*	Matriz	Matriz de objetos que especifica los clientes a los que da asistencia la acción de workflow personalizada. Cada objeto de la matriz debe tener una clave `client` con un valor de cadena que indique el tipo de cliente. Los valores incluyen: `WORKFLOWS`: activa la acción para los workflows. `AGENTS`: activa la acción para los agentes.
`inputFields`	Matriz	Los valores de las entradas que el usuario ha rellenado. Más información sobre las prácticas recomendadas de cantidad de campo.
`typeDefinition.name`	Cadena	El nombre o clave del campo de entrada.
`typeDefinition.type`	Cadena	El tipo de valor que debe esperar el campo de entrada.
`typeDefinition.fieldType`	Cadena	El tipo de campo que aparece a los usuarios que crean el workflow.
`typeDefinition.options`	Matriz	Para los tipos de enumeración, este campo proporciona una lista de opciones. Cada opción debe tener un `value`, basado en la entrada que proporciona el usuario, y un `label`, que identifica la opción en la herramienta workflows.
`inputFieldDependencies`	Matriz	Una lista de reglas que definen las relaciones entre dos o más entradas, basándose en su `dependencyType`. Más información en este ejemplo .
`labels.<locale>`*	Cadena	Clave de configuración regional que se asigna a la definición de configuración regional. Como mínimo, debe definirse una etiqueta en inglés (`en`) y su definición.
`labels.<locale>.inputFieldDescriptions`	Objeto	Un objeto que define los detalles de las entradas de tu acción. En el ejemplo de arriba, este objeto incluye los campos `message` y `priority`.
`labels.<locale>.inputFieldOptionLabels`	Objeto	Un objeto necesario si tus campos de entrada tienen opciones. Proporciona un mapa de las etiquetas de las opciones de los campos de entrada, codificadas por el valor o la etiqueta de la opción.
`labels.<locale>.outputFieldLabels`	Objeto	Objeto que asigna las definiciones de `outputFields` a las etiquetas correspondientes que aparecen en la herramienta de workflows.
`labels.<locale>.actionName`*	Cadena	El nombre de la acción tal y como se muestra en el panel Elegir una acción del editor de workflows.
`labels.<locale>.appDisplayName`*	Cadena	El nombre de la sección del panel Elegir una acción donde aparecen todas las acciones de la aplicación. Si se define `appDisplayName` para varias acciones, se utilizará la primera que se encuentre.
`labels.<locale>.actionCardContent`	Cadena	Una descripción resumida que aparece en la ficha de la acción.
`labels.<locale>.executionRules`	Objeto	Un objeto que asigna las definiciones de tus `executionRules` a los mensajes que aparecerán para los resultados de la ejecución en el historial del workflow.
`objectTypes`	Matriz	Los tipos de objetos del CRM disponibles con los que se puede utilizar esta acción. Si está vacía, la acción estará disponible para todos los tipos de objetos.
`outputFields`	Matriz	Los valores que se mostrarán en la acción y que pueden ser utilizados por acciones posteriores del agente o workflow. Una acción personalizada puede tener 0, 1 o muchas salidas.
`executionRules`	Objeto	Una lista de definiciones que puedes especificar para mostrar los errores de tu servicio al usuario que crea el workflow.

Prácticas recomendadas

Cuando construyas herramientas de agentes, ten en cuenta la siguiente lista de comprobación de prácticas recomendadas:

Empieza con campos opcionales, y luego ponlos como obligatorios solo cuando sean estables.
Etiqueta y describe los campos tanto para los humanos como para la IA.
Prueba con menos instrucciones de agente al principio para entender cómo interpreta la IA una herramienta.
Mantén las herramientas centradas y ten en cuenta la cantidad de campo.
Utiliza las descripciones de los campos para controlar la creatividad de los agentes.

Más información sobre cada una de las prácticas recomendadas en las secciones de abajo.

Nota:Aunque algunas de las orientaciones que aparecen abajo incluyen información sobre las herramientas de comprobación de los agentes, estas funciones de comprobación están aún en fase de desarrollo. La documentación de las herramientas del agente se actualizará cuando estén disponibles los métodos de prueba.

Desarrollar con campos opcionales

No establezcas campos de acción (inputFields) como obligatorios durante el desarrollo activo. Una vez que un campo se ha establecido como obligatorio y se ha subido el proyecto, no puedes eliminar ni actualizar el campo. Solo debes establecer un campo como obligatorio cuando estés seguro de los detalles del campo, como su name y type. La razón de esta limitación es que cambiar los campos obligatorios rompería cualquier workflow activo que incluya la acción.

Construir para la comprensión humana y de la IA

actionName, inputFields y labels deben comunicar claramente su uso y utilidad tanto a los humanos como al agente. Estos campos en concreto los utiliza el agente para saber cuándo invocar la acción y cómo pasar los datos a la herramienta. Cuando construyas tus herramientas, ten en cuenta que los LLM pueden necesitar descripciones más explícitas que los usuarios humanos. Por ejemplo, mientras que un humano podría entender intuitivamente un campo etiquetado Date, un LLM podría preferir Event start date (YYYY-MM-DD). Lo ideal es que las herramientas se construyan de forma que los agentes no necesiten instrucciones adicionales para utilizarlas. Sin embargo, hay casos en los que los datos de campo por sí solos pueden no ser suficientes para el agente. Por ejemplo, puede que no comprenda el orden previsto de las operaciones para ejecutar herramientas que dependen de la salida de otras herramientas (por ejemplo, una herramienta “Enviar correo electrónico” puede depender de que primero se ejecute una herramienta “Obtener información de contacto”). Cuando construyas una herramienta, deberías probarla primero en el agente sin agregarle instrucciones, para entender mejor cómo interpreta la herramienta. Mediante las pruebas, podrás determinar si el motor de razonamiento funciona correctamente por sí solo o si necesita instrucciones adicionales.

Ten en cuenta el número de campos de entrada

Los agentes pueden manejar un elevado número de campos de entrada en cada herramienta (máximo 26 entradas únicas). Sin embargo, cuantos más campos de entrada haya en una herramienta, más claro deberás ser a la hora de asignar los valores actionName, inputField y label. Las herramientas son más eficaces y fiables cuando se diseñan para tareas específicas con un conjunto de parámetros bien definidos. Para operaciones complejas, plantéate si sería más eficaz crear varias herramientas más sencillas que una única herramienta con un número excesivo de entradas.

Nota:Es posible que HubSpot restrinja el número de entradas en el futuro basándose en los comentarios sobre la calidad de los agentes que manejan un gran número de entradas.

Creatividad e improvisación del agente de control

En algunos casos, puede que quieras que un agente sea creativo e improvisador. Sin embargo, puede haber situaciones en las que no quieras que el agente improvise. Experimenta dando instrucciones al LLM en los nombres, etiquetas y descripciones de tus campos de entrada. Si necesitas una orientación más estricta, agrega instrucciones al agente para establecer expectativas claras. Por ejemplo, supongamos que encomiendas a un agente la tarea de generar una publicación de blog, siendo uno de los campos el título de la entrada. Dependiendo de cuánto quieras que improvise el agente, podrías etiquetar el campo de forma permisiva o más restrictiva:

Permisivo: "Blog title"
Restrictivo: "Blog title (must include the product name 'HubSpot CRM')"

Como otro ejemplo, considera las siguientes etiquetas de campo de entrada destinadas al contenido de publicaciones en redes sociales:

Permisivo: "Social post content"
Moderado: "Social post content (keep under 280 characters)"
Restrictivo: "Social post content (must mention our Q4 sale, include #HubSpot, and stay under 280 characters)"

Verificar el origen de la solicitud de la herramienta de agente

Cuando un agente utiliza una herramienta para hacer una solicitud, realiza una solicitud de POST a la actionUrl de la herramienta. La invocación de la herramienta de agente se autentica validando el título X-HubSpot-Signature enviado con la solicitud. Es el mismo sistema que utiliza HubSpot para validar las solicitudes de webhook.

Nota:No deberías crear campos de entrada para secretos o claves de API, ya que esto es inseguro y no es el patrón de autenticación previsto, especialmente porque el LLM necesitaría recibir el secreto/clave de API en sus instrucciones o recibirlo de otra herramienta.

Crear aplicaciones

Agregar funciones

Publicar en el mercado de HubSpot

Referencia de las herramientas del agente (BETA)

Configuración del proyecto

Definición de las herramienta de agente

Prácticas recomendadas

Desarrollar con campos opcionales

Construir para la comprensión humana y de la IA

Ten en cuenta el número de campos de entrada

Creatividad e improvisación del agente de control

Verificar el origen de la solicitud de la herramienta de agente

​Configuración del proyecto

​Definición de las herramienta de agente

​Prácticas recomendadas

​Desarrollar con campos opcionales

​Construir para la comprensión humana y de la IA

​Ten en cuenta el número de campos de entrada

​Creatividad e improvisación del agente de control

​Verificar el origen de la solicitud de la herramienta de agente

Configuración del proyecto

Definición de las herramienta de agente

Prácticas recomendadas

Desarrollar con campos opcionales

Construir para la comprensión humana y de la IA

Ten en cuenta el número de campos de entrada

Creatividad e improvisación del agente de control

Verificar el origen de la solicitud de la herramienta de agente