El nuevo Agentforce Builder: de configurar un bot a escribir un agente

Este documento está pensado en capas. Si es la primera vez que oye la palabra Agentforce, arranque por la Parte 0 con una analogía sin tecnicismos. Si ya construyó un agente con el builder anterior, salte a la Parte 3 (Anatomía del stack nuevo) y a la Parte 5 (Su primer Agent Script). Si viene a decidir migración, mire la Parte 8 (Cuándo migrar) y la Parte 10 (Cómo empezar).

Piense en un asistente virtual como si contratara personal para atender un mostrador de servicio al cliente. En el modelo anterior, usted contrataba por partes: primero el recepcionista (el bot), después le enseñaba en qué temas puede hablar (los tópicos), después le explicaba qué acciones puede ejecutar (las funciones), y por separado le entregaba un cerebro de planificación que decidía qué hacer con cada consulta. Cuatro contratos, cuatro archivos, cuatro conversaciones distintas — y todos tenían que estar sincronizados o el asistente se rompía.

En el modelo nuevo, usted no contrata por partes. Escribe un solo guion — como el guion de una obra de teatro — que dice: así se llama el personaje, así saluda, así se presenta, esto es lo que sabe, estas son las escenas en las que participa, esta es su lista de acciones, este es el orden y estas son las variables que recuerda. Un solo cuaderno. Un solo idioma. Y si mañana quiere cambiar cómo saluda, edita una línea; no tiene que abrir cuatro archivos distintos.

¿Y qué gana el negocio con esto?

• Tiempo — cambiar cómo se comporta un agente pasa de horas de configuración a minutos de edición.
• Confianza — se puede probar el agente antes de publicarlo, con casos de prueba que se corren en batch y en CI, no solo en la vista de Preview.
• Trazabilidad — todo el comportamiento vive en un archivo versionado en Git, con historial de cambios y revisión por pares.
• Escalabilidad — modelar un negocio grande con varios sub-agentes especializados (uno para pedidos, otro para reclamos, otro para cotizaciones) deja de ser una acrobacia técnica y pasa a ser el patrón oficial.

La motivación pública no está escrita como un manifiesto — hay que leerla entre líneas en el propio contenido oficial. El blog `Master the Agentic Development Lifecycle for Agentforce` (junio 2026) describe al AiAuthoringBundle como *the deployable package containing the agent's complete definition as local metadata files* y al Agent Script como *the declarative format that specifies your agent's sub-agents, routing logic, instructions, and action bindings*. Debajo de esas dos oraciones hay una decisión de arquitectura clara: pasar de una configuración imperativa fragmentada a una definición declarativa unificada.

Qué problemas del modelo anterior estaba resolviendo

El nuevo Agentforce Builder ataca las cuatro deudas en paralelo. La definición se unifica en un archivo. El diff en Git empieza a leerse como lógica de negocio. El testing es un comando de CLI de primera clase. Y el patrón router + subagentes está documentado como la manera oficial de modelar dominios múltiples.

Antes de meternos al nuevo modelo, revisemos el anterior con el mismo detalle. Sin esa foto no se aprecia el cambio.

Las 5 piezas que componían un agente v1

En un caso real (Paquetexpress, agente `Agentforce_Paquete_Express` v12) esto se traducía en 1 bot, 1 planner, 5 GenAiPlugin, 17 GenAiFunction custom y decenas de instrucciones distribuidas — que en la auditoría dieron 8 funciones huérfanas y contradicciones entre reglas. No es que el modelo anterior estuviera mal; es que su superficie de configuración escalaba mal.

force-app/main/default/
├── bots/
│   └── Agentforce_Paquete_Express/
│       ├── Agentforce_Paquete_Express.bot-meta.xml
│       └── v12.botVersion-meta.xml
├── genAiPlanners/
│   └── Agentforce_Paquete_Express.genAiPlanner-meta.xml
├── genAiPlugins/
│   ├── Orden_Management.genAiPlugin-meta.xml
│   ├── Quote_Management.genAiPlugin-meta.xml
│   ├── General_Information_Management.genAiPlugin-meta.xml
│   ├── SvcCopilotTmpl__CaseManagement.genAiPlugin-meta.xml
│   └── SvcCopilotTmpl__Escalation.genAiPlugin-meta.xml
└── genAiFunctions/
    ├── Obtener_estatus_de_la_orden/
    ├── Create_Case_v2/
    ├── Obtener_C_digo_postal_origen_v_lido/
    └── ... (14 más)

El agente completo se define en un archivo `.agent` (Agent Script) y se empaqueta en un metadata type llamado `AiAuthoringBundle`. La estructura de directorios en SFDX se simplifica dramáticamente.

force-app/main/default/
└── aiAuthoringBundles/
    └── Paquete_Express_Agent/
        ├── Paquete_Express_Agent.agent
        └── Paquete_Express_Agent.aiAuthoringBundle-meta.xml

Un archivo, un bundle. El contenido del `.agent` sigue un esquema declarativo con bloques nombrados. Cada bloque tiene una responsabilidad clara.

Los bloques que componen un `.agent`

Los 3 tipos de referencia que aparecen en el script

• `@variables.<name>` — apunta a una variable declarada arriba. Ej. `@variables.isPremiumUser`.
• `@actions.<name>` — apunta a una acción (Apex, Flow, prompt template) empaquetada en el bundle. Ej. `@actions.obtener_estatus_orden`.
• `@subagents.<name>` — apunta a otro sub-agente definido en el mismo script. Ej. `@subagents.quotes_agent`.

Los 2 operadores de flujo

• `->` (flecha determinística) — enrutamiento por regla, sin llamar al LLM. Ej. *si el canal es WhatsApp, dirige al subagente `mobile_agent`*.
• `|` (pipe LLM) — llama al LLM para razonar la siguiente decisión. Es el modo natural cuando la lógica es flexible o depende de contexto conversacional.

Nada explica el nuevo modelo como leer un `.agent` completo. A continuación un ejemplo comentado — un agente de servicio para una empresa de paquetería, con router + 2 sub-agentes.

system:
  instructions: |
    Eres el asistente virtual de Paquetexpress. Ayudas con
    rastreo de envíos, cotizaciones nacionales y creación de
    casos. Responde en el idioma indicado por
    @variables.endUserLanguage; si no está definido, responde
    en español. Nunca muestres el Case ID al cliente.
  messages:
    welcome: |
      Hola, soy el asistente de Paquetexpress. Puedo ayudarte
      a rastrear un envío, cotizar un servicio nacional o
      crear un caso. ¿Qué necesitas hoy?
    error: |
      Perdona, tuve un problema procesando tu solicitud.
      ¿Quieres intentarlo de nuevo o transferirte con un
      agente humano?

config:
  agent_name: "Paquete Express Agent"
  agent_description: |
    Agente de servicio al cliente de Paquetexpress. Cubre
    rastreo, cotización nacional y creación de casos.

access:
  default_agent_user: "paquete_express_agent@example.com"

language:
  default_locale: "es_MX"
  additional_locales:
    - "en_US"

variables:
  endUserLanguage: mutable string = "es_MX"
    description: |
      Idioma preferido del cliente, tomado de la sesión de
      Messaging. Cambia si el cliente pide explícitamente
      cambiar de idioma.
  isPremiumUser: mutable boolean = False
    description: |
      Verdadero si el cliente tiene contrato empresarial
      activo. Se calcula al identificar al contacto.

start_agent router:
  description: |
    Router raíz. Decide qué sub-agente atiende la consulta
    según intención del cliente.
  reasoning:
    instructions: |
      Clasifica el mensaje del usuario en una de estas rutas:
      1. Rastreo o estatus de pedido → @subagents.orders_agent
      2. Cotización nacional → @subagents.quotes_agent
      3. Cualquier otra cosa → responde con el mensaje de
         bienvenida y ofrece las 2 opciones.

  | @subagents.orders_agent
  | @subagents.quotes_agent

subagent orders_agent:
  description: |
    Atiende preguntas sobre rastreo y estatus de pedidos.
  reasoning:
    instructions: |
      Si el usuario da número de guía, invoca
      @actions.obtener_estatus_orden. Si no tiene guía,
      ofrece crear un caso pidiendo email, nombre y apellido.
      No solicites identificación adicional si la consulta
      es solo de rastreo.
  | @actions.obtener_estatus_orden
  | @actions.crear_caso_seguimiento

subagent quotes_agent:
  description: |
    Cotizaciones nacionales (Sobre y Paquete).
  reasoning:
    instructions: |
      Pregunta CP origen → valídalo. Pregunta CP destino →
      valídalo. Luego pregunta tipo (Sobre o Paquete). Para
      Paquete pide peso y dimensiones. Ejecuta la acción de
      cotización correspondiente. No identifiques al cliente.
  | @actions.validar_cp_origen
  | @actions.validar_cp_destino
  | @actions.cotizar_sobre
  | @actions.cotizar_paquete

Nótese la economía del formato: 60 líneas describen lo que en el modelo anterior requería un `Bot`, un `GenAiPlanner`, 3 `GenAiPlugin` y 5-6 `GenAiFunction` — cada uno en su propio XML. Aquí vive todo en una unidad legible, versionable y navegable.

Cómo se llama un action desde el script

Un `@actions.obtener_estatus_orden` en el script apunta a un archivo declarado en el mismo bundle. Ese archivo describe el input, el output y el binding a un Apex, Flow o prompt template. La ventaja: al leer el script se ve el nombre semántico (`obtener_estatus_orden`) y no un ID críptico de metadata. La ventaja secundaria: refactorizar es un rename cross-file en el bundle, no una operación de metadata.

Agentforce DX es el nombre oficial del toolkit pro-code: `sf agent` (subcomando de Salesforce CLI) + una extensión oficial de VS Code con syntax highlighting, autocompletion y validación del Agent Script. Todos los comandos siguientes están verificados en la Salesforce CLI unified reference.

Ciclo de vida completo con `sf agent`

Comandos adyacentes que amplían el ecosistema

• `sf agent adl create/list/upload` + `sf agent adl file add/delete/list` — administración de **Agentforce Data Libraries (ADL)** desde CLI. Permite subir documentos y usarlos como grounding sin tocar la UI.
• `sf agent mcp create/get/list/update/delete/fetch` — administración de servidores **MCP (Model Context Protocol)** conectados al agente. Está en **Developer Preview**.
• `sf agent template ...` — packaging de agentes como templates reusables entre orgs.

En el modelo anterior, testear un agente era casi siempre manual — abrir Preview y hacer preguntas a mano. El nuevo builder trae dos superficies de testing y una de observabilidad que estaban ausentes como productos oficiales.

1 · Test cases estructurados (`sf agent test`)

Se declara un YAML de casos de prueba con `sf agent generate test-spec`. Cada caso tiene un input, una expectativa y una tolerancia. Se corren con `sf agent test run` — local o en CI. Los resultados son leíbles con `sf agent test results`.

2 · Evaluación LLM-as-judge (`sf agent test run-eval`, Beta)

Para casos donde la expectativa no es una respuesta exacta sino una calidad de respuesta (tono, completitud, adherencia a la política), la CLI expone `run-eval` — un evaluador que usa el LLM como juez. Al momento de publicación está en Beta. Es la respuesta oficial a la práctica común de armar evaluadores caseros.

3 · Trazas de producción (`sf agent trace`)

Cada interacción del agente en producción deja una traza que se puede recuperar con `sf agent trace read <id>`. La traza incluye qué sub-agente atendió, qué acciones invocó, qué decisiones de routing tomó y el uso de tokens. Es el equivalente a un logging estructurado sobre el runtime del agente — sin depender de Data Cloud ni de armar dashboards ad hoc.

Model Context Protocol (MCP) es un estándar abierto para exponer herramientas y datos a un modelo de lenguaje. Antes, las acciones de un agente en Agentforce vivían dentro de la plataforma — Apex, Flow, Prompt Templates. Con MCP integrado, un agente puede invocar herramientas expuestas por servidores externos que hablen el protocolo — sin escribir wrappers de Apex ni negociar contratos custom.

Qué habilita concretamente

• Conectar el agente a un servidor MCP corporativo que exponga inventario en tiempo real, catálogos, servicios internos — sin construir integraciones bespoke.
• Reutilizar herramientas que ya escribió para otros agentes (por ejemplo, un asistente de VS Code interno) en su agente de servicio al cliente.
• Estandarizar el `agent A2A` (agent-to-agent) con contratos ya establecidos por la industria en lugar de reinventarlos por proyecto.

Comparación honesta entre alcance del builder anterior y del nuevo, con lo verificable y lo que sigue abierto.

Preguntas abiertas verificables — no fabricar respuestas

• **GA date del Agentforce Builder** — no fue verificable en fuente oficial fetchable durante esta investigación. Requiere confirmación contra release notes Winter '26 / Spring '26 / Summer '26.
• **Retirement del stack v1** (Bot + GenAiPlanner + GenAiPlugin + EinsteinServiceAgent) — no anunciado según lo verificable en agosto 2026. Coexistencia es la política observable.
• **Motor de razonamiento** — si el nuevo builder sigue usando ReAct por debajo o si adoptó explícitamente Atlas Reasoning Engine no está confirmado en la doc actual de Agent Script. Requiere verificación con release notes de reasoning engine.
• **Migración forzada** — no confirmada. Los agentes v1 pueden seguir corriendo; los nuevos deben ir sobre `AiAuthoringBundle` como path preferido.

Un agente sin canal es un experimento. El canal web de segunda generación en el ecosistema de Salesforce se llama en la documentación **Enhanced Web Chat** (referenciado como **ECv2** en la superficie de APIs). Es la evolución del widget que usted montaba antes con `embeddedservice_bootstrap.init(...)`.

Qué cambia respecto a la generación 1

El objeto bootstrap sigue existiendo

Buenas noticias para quien ya tiene un widget Gen1 en producción: el objeto global `embeddedservice_bootstrap` sigue existiendo en ECv2. Los settings documentados de la nueva API operan sobre él con el mismo naming. Ejemplos verificados en la doc oficial:

embeddedservice_bootstrap.settings.chatButtonPosition = "30px,20px";
embeddedservice_bootstrap.settings.disableInlineAutoLaunch = true;
embeddedservice_bootstrap.settings.hideChatButtonOnLoad = true;
embeddedservice_bootstrap.settings.restrictSessionOnMessagingChannel = true;
embeddedservice_bootstrap.settings.shouldOpenLinksInSameTab = true;

embeddedservice_bootstrap.init(
  orgId,
  deploymentName,
  siteUrl,
  { scrt2URL: scrt2URL }
);

Si termina de leer este documento y quiere probarlo esta semana, este es un plan concreto de un sprint (2 semanas) que produce un agente v2 funcional publicado en una sandbox, con testing y observabilidad.

Semana 1 · Setup y primer agente

1. Instalar Salesforce CLI actualizada + la extensión oficial Agentforce DX para VS Code.
2. Instalar el skill bundle `forcedotcom/sf-skills` (`npx skills add forcedotcom/sf-skills`) para autoría asistida.
3. Autenticar CLI a una sandbox de desarrollo con `sf org login web`.
4. Ejecutar `sf agent generate agent-spec` — responder a las preguntas de persona, capabilities y idiomas.
5. Ejecutar `sf agent generate authoring-bundle` para producir el `.agent` inicial.
6. Abrir el `.agent` en VS Code y editarlo — agregar 1 subagente y 1 acción simple (por ejemplo, `hola_mundo`).
7. Validar con `sf agent validate authoring-bundle`.
8. Publicar en sandbox con `sf agent publish authoring-bundle` y activar con `sf agent activate`.
9. Previsualizar con `sf agent preview` — validar respuesta a 3-5 inputs típicos.

Semana 2 · Testing, canal y observabilidad

1. Ejecutar `sf agent generate test-spec` y describir 10-15 casos representativos (feliz, borde, adversarial).
2. Correr `sf agent test run` — iterar sobre las instrucciones hasta que los casos pasen.
3. Configurar un Embedded Service Deployment con Enhanced Web Chat (ECv2), apuntando al agente publicado.
4. Agregar el dominio del sitio anfitrión a la lista de dominios permitidos (Setup) y republicar.
5. Embeber el widget en el sitio con `embeddedservice_bootstrap.init(...)`.
6. Enviar 10 conversaciones reales de prueba desde el widget.
7. Correr `sf agent trace list` — revisar 3 trazas al azar para validar decisiones de routing y uso de acciones.
8. Documentar hallazgos, iterar sobre 2-3 instrucciones y republicar.

Checklist de listo para producción

• El script está en Git, con revisión por pares aprobada.
• El test suite corre en CI y bloquea merges si falla.
• Todas las acciones críticas tienen `isConfirmationRequired` cuando aplica.
• El agente tiene guardrails de scope explícitos (no dar consejos legales/médicos, no discutir competidores).
• El canal tiene sessionTimeout definido (no `0`) — 15-30 min para chat, 24h para email.
• Enhanced Web Chat está desplegado con dominios permitidos correctos y JWT auth (si aplica).
• Al menos una alerta de observabilidad configurada sobre las trazas — error rate, latencia p95.

Toda afirmación técnica de este documento está anclada a documentación oficial pública. Donde la fuente no fue verificable en el momento de investigación, quedó marcada como `requiere verificación`. Estas son las URLs que sostienen el resto del texto.

• Agentforce Developer Guide · Índice oficial
• Agent Script · Documentación de referencia
• Agent Script · Documentation download (AgentScriptDocs.zip)
• Salesforce CLI · `sf agent` unified reference
• Master the Agentic Development Lifecycle (blog · jun 2026)
• Enhanced Web Chat (ECv2) · Settings API reference
• Messaging for Web · Developer Guide
• Salesforce · Agentforce Platform (producto)