Configuración de herramientas
Qué significa “configurar herramientas”
Un agente de REDA AI es la suma de sus herramientas. Configurar el conjunto de herramientas de un agente implica tres decisiones:
- Qué herramientas integradas recibe el agente. Las 18 herramientas que vienen con la plataforma están enumeradas en la Referencia de herramientas integradas; asigna solo las que cada agente realmente necesita.
- Qué herramientas personalizadas creas para él. Cuando las integradas no cubren un caso de uso, crea una herramienta personalizada de uno de tres tipos: SOQL Template, Apex Class o File Mapping.
- Cómo se delimita el alcance de las herramientas. Cada herramienta puede restringirse a canales, agentes y objetos de contexto específicos para que la herramienta correcta aparezca en el contexto correcto.
Asignar herramientas a un agente
Las herramientas quedan disponibles para un agente cuando se le asignan de forma explícita. La plataforma nunca asigna herramientas automáticamente a un agente nuevo.
-
Abre el agente
Ve al agente que quieres configurar.
-
Abre el panel de Herramientas
La sección Herramientas enumera cada herramienta asignada actualmente a este agente, junto con sus categorías (Herramienta / Acción) y canales.
-
Agrega o quita herramientas
Busca las herramientas disponibles por nombre o categoría, marca las que quieras y guarda. Quitar una herramienta surte efecto en la siguiente conversación del agente.
-
Prueba en la Vista previa de ejecución
La vista previa de ejecución muestra el prompt ensamblado y la lista exacta de herramientas que verá el modelo. Confirma que el agente tenga ahora las herramientas que esperas.
Por gobernanza, la asignación es por agente. Dos agentes en el mismo canal pueden tener conjuntos de herramientas completamente distintos; la definición del agente es el límite.
Crear herramientas personalizadas — el Generador de herramientas
Para todo lo que las integradas no cubran, el Generador de herramientas te guía en la creación de una herramienta personalizada desde una sola pantalla. El generador prioriza el tipo — eliges qué clase de herramienta quieres y el formulario se adapta a esa elección.
Paso 1 — Elige un tipo de herramienta
En la parte superior del generador hay tres tarjetas de tipo:
| Tarjeta de tipo | Qué produce | Recurre a ella cuando… |
|---|---|---|
| Plantilla SOQL | Una herramienta de solo lectura respaldada por una consulta SOQL parametrizada. | Quieres exponer una consulta fija con parámetros con nombre — y nada más. |
| Apex Class | Una herramienta respaldada por tu propia clase Apex que implementa la interfaz de ejecución. | Necesitas lógica condicional, escrituras en varios objetos, llamadas externas o extracción estructurada de archivos. |
| File Mapping | Una herramienta declarativa de importación de CSV a Salesforce. | Quieres cargar CSV de forma masiva en un objeto de Salesforce usando un mapeo fijo. |
La tarjeta que elijas es determinante. Las demás secciones del generador se contraen y se reorganizan en torno al tipo, para que solo veas los campos que son relevantes.
Paso 2 — Bloqueo de categoría
Cada tipo de herramienta tiene una categoría predeterminada sensata, y el generador la aplica de forma visible:
| Tipo | Categoría | Por qué está bloqueada |
|---|---|---|
| SOQL Template | Tool (solo lectura) |
Las SOQL Template ejecutan consultas de solo SELECT y no pueden realizar DML. |
| File Mapping | Action |
Las herramientas File Mapping siempre escriben filas en Salesforce. |
| Apex Class | Tool o Action |
Las herramientas Apex Class pueden leer o escribir, así que la elección es tuya; el generador te pide que la declares de forma explícita. |
Cuando una categoría está bloqueada, el generador muestra un aviso de bloqueo que explica por qué — para que los administradores no pierdan tiempo intentando anular una restricción que, de todos modos, el tiempo de ejecución rechazaría.
Paso 3 — Configura los campos específicos del tipo
Cada tipo abre un conjunto distinto de bloques de configuración. El detalle vive en las páginas dedicadas:
- Herramientas de plantillas SOQL — plantilla de consulta, sintaxis de marcadores de posición, esquema de entrada generado automáticamente.
- Herramientas de clases Apex — nombre de la clase de ejecución, esquema de entrada, contrato de retorno, indicador de procesamiento de archivos.
- Herramientas de mapeo de archivos — objeto de destino, operación, mapeo de columna a campo, clave de coincidencia.
Paso 4 — Usa el Generador de IA
Para cada tipo, el generador ofrece un Generador de IA que produce una herramienta funcional a partir de una descripción breve y de cualquier entrada de referencia que proporciones:
- Para las herramientas SOQL Template, pega la consulta que quieras (o describe lo que necesitas) — el generador extrae los marcadores de posición y escribe el esquema de entrada con descripciones detalladas.
- Para las herramientas Apex Class, describe la operación, sube opcionalmente un archivo de muestra cuando la herramienta vaya a procesar documentos, y el generador produce el esquema de entrada y una muestra de los datos que recibirá tu ejecutor.
- Para las herramientas File Mapping, sube un CSV de muestra más una descripción de una línea; el generador propone el objeto de destino, la operación, el mapeo y la clave de coincidencia.
El resultado siempre se puede revisar — el generador completa el formulario, tú editas lo que no encaje y guardas cuando estés conforme.
Paso 5 — Observa el panel de impacto en vivo
A lo largo del generador, un panel de impacto muestra lo que el agente verá realmente en tiempo de ejecución:
- El nombre y la descripción de la herramienta tal como aparecerán ante el modelo
- El esquema de entrada con la forma JSON exacta que se envía en cada solicitud
- La categoría, el nivel y el alcance de canal que determinan cuándo se carga la herramienta
- Para las herramientas de Acción, una vista previa de la tarjeta de confirmación que verá el usuario
- Para las herramientas Apex Class con procesamiento de archivos, una muestra de la forma de los datos extraídos que recibirá tu ejecutor
Esta es la forma más rápida de detectar discrepancias entre lo que quieres y lo que verá el agente — antes de la primera conversación real.
Paso 6 — Guarda y asigna
Al guardar, la herramienta se implementa a través de la API de metadatos. El Generador de herramientas hace seguimiento de la implementación y te avisa cuando la herramienta está activa. Una vez implementada, asígnala a uno o más agentes desde el panel de Herramientas del agente. Las herramientas no son visibles de forma implícita para los agentes — la asignación siempre es explícita.
Delimitar el alcance de una herramienta
Cada definición de herramienta tiene campos de alcance que controlan dónde y cuándo aparece la herramienta:
| Campo | Propósito |
|---|---|
| Nombre del agente | Restringe la herramienta a un agente específico. Déjalo en blanco para que esté disponible para cualquier agente que la agregue. |
| Canales | Lista de selección múltiple de los canales en los que se permite la herramienta (Interno, Widget externo, Comunidad, API). La herramienta se oculta en cualquier canal no seleccionado, incluso si está asignada al agente. |
| Objetos de contexto | Nombres de API de objeto donde esta herramienta es más relevante. La plataforma los usa para ponderar la relevancia de la herramienta cuando el agente se ejecuta en una página de registro específica. |
| Nivel de herramienta | Obsoleto — el motor lo ignora. Todas las herramientas activas se cargan en cada turno como una lista estable en caché. Consulta Carga y costo de herramientas. |
| Requiere confirmación | En las herramientas de Acción, si el agente muestra una tarjeta de confirmación antes de ejecutarse. Está activado de forma predeterminada para las Acciones; normalmente conviene dejarlo activado. |
| Activo | Interruptor principal. Las herramientas inactivas se omiten por completo. |
Mantener el conjunto de herramientas ligero
Cada herramienta que tiene el agente cuesta tokens en cada solicitud — el modelo ve el nombre, la descripción y el esquema de entrada de la herramienta incluso cuando no la usa. La optimización proviene de tres hábitos:
Asigna según la necesidad. No asignes de más por si el agente pudiera necesitar una herramienta algún día. Agrega herramientas cuando una conversación real las necesite; quita las herramientas que no se han activado en semanas.
Ajusta los esquemas extensos. La definición de una herramienta se envía en cada turno, así que un esquema de entrada inflado es un impuesto por turno. Mantén las descripciones concisas y los campos al mínimo, y confirma con el Depurador de conversaciones qué vio realmente el modelo. Consulta Carga y costo de herramientas.
Reemplaza las herramientas de tipo descripción con prompts cuando los patrones sean estables. Si el agente siempre hace las mismas preguntas de lista de selección sobre el mismo campo, codificar ese conocimiento en el prompt del agente es más económico que llamar a get_picklist_values en cada conversación. Consulta Prompts personalizados por agente.
Establece un límite máximo por agente. Los tres hábitos anteriores son cuestión de criterio; dos ajustes por agente los convierten en límites que el agente no puede superar. Máximo de herramientas limita cuántas herramientas ofrece este agente a la IA por turno (1–100; en blanco equivale a 25), un tope directo al coste por turno de la propia lista de herramientas. Máximo de iteraciones de herramientas limita cuántos pasos puede dar el agente dentro de un mismo turno al encadenar herramientas (3–25; en blanco equivale a 6), que es lo que impide que un agente entre en bucle en una tarea que no puede terminar. Ambos están en la sección Controles de rendimiento y costes del registro de Definición de agente; consulta Rendimiento y control de costes.
Errores de permiso en tiempo de ejecución
Las herramientas se ejecutan con los permisos del usuario que las está ejecutando. Cuando una llamada a una herramienta falla porque el usuario no tiene acceso:
- La herramienta devuelve un error estructurado, no un seguimiento de pila
- El agente lee el error y se lo explica al usuario de forma conversacional
- La conversación continúa — los errores de permiso no provocan la caída del agente
Esta es la postura deseada: la plataforma hereda el modelo de permisos de Salesforce, presenta las fallas de forma limpia y permite que el agente ayude al usuario a resolverlas. No existe ninguna vía que eleve al agente por encima del acceso normal del usuario.
Prácticas recomendadas
Crea por intención, no por superficie de API. Una herramienta llamada “Enviar cotización de renovación” que envuelve un método Apex acotado es mucho más confiable que una herramienta genérica “Actualizar registros” que el agente tiene que descifrar. Las herramientas acotadas producen conversaciones predecibles.
Invierte en las descripciones de las herramientas. La decisión del agente de llamar a una herramienta depende casi por completo de la descripción. Detalla qué hace la herramienta, cuándo usarla y qué no hace.
Bloquea lo que no debería cambiar. Usa las herramientas SOQL Template y File Mapping cuando quieras un contrato estable. Usa las herramientas Apex Class cuando necesites flexibilidad. No le des al agente más libertad de la que el caso de uso realmente necesita.
Usa el panel de impacto. El paso de depuración más rápido es leer la vista desde la perspectiva del agente en el panel de impacto y confirmar que coincide con lo que esperas.
Itera con el Depurador de conversaciones. Una vez que la herramienta está activa, el Depurador muestra cada llamada a herramienta que hizo el agente, sus entradas y su resultado. Allí la mayoría de los problemas de las herramientas se vuelven evidentes.
Preguntas frecuentes
A menudo no. Las herramientas SOQL Template y File Mapping son totalmente declarativas. Apex solo se necesita cuando el trabajo implica lógica, escrituras en varios objetos, llamadas externas o extracción estructurada de archivos.
La categoría se bloquea cuando el tipo garantiza un comportamiento específico. Las herramientas SOQL Template siempre leen; las herramientas File Mapping siempre escriben. Las herramientas Apex Class pueden hacer cualquiera de las dos cosas, por lo que son el único tipo en el que la elección es tuya.
Sí. Deja en blanco el campo Nombre del agente en la herramienta y asígnala a tantos agentes como quieras. Para restringir una herramienta a un solo agente, establece el Nombre del agente en el Id de ese agente.
Completa por ti los bloques de configuración específicos del tipo a partir de una descripción y de cualquier entrada de referencia (una consulta para SOQL Template, un CSV de muestra para File Mapping, una descripción más un archivo de muestra opcional para Apex Class). El resultado es editable; no se guarda nada hasta que lo confirmas.
En la siguiente conversación del agente. Las nuevas implementaciones se propagan en cuanto se confirman los metadatos; las conversaciones en curso terminan con la versión con la que empezaron.
La asignación de herramientas se realiza a nivel de agente, no por usuario. Todos los usuarios de un agente ven el mismo conjunto de herramientas. La seguridad a nivel de campo y las reglas de colaboración determinan luego lo que cada usuario puede leer o escribir realmente a través de esas herramientas.
Desactiva la casilla Activo en la Definición de herramienta. La herramienta se conserva (y se puede recuperar), pero se omite en tiempo de ejecución.
Próximos pasos
Lee Confirmaciones de acciones para saber cómo se muestran las herramientas de Acción a los usuarios, o elige un tipo de herramienta para profundizar: SOQL Template, Apex Class o File Mapping.