Herramientas de plantillas SOQL

Consultas bloqueadas Una herramienta de plantilla SOQL envuelve una única consulta SOQL parametrizada como una herramienta que el agente puede llamar. Escribes la consulta una sola vez con marcadores de posición con nombre; el agente completa los parámetros en tiempo de ejecución; la plataforma se encarga del escape, la FLS, el uso compartido y el límite de filas.

¿Qué es una herramienta de plantilla SOQL?

La plantilla SOQL es el más ligero de los tres tipos del Generador de herramientas. Úsala cuando:

Quieres que el agente recupere datos con una consulta que controlas de principio a fin
Quieres exponer solo parámetros específicos — no dejar que el modelo redacte SOQL de forma libre
El resultado es de solo lectura — sin inserciones, actualizaciones ni eliminaciones
No quieres escribir Apex

La consulta en sí queda bloqueada en tiempo de diseño. El agente solo puede elegir qué herramienta llamar y qué pasar para cada parámetro declarado; no puede reescribir el SOQL, cambiar el objeto ni eliminar la cláusula WHERE.

Cómo funciona una herramienta de plantilla SOQL

Escribes la plantilla
Una consulta SOQL con marcadores de posición con nombre en formato {param_name}.
Se genera el esquema
El Generador de herramientas extrae los marcadores de posición y genera un JSON Schema que describe cada parámetro. El generador asistido por IA puede escribir descripciones de parámetros más completas a partir del contexto de la consulta circundante.
Contrato tipado del agente
El modelo ve el nombre de la herramienta, la descripción y la lista de parámetros. Eso es todo — el SOQL subyacente no se expone.
Sustitución en tiempo de ejecución
En el momento de la llamada, la plataforma sustituye cada marcador de posición por el valor del modelo, escapado para evitar la inyección de SOQL. Se verifica que la consulta sea exclusivamente de tipo SELECT, se bloquean las palabras clave DML y se aplica un LIMIT de filas.
Ejecución en modo de usuario
La consulta se ejecuta en modo de usuario — se aplican CRUD, FLS y el uso compartido de registros. En un agente de API con Contexto de ejecución = Sistema, CRUD y FLS se elevan; la colaboración sigue sin elevarse.
El agente recibe el resultado
El resultado se serializa como JSON con totalSize, records y una marca si la visualización se limitó. El agente lo lee y responde al usuario.

Escribir la plantilla

Los marcadores de posición usan llaves y siguen las reglas estándar de identificadores (primero una letra o un guion bajo, luego caracteres alfanuméricos o guiones bajos). Por ejemplo:

SELECT Id, Name, AccountId, StageName, Amount, CloseDate
FROM Opportunity
WHERE StageName = '{stage}'
  AND CloseDate >= {start_date}
  AND CloseDate <= {end_date}
ORDER BY CloseDate ASC

En tiempo de ejecución, el agente proporciona stage, start_date y end_date. Cada valor se escapa antes de la sustitución, de modo que una entrada maliciosa o mal formada no pueda salirse de la consulta.

Qué puedes usar

Cualquier consulta SELECT válida, incluidas las subconsultas de relación padre y de relación hijo
Consultas de agregación (COUNT(), SUM(), GROUP BY) — la plataforma omite su LIMIT automático para las agregaciones sin agrupar, de modo que los totales se devuelven correctamente
Varios marcadores de posición en una sola consulta, en WHERE, ORDER BY, LIMIT o en cualquier lugar donde normalmente aparecería un literal
Condiciones codificadas de forma fija para acotar lo que el agente puede ver — p. ej. WHERE OwnerId = '{user_id}'

Qué está bloqueado

Cualquier cosa que no sea un SELECT — las palabras clave INSERT, UPDATE, DELETE, UPSERT, MERGE y UNDELETE se rechazan en el momento de la validación
Consultas que no resuelven ningún parámetro pero aun así los necesitan — los marcadores de posición que no están en el esquema de entrada no pasan la validación
Plantillas que superan el límite de longitud del campo SOQL Template

