Cómo crear tu primer agente en Arko

Crear un agente parece trivial hasta que lo pones frente a usuarios reales: entonces contesta de más, inventa datos, ignora instrucciones o se queda mudo cuando debía actuar. La diferencia entre un agente que impresiona en una demo y uno que aguanta producción no está en el modelo que elijas, sino en cómo lo defines: un propósito acotado, instrucciones sin ambigüedad y solo las herramientas que necesita. Esta guía recorre ese camino en Arko, del propósito a la publicación.

Qué es un agente en Arko

Un agente es un modelo de lenguaje con tres cosas encima: un conjunto de instrucciones que definen su comportamiento, un acceso opcional a memoria para recordar entre conversaciones, y una colección de Powers —herramientas— que le permiten hacer algo más que responder texto. Lo que en un chat genérico es una caja de diálogo, en Arko es una entidad con propósito, límites y capacidad de ejecutar acciones sobre tus propios sistemas.

Antes de tocar nada, conviene tener claro que un agente no es un prompt largo. El prompt es solo una de sus piezas. Un buen agente se parece más a la descripción de un puesto de trabajo: qué hace, qué no le corresponde, con qué herramientas cuenta y a quién escala cuando algo se sale de su alcance.

Paso 1: define el propósito antes que el prompt

El error más común al empezar es abrir el editor de instrucciones y escribir «Eres un asistente útil y amable». Esa frase no acota nada: describe a cualquier agente del mundo. Antes de redactar una sola instrucción, responde en una frase concreta qué problema resuelve tu agente y para quién. «Responde dudas de facturación de clientes existentes y crea tickets cuando no puede resolverlas» es un propósito; «ayudar a los usuarios» no lo es.

• El destinatario: a quién le habla el agente (un cliente, un empleado interno, un desarrollador).
• El resultado esperado: qué debe conseguir cada conversación, no solo de qué puede hablar.
• Los límites: qué temas o acciones quedan explícitamente fuera de su alcance.
• La salida cuando no sabe: a dónde deriva o qué responde cuando el caso lo supera.

Paso 2: escribe instrucciones que se cumplen

Con el propósito claro, las instrucciones casi se escriben solas. La regla es preferir lo específico sobre lo genérico y lo afirmativo sobre lo prohibitivo: un agente sigue mejor «responde siempre con el monto exacto y la fecha de vencimiento» que «no seas vago». Ordena las instrucciones de lo más importante a lo más accesorio, porque cuando el contexto se llena, lo primero pesa más. Y da ejemplos: una o dos conversaciones modelo enseñan el tono mejor que tres párrafos describiéndolo.

Cuida también lo que el agente no debe hacer, pero exprésalo como comportamiento, no como una lista de miedos. En lugar de acumular prohibiciones, define la conducta correcta ante el caso difícil: qué responde si le piden algo fuera de su alcance, cómo reacciona si el usuario insiste, cuándo reconoce que no tiene la información en lugar de inventarla. Un agente que sabe decir «no tengo ese dato, déjame crear un ticket» vale más que uno que nunca admite un límite.

Paso 3: dale herramientas con Powers

Un agente que solo genera texto está a medio construir. Los Powers son las herramientas que le permiten actuar: consultar el saldo real de un cliente, crear un ticket, buscar en tu catálogo, disparar un webhook hacia tu backend. En Arko conectas un Power describiendo qué hace y qué parámetros necesita; el agente decide cuándo usarlo a partir de la conversación. La clave es dar pocas herramientas y bien descritas: diez Powers ambiguos confunden al agente más que lo habilitan.

Empieza con una sola herramienta y verifica que el agente la invoca en el momento correcto y con los parámetros correctos. Solo cuando ese lazo funciona conviene sumar la segunda. Un agente con dos Powers que usa impecablemente es más útil —y mucho más fácil de depurar— que uno con ocho que dispara al azar.

Paso 4: prueba en el playground y publica

Antes de exponer el agente, conversa con él en el playground como lo haría tu peor usuario: pregúntale lo que no debería contestar, dale datos incompletos, cámbiale el tema a mitad de conversación. Ahí se revelan los huecos de las instrucciones sin costo. Cuando el comportamiento sea estable en los casos difíciles, publícalo: intégralo en tu producto vía la API, conéctalo a un canal como un widget o Telegram, y observa las primeras conversaciones reales, que siempre enseñan algo que la prueba no anticipó.

Publicar no es el final sino el principio del ciclo. Los primeros días revisa las conversaciones reales, identifica los dos o tres patrones donde el agente falla y ajústalos en las instrucciones. La mayoría de los problemas se resuelven con una frase más precisa, no con un modelo más grande.

Errores comunes al empezar

Querer que un solo agente lo haga todo, hasta que ninguna instrucción cabe sin contradecir a otra: cuando un agente acumula propósitos, conviene partirlo en varios especializados. Escribir instrucciones en negativo, que el modelo cumple peor que las afirmativas. Conectar todos los Powers de golpe y no saber cuál causa un comportamiento raro. Y publicar sin haber probado los casos límite, que son justamente los que llegan primero en producción. Empieza pequeño, verifica cada pieza y crece sobre lo que ya funciona.