Última modificación: 11 de septiembre de 2025
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
.
Configuración del proyecto
Para construir herramientas, tuhsproject.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.
Definición de las herramienta de agente
El archivo de configuración de tus herramientas debe estar en el directorioworkflow-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
.
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:
|
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:
|
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.
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 valoresactionName
, 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')"
- 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 dePOST
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.