Campos de la Definición de herramienta

Campo	Obligatorio	Propósito
Tipo de herramienta	Sí	Establécelo en `SOQL_Template`.
Plantilla SOQL	Sí	La consulta parametrizada con marcadores de posición `{param_name}`.
Categoría	Bloqueado	Siempre `Tool` (solo lectura). El Generador de herramientas lo impone; las herramientas de plantillas SOQL no pueden ser Acciones.
Descripción	Sí	Cómo decide el agente cuándo llamar a esta herramienta. Sé explícito sobre lo que devuelve la herramienta y cualquier alcance al que ya esté filtrada.
Esquema de entrada	Generado automáticamente	Se genera a partir de los marcadores de posición de la plantilla. El generador asistido por IA puede producir descripciones por parámetro más completas; también puedes editar el esquema directamente.
Nivel de herramienta, Canales, Nombre del agente, Objetos de contexto	Opcional	Controles estándar de la Definición de herramienta — escalamiento de nivel, delimitación por canal, asignación por agente y a qué objetos es relevante esta herramienta.

Comportamiento en tiempo de ejecución

Escape y protección contra inyección

Cada parámetro pasa por el escape de comillas simples de SOQL antes de la sustitución, y la consulta resultante se vuelve a comprobar para confirmar que sigue siendo una única instrucción SELECT sin palabras clave DML. El agente no puede convertir un SELECT en una operación DML, comentar cláusulas ni encadenar una segunda instrucción.

FLS, CRUD y uso compartido

Las consultas se ejecutan en modo de usuario. Los objetos, campos y filas que el usuario en ejecución no puede ver no se devuelven. Este es el mismo modelo de seguridad que el resto de la plataforma usa para las herramientas integradas.

La única excepción es un agente con Contexto de ejecución = Sistema en el canal de API, donde el acceso a objetos y campos se eleva. La colaboración de registros nunca se eleva: el ejecutor sigue siendo with sharing, así que incluso un agente elevado obtiene más columnas, nunca más filas.

Límites de filas

Si la plantilla no tiene una cláusula LIMIT, la plataforma agrega una según la configuración de la plataforma Max Query Rows. Las consultas de agregación que no agrupan quedan exentas para que los totales sean precisos. El resultado serializado también tiene un límite de longitud definido por Max Query Result Length — las cargas útiles demasiado grandes se truncan y se marcan para que el agente no desborde el contexto del modelo.

Forma del resultado

El agente recibe un objeto JSON:

{
  "totalSize": 12,
  "showing": 12,
  "records": [
    { "Id": "006...", "Name": "Acme Renewal", "Amount": 25000 },
    ...
  ]
}

Cuando la visualización se limita (coincidieron más filas de las que se le mostraron al agente), un campo note le indica al agente cuántas filas se devolvieron frente a cuántas está viendo.

Una consulta por llamada

Las herramientas de plantillas SOQL ejecutan exactamente una consulta por invocación. La herramienta integrada soql_query de la plataforma admite un modo por lotes que ejecuta varias consultas en un solo intercambio; las herramientas de plantillas SOQL no. Si necesitas un comportamiento por lotes, expón la herramienta integrada soql_query al agente o mueve la lógica a una herramienta de clase Apex.

Seguridad y gobernanza

Los parámetros se escapan automáticamente. No necesitas agregar el manejo de comillas a la plantilla.
Imposición de solo SELECT. La consulta se rechaza en la validación y de nuevo en la ejecución si contiene palabras clave DML.
Ejecución en modo de usuario. Se aplican las reglas de CRUD, FLS y uso compartido; el agente no puede ver datos que el usuario no podría ver en una sesión normal de Salesforce.
Bloqueada en tiempo de diseño. El agente no puede editar el SOQL ni el esquema de parámetros. Los cambios requieren que un administrador actualice la Definición de herramienta.
Rastro de auditoría. La llamada a la herramienta y su resultado se registran en los registros de Conversación y Mensaje, incluida la herramienta que se usó y los parámetros que se pasaron.

Cuándo usar la plantilla SOQL frente a las alternativas

Si necesitas…	Usa
Dejar que el agente redacte su propio SOQL sobre la marcha	La herramienta integrada `soql_query` — consulta Referencia de herramientas integradas
Restringir una consulta a parámetros específicos y una forma fija	Herramienta de plantilla SOQL (esta página)
Insertar, actualizar o eliminar registros	Herramientas de acción integradas, o una herramienta de clase Apex para lógica personalizada
Combinar varias consultas con lógica condicional, o llamar a otro sistema	Una herramienta de clase Apex
Cargar filas de un CSV en un objeto de Salesforce	Una herramienta de mapeo de archivos

Prácticas recomendadas

Restringe la consulta, no al agente. Incorpora límites estrictos en la plantilla — tipos de registro específicos, filtros de propietario, condiciones de estado — en lugar de depender de que el agente los agregue.

Nombra los parámetros de forma semántica. {stage} y {close_date_after} son más claros para el modelo que {p1} y {p2}. Los nombres aparecen en el esquema que lee el agente.

Incluye siempre los campos que el agente necesita para responder. El agente solo ve lo que devuelve el SELECT. Si es probable que la siguiente pregunta del usuario sea “¿quién es el propietario?”, agrega Owner.Name al SELECT ahora.

Agrega un LIMIT explícito para resultados acotados. El LIMIT automático es una red de seguridad, no una herramienta de ajuste. Si sabes que la consulta nunca debería devolver más de diez filas, indícalo en la plantilla.

Prueba en el Generador de herramientas antes de exponerla. El generador te permite ejecutar la plantilla con valores de parámetros de muestra e inspeccionar la consulta sustituida, los resultados y cualquier advertencia de validación.

Preguntas frecuentes

No. Las herramientas de plantillas SOQL son de solo lectura. Las palabras clave INSERT, UPDATE, DELETE, UPSERT, MERGE y UNDELETE se rechazan durante la validación, y el motor de ejecución ejecuta la consulta por una ruta exclusiva de SELECT. Para escrituras, usa las herramientas de acción integradas o una herramienta de clase Apex.

No. Cada valor de parámetro se escapa antes de sustituirse en la consulta. No agregues comillas manuales alrededor de los marcadores de posición — deja que la plataforma lo haga.

No. El modelo ve el nombre de la herramienta, la descripción y el esquema de parámetros. El SOQL subyacente forma parte de la Definición de herramienta y permanece dentro de Salesforce.

La plataforma limita el número de filas mediante la configuración de la plataforma Max Query Rows y, si es necesario, trunca el resultado serializado mediante Max Query Result Length. El resultado que se devuelve al agente incluye una nota que indica que la visualización se limitó, de modo que el agente pueda sugerir acotar la consulta.

El agente puede llamar a varias herramientas dentro de un mismo turno, y cada invocación de plantilla SOQL ejecuta una consulta. La plantilla SOQL no agrupa varias consultas en una sola llamada — para eso, usa el modo por lotes de la herramienta integrada soql_query.

Sí. Las consultas se ejecutan en modo de usuario, por lo que se aplican las reglas de CRUD, la seguridad a nivel de campo y el uso compartido de registros — de forma idéntica a la protección de las herramientas de lectura integradas de la plataforma.

Sí. El Generador de herramientas genera un esquema base a partir de los marcadores de posición, pero puedes editarlo directamente para agregar tipos, enumeraciones, descripciones e indicadores de campos obligatorios. Cuanto más completo sea el esquema, mejor llamará el agente a la herramienta.

Próximos pasos

Lee la Referencia de herramientas integradas para conocer las herramientas que la plataforma incluye de fábrica y que puedes exponer a los agentes sin ninguna configuración, o continúa con Descripción de los campos de contexto para controlar qué datos se incluyen automáticamente con cada conversación.

← Anterior: Herramientas de clases Apex

Siguiente: Referencia de herramientas integradas →