Referencia de herramientas integradas

Cómo leer esta referencia

Toda herramienta integrada tiene la misma anatomía:

• Categoría — Herramienta para recuperación de solo lectura, Acción para cualquier cosa que escriba en Salesforce.
• Confirmación — si el agente muestra una tarjeta de confirmación de acción antes de ejecutarse. Todas las herramientas de acción confirman de forma predeterminada; las de lectura nunca confirman.
• Canales — qué canales de implementación pueden usar la herramienta. Algunas herramientas (eliminaciones, notificaciones internas) están restringidas intencionalmente a los usuarios internos de Salesforce.
• Entrada por lotes — si la herramienta acepta un arreglo de entradas en una sola llamada para reducir las idas y vueltas al modelo.
• Nivel — el nivel de herramienta al que el agente debe tener acceso. Consulta Carga y costo de herramientas.

Las herramientas integradas aplican la seguridad a nivel de campo, CRUD y las reglas de colaboración bajo los permisos del usuario en ejecución — una postura idéntica a la de una sesión normal de Salesforce.

Herramientas de lectura

Las herramientas de lectura recuperan datos y devuelven JSON al agente. Nunca escriben, por lo que no requieren confirmación.

soql_query

Ejecuta una consulta SELECT de solo lectura en modo de usuario. Se aplican CRUD, FLS y las reglas de colaboración. La plataforma agrega un LIMIT de filas si la consulta no lo tiene y limita la longitud del resultado serializado. Las consultas agregadas sin agrupar quedan exentas del LIMIT automático para que los totales se devuelvan con exactitud. Usa la forma por lotes siempre que el agente necesite más de una consulta en un turno — reduce considerablemente las idas y vueltas al modelo.

describe_object

Devuelve el esquema de uno o varios objetos de Salesforce: nombres de API de campos, etiquetas, tipos de datos, referencias a listas de selección y campos de relación. Se almacena en caché dentro de la transacción, por lo que las llamadas repetidas en el mismo turno son gratuitas. El modo por lotes es la forma preferida cuando el agente necesita conocer varios objetos relacionados.

count_records

Devuelve el recuento de filas de un objeto, con un filtro opcional mediante una cláusula WHERE. Más económico que soql_query cuando el agente solo necesita un número. Restringido a los canales internos para que los widgets orientados a invitados no puedan enumerar volúmenes de registros.

get_record

Devuelve un único registro por su ID. Si no se especifica fields, la plataforma devuelve hasta cincuenta campos del objeto que el usuario puede leer. Úsalo cuando el agente ya conoce el ID y solo necesita los valores más recientes.

get_picklist_values

Devuelve los valores activos de la lista de selección de un campo, con las etiquetas, los valores de API y el indicador de valor predeterminado. Útil antes de que el agente intente escribir en un campo de lista de selección.

get_record_types

Devuelve los tipos de registro activos de un objeto. Úsalo antes de create_record cuando el objeto de destino tiene varios tipos de registro y el agente necesita elegir el correcto.

Herramientas de acción

Las herramientas de acción cambian el estado de Salesforce. Toda herramienta de acción muestra una tarjeta de confirmación de forma predeterminada; el usuario debe aprobarla antes de que la plataforma ejecute la acción. La confirmación puede desactivarse por agente en los canales internos mediante Ejecución automática de acciones; en los canales externos y de comunidad permanece activada. Consulta Confirmaciones de acciones para conocer el flujo completo.

create_record

Crea un nuevo registro en el objeto indicado con los valores de campo proporcionados. Se aplican las reglas de validación, los campos obligatorios y la FLS — el agente recibirá una respuesta de error estructurada si la escritura falla.

update_record

Actualiza un registro existente por su ID con los cambios de campo proporcionados. Solo cambiarán realmente los campos que el usuario puede editar.

delete_record

Elimina un registro por su ID. Restringido a los canales internos porque es destructivo e irreversible. La confirmación no puede ejecutarse automáticamente ni siquiera en los canales internos — el usuario debe aprobar cada eliminación.

create_task

Crea una Tarea de Salesforce. De forma predeterminada, asigna la tarea al usuario en ejecución; pasa assigned_to para asignarla a otra persona.

create_event

Crea un Evento de calendario de Salesforce con marcas de tiempo de inicio y fin. El propietario del evento es el usuario en ejecución.

send_email

Envía un correo electrónico a través de Salesforce como el usuario en ejecución. El agente debe obtener el correo del destinatario a partir de un registro de Contacto o Prospecto antes de llamarla. related_to_id adjunta el correo a un registro para el historial de actividades; group_key agrupa varios correos salientes en una sola entrada del registro de auditoría.

Elegir de quién procede el correo. Tres entradas opcionales controlan la identidad del remitente, y las tres se definen mediante las instrucciones del agente y no en un ajuste. from_address indica la dirección de correo para toda la organización desde la que enviar: debe existir y estar verificada en Configuración y, si no se puede asociar, el correo se envía igualmente desde el remitente predeterminado y la discrepancia queda registrada, de modo que un agente nunca se queda en silencio por una errata. sender_display_name establece el nombre visible que ve el destinatario y solo se aplica cuando no interviene ninguna dirección para toda la organización. reply_to decide adónde llegan las respuestas: apúntala a una dirección conectada al enrutamiento entrante y la respuesta volverá a la conversación. Un agente cuyas instrucciones no incluyan ninguna de estas se comporta exactamente como antes. Consulta Canal de correo — Saliente.

Estampar tus propios campos en el correo. Cada correo que envía el agente crea un registro EmailMessage en Salesforce. Si has añadido tus propios campos personalizados a ese objeto —una categoría, un código de campaña, un indicador de nivel de servicio—, la entrada opcional field_values permite que el agente los rellene al enviar, de modo que el correo llega ya clasificado en lugar de necesitar una actualización posterior. Se pasa como un mapa de nombre de API del campo a valor, por ejemplo {"Outreach_Category__c": "Renovación", "Campaign_Code__c": "Q3-RENEW"}. La rigen tres reglas, y cada una existe para evitar que un valor generado por el modelo cause daños:

• Solo campos personalizados. Los nombres deben terminar en __c. Los campos estándar como Subject, Status o FromAddress se rechazan: los establece el propio envío, y permitir que el agente los sobrescriba corrompería el registro de lo que realmente se envió.
• El campo debe existir y ser modificable por el usuario que ejecuta. Los nombres se comprueban contra el esquema real de tu organización antes de escribir nada. Todo lo que no se reconozca se omite, no se adivina.
• El correo nunca se pierde por un campo incorrecto. Si un valor no puede aplicarse, el envío se realiza igualmente y se informa al agente exactamente de qué campos se establecieron y cuáles se omitieron, para que pueda informar con precisión en lugar de afirmar una clasificación que no hizo.

Nada de esto es automático: el agente proporciona field_values solo cuando sus instrucciones se lo indican, así que los agentes existentes no se ven afectados. Si quieres que todos los correos de un agente se etiqueten igual, indícalo en el prompt de Instrucciones personalizadas de ese agente y nombra el campo y el valor que esperas.

send_custom_notification

Publica una notificación de campana en la aplicación para un usuario de Salesforce (es la notificación del icono de campana, no un correo electrónico). Útil para avisar a un colega sobre un registro que el agente acaba de crear o actualizar.

link_file_to_record

Adjunta un archivo cargado a un registro de Salesforce creando un ContentDocumentLink. Si se omite content_document_id, se usa el archivo cargado más recientemente en la conversación. Es el emparejamiento estándar para cualquier agente que procesa documentos y luego necesita adjuntarlos al registro relacionado.

schedule_action

Aplaza otra acción para que se ejecute más tarde. Prográmala por marca de tiempo absoluta, por desfase relativo o por activación de respuesta (por ejemplo, “enviar cuando el contacto responda a este correo”). El trabajo aplazado se crea como un registro de Acción programada y lo ejecuta un trabajo programado. Consulta Acciones programadas para conocer el modelo de ejecución completo.

Condiciones. Los campos opcionales condition_field, condition_operator y condition_value se vuelven a comprobar en el momento en que se dispara la acción, de modo que solo se ejecuta si la situación sigue siendo la que era cuando se programó. condition_operator debe ser uno de estos: equals, not_equals, contains, not_contains, is_blank o not_blank — escrito exactamente así, en todos los idiomas — y cualquier otro valor se rechaza al programar la acción. Una condición que no se puede comprobar omite la acción en lugar de dejar que se ejecute.

get_context_prompts

Obtiene las instrucciones adicionales configuradas para el objeto y el tipo de registro de un registro concreto — útil cuando el usuario menciona un registro que no formaba parte del contexto de la conversación. Devuelve una lista vacía cuando no hay ninguna, lo cual es normal, y el agente tiene instrucciones de no llamarla repetidamente para el mismo registro.

continue_workflow

Solicita un turno autónomo adicional para que un flujo de trabajo continúe en una transacción nueva. Existe para el caso escribir–llamar–escribir: el agente acaba de crear o actualizar un registro y ahora necesita una llamada externa (u otra herramienta) que depende del resultado confirmado. El siguiente turno se ejecuta después de que se confirmen los cambios actuales, así que los registros nuevos y sus Id están disponibles para él. No es un botón genérico de “seguir”: un agente ya puede leer, razonar y escribir varios registros dentro de un mismo turno.

call_agent

Formula una pregunta a otro agente en mitad de una conversación y devuelve su respuesta, de modo que un asistente general puede consultar al agente que domina un tema especializado en lugar de improvisar. El agente consultado responde con sus propias instrucciones, herramientas y acceso a los datos; se ejecuta como la persona que usa el asistente, así que no ve nada que esa persona no pudiera ver ya, y no puede realizar cambios por su cuenta: todo lo que proponga vuelve a la conversación original para que se confirme. Cada consulta cuesta un turno adicional y se conserva como una conversación propia.

Solo funciona cuando un administrador marca a la vez Agente invocable y Permitir solicitudes automatizadas en el agente al que se consulta, y hasta dónde pueden encadenarse las consultas lo define Profundidad máxima de llamadas entre agentes en el agente que pregunta. La disponibilidad por sí sola no cambia nada: son las instrucciones del agente que llama las que deciden cuándo consultar. Consulta Delegación entre agentes.

Disponibilidad por canal de un vistazo

Modo de entrada por lotes

Tres de las herramientas de lectura aceptan un arreglo de entradas en una sola llamada:

• soql_query — arreglo queries (máx. 5)
• describe_object — arreglo object_names (máx. 5)
• count_records — arreglo counts (máx. 5)

El modo por lotes reduce las idas y vueltas al modelo cuando el agente realmente necesita más de un dato del mismo tipo en un turno — por ejemplo, describir tres objetos relacionados antes de componer una consulta, o contar registros con dos filtros a la vez. La forma de entrada única sigue funcionando; el modo por lotes es opcional.

Prácticas recomendadas

Asigna solo lo que el agente necesita. Una lista de herramientas enfocada produce conversaciones más rápidas y predecibles. No hay ningún beneficio en asignar todas las herramientas integradas a todos los agentes.

Ten en cuenta el canal. Una herramienta restringida a los canales internos no aparecerá para un usuario invitado en el Widget externo — aunque esté asignada al agente. Revisa la columna de canales cuando un agente “olvide” una capacidad.

Apóyate en las herramientas de lectura antes de escribir. Combina describe_object y get_picklist_values con create_record para que el agente elija nombres de campo y valores de lista de selección válidos; esto reduce drásticamente los fallos de reglas de validación.

Elige la herramienta adecuada para cada pregunta. count_records es mucho más económico que soql_query cuando lo único que el agente necesita es un número; get_record es mucho más económico que una consulta completa cuando el ID ya se conoce.

Acciones de correo, registros y programación

El correo distingue al destinatario Contacto o Prospecto del registro de negocio relacionado, admite listas Para/CC y comprueba los casos de exclusión de correo compatibles. Los Contactos/Prospectos enviados como registros relacionados se tratan como destinatarios. Las confirmaciones de registros muestran campos no aplicados. Los pasos del plan se concilian uno a uno y los horarios relativos conservan UTC. Se comprueban agentes desactivados y acciones anidadas no permitidas antes de ejecutar confirmaciones. La confirmación de vínculos de archivos reutiliza la ruta con control de acceso. Las acciones nuevas pendientes o reprogramadas por hora requieren un procesador disponible; el seguimiento de respuestas de correo y las actualizaciones normales de historial/estado continúan. Los trabajos posteriores se ejecutan como su propietario de programación, sin suplantar al solicitante. Las instrucciones reducen duplicados por otros conectores, pero no garantizan el comportamiento del asistente.

Preguntas frecuentes

Próximos pasos

Lee Carga y costo de herramientas para saber cómo funciona el acceso basado en niveles, o Confirmaciones de acciones para conocer el flujo de confirmación completo que envuelve cada herramienta de acción.