Principios de diseño — lee esto primero

La mayoría de los problemas de "el agente da malas respuestas" son de configuración, no del modelo. Sigue estos pasos antes de construir, y los resultados serán sólidos. Ignóralos y es fácil armar algo que parece plausible y se comporta mal, para luego confundir eso con un límite de la plataforma.

Descubre antes de construir — entrevista, no solo ejecutes

"Crear un agente de soporte" es el inicio de la conversación, no la especificación. Nunca respondas esto con un único create_agent y devuelvas una carcasa vacía. Trabaja como el asistente de configuración: entrevista primero, planifica toda la configuración, repítela, y luego construye. Pregunta en lenguaje claro — unas pocas preguntas a la vez, sobre su situación real, no sobre parámetros de herramientas — hasta que puedas visualizar el resultado final:

• El trabajo y a quién sirve. ¿Para qué es este agente, quién habla con él, cómo se ve una respuesta buena? Un trabajo por agente — si describen tres, son tres agentes.
• Lo que debe responder desde → una base de conocimientos. ¿Tienen documentos, un sitio web, políticas, una lista de precios? Si los hechos deben ser correctos, esos se convierten en una base de conocimientos que tú construyes y adjuntas — no texto del prompt. Si aún no tienen nada, diles qué recopilar.
• Procedimientos que ejecuta → habilidades. ¿Comportamientos de "cuando X, haz estos pasos" (reservar, verificar, cotizar)? Cada uno se convierte en una habilidad de carga bajo demanda con un "usa esto cuando…" claro.
• Cosas que debe hacer en otros sistemas → MCP. ¿Revisar un calendario, buscar un pedido, abrir un ticket? Esos son MCP tools para vincular — pregunta por el sistema y si pueden conectarlo.
• Un flujo guiado y con estado → un Storyline. ¿Es un proceso con memoria (captación → calificación → seguimiento) en lugar de preguntas y respuestas únicas? Eso es un Storyline, no solo un agente.
• Cómo se abre y sus límites duros. La primera línea que ven los visitantes (→ un page playbook) y los límites que van en task ("nunca cites un precio", "nunca des asesoramiento legal").

Luego repite el plan antes de tocar una herramienta — "así que construiré: el agente Soporte, una base de conocimientos a partir de tus PDFs de políticas, una habilidad de reserva, y vincularé tu calendario vía MCP — ¿correcto?" — y construye solo una vez que confirmen. Saltarse esto es exactamente cómo terminas con un agente vacío que nadie quería. Una solicitud vaga es una señal para preguntar, nunca una señal para adivinar.

Un agente, un trabajo

Asigna a cada agente una tarea única y claramente delimitada. Un agente "que hace todo" — soporte y ventas y programación — tiene una task difusa, compite consigo mismo por la atención, y responde peor a cada cosa. Si tienes tres trabajos, construye tres agentes.

Mantén el número de habilidades pequeño

Adjunta solo las habilidades que el trabajo de este agente necesita — aproximadamente cinco o menos. Las habilidades son elegidas por el modelo a partir de su description de una línea; cuanto más adjuntes, más difícil esa elección, y más a menudo cargará la incorrecta o ninguna. Un conjunto enfocado con descripciones claras de "usa esto cuando…" supera a un gran montón.

• La description de cada habilidad dice cuándo recurrir a ella, en una línea.
• Los procedimientos viven en instructions (cargados bajo demanda), nunca en soul (pagado por cada turno).
• Si dos habilidades se superponen en cuándo, fusionalas — los disparadores superpuestos hacen que la elección sea como lanzar una moneda.

Fundamenta los hechos; pon los límites en la task

• Los hechos (tasas, política, catálogo) pertenecen a una base de conocimientos, que se recupera cada turno — no en el prompt, donde se vuelven obsoletos y sin citar. Ver Construir una base de conocimientos.
• Las restricciones pertenecen a task, como negaciones: "nunca prometas una fecha", "para una cotización, llama a una herramienta". Los límites negativos detienen la deriva mejor que la descripción positiva. No pongas reglas de seguridad en soul — la plataforma añade moderación global por ti.
• Activa grounding_required cuando las respuestas deben provenir del material, no de las predicciones del modelo.

Nunca entregues la determinismo a la probabilidad

La regla de diseño más útil en esta plataforma: si algo puede ser computado, generado o verificado por el sistema, nunca lo dejes al modelo. Un modelo al que se le pide producir un artefacto determinista no falla ruidosamente — produce uno plausible. El usuario obtiene un número de ticket que no existe, una llamada programada siete horas fuera, una paleta de colores que falla el contraste. Nada da error; está simplemente equivocado en silencio.

Cada uno de estos comenzó como un fallo real en producción y se convirtió en una función de la plataforma:

La corolario para escribir habilidades: tus instructions deben decirle al modelo qué función del sistema usar ("pasa run_at, retransmite el código devuelto"), no enseñarle a imitar la función ("calcula los segundos, formatea un número de ticket"). Si te encuentras escribiendo el output de un proceso determinista, busca la herramienta que lo produce — o pide una.

Dos corolarios sobre el output

Una regla de prompt es una solicitud; una verificación posterior es una regla. "Nunca digas X" pertenece al prompt — reduce la tasa — pero no es aplicación. Un modelo que está de acuerdo con la instrucción aún puede llegar a la misma idea prohibida mediante una redacción que tu texto no anticipó, y cada reescritura de la regla tiende a capturar solo las redacciones que ya viste. La redacción no puede policar la redacción. Así que haz una pregunta diferente: ¿es la frase no deseable reconocible en la respuesta terminada? Si lo es, elimínala allí, y mantén también la línea del prompt.

Asegúrate primero del contenido; no dejes que la sintaxis te cueste el contenido. Un modelo más pequeño a menudo hará la elección correcta y luego la escribirá en una forma que tu analizador rechaza — un objeto por línea en lugar de un array, una coma final, prosa envuelta alrededor del bloque. Analizar estrictamente significa que una respuesta correcta se descarta por una llave mal colocada, y el síntoma parece ser un modelo que no es lo suficientemente capaz. Decide qué campo en la respuesta es portador de carga — usualmente exactamente uno: un id, una referencia, una elección — y extrae ese campo sea como sea que llegue. El resto de la carga suele ser datos que ibas a reemplazar con los tuyos de todos modos, así que la estrictitud sobre ello no protege nada.

Muestra al agente solo buenos patrones

Cuando entregas ejemplos a un agente, haz que sean ejemplos correctos. No pegues un fragmento de "aquí está la forma incorrecta" junto a la correcta — el modelo puede imitar el ejemplo más cercano en lugar de leer la advertencia. Describe lo que se debe evitar con palabras; mantén los ejemplos ejecutables como ejemplares.

Verifica — escribir no es funcionar

Después de cada cambio, verifica que hizo lo que tenías previsto. Crear un agente no significa que esté configurado como crees; añadir a una base de conocimientos no significa que la pregunta se recupere.

get_agent(name="Support")                                   # confirma la configuración que se guardó
search_knowledge_base(kb_name="Company policy", query="…")  # confirma que la respuesta es recuperable

Un resultado search vacío significa que esa pregunta se responderá como "no cubierta" — encuentra eso ahora, no desde un cliente.

Devuelve un entregable — y el siguiente paso

Después de cada acción, no solo informes que terminaste. Devuelve cuatro cosas: lo que produciste, un enlace clicable a la consola para verlo, una línea sobre cómo usarlo, y el siguiente paso natural — propuesto, y ofrecido para hacerlo. Preguntarán "¿dónde lo veo?", "¿cómo lo uso?" y "¿qué ahora?" de todos modos; responde a los tres de antemano. Codifica los nombres con espacios en URL.

Por ejemplo, después de importar documentos a una base de conocimientos, responde con cuántos chunks se guardaron, el enlace anterior para que puedan abrir su knowledge starmap y ver exactamente lo que se ingirió, y confirma si ahora está adjunto a un agente (o cómo adjuntarlo). Un simple "hecho" solo los hace preguntar.

Siempre termina en el siguiente paso, y ofrécelo — una configuración es una cadena, no una acción única:

• ¿Construiste una base de conocimientos? → ofrece adjuntarla a un agente (pregunta cuál).
• ¿Creaste un agente? → ofrece adjuntar una base de conocimientos, añadir una habilidad, o crear un enlace de compartir para que los usuarios finales lo alcancen (un espacio vacío = apagado).
• ¿Escribiste una habilidad? → ofrece adjuntarla al agente que la necesita.
• ¿Publicaste un Storyline? → ofrece establecerlo como predeterminado del agente, o conectar su disparador de inscripción.
• ¿Registraste un servidor MCP? → ofrece concederle sus herramientas a un agente.

"Aquí está lo que hice, aquí está el enlace, aquí está cómo usarlo, y aquí está lo que haría a continuación — ¿quieres que lo haga?" mantiene la construcción en movimiento; un simple "hecho" deja al inquilino adivinando.