La API v3 de Arko en 5 minutos

Toda la superficie de Arko —agentes, Powers, memoria— es accesible por API, y esa es la vía por la que llevas un agente a tu propio producto. La API v3 está pensada para que la primera llamada exitosa te tome minutos, no una tarde: autenticas con una clave, apuntas a un agente y recibes una respuesta. Este recorrido va de la clave a tu primera conversación, con las dos o tres cosas que conviene entender desde el inicio para no reescribir la integración después.

Autenticación: tu clave de API

La API se autentica con una clave que generas en tu panel y que envías en cada petición mediante la cabecera de autorización. Esa clave identifica a tu cuenta y determina qué agentes y qué límites tienes disponibles, así que se trata como un secreto: vive en una variable de entorno del servidor, nunca en el código del navegador ni en un repositorio. Si una clave se expone, se revoca y se genera otra; por eso conviene usar claves distintas para cada entorno, de modo que rotar una de desarrollo nunca afecte a producción.

Una regla que ahorra incidentes: las llamadas a la API se hacen desde tu backend, no desde el cliente. Si el navegador del usuario llamara directamente a Arko, tu clave viajaría al dispositivo de cada visitante. Tu servidor actúa de intermediario: recibe la petición de tu frontend, añade la clave y reenvía a Arko. Así el secreto nunca sale de tu infraestructura.

Tu primera conversación

El corazón de la API es enviar un mensaje a un agente y recibir su respuesta. Indicas qué agente responde, pasas el mensaje del usuario y, si quieres continuidad, un identificador de conversación para que Arko mantenga el hilo. La respuesta llega con el texto del agente y los metadatos de la ejecución. Con esas tres piezas —agente, mensaje e hilo— ya tienes un chat funcional; todo lo demás es refinamiento sobre esta base.

• El agente: cuál de tus agentes debe responder a este mensaje.
• El mensaje: el texto del usuario que quieres que el agente procese.
• El hilo de conversación: un identificador para agrupar mensajes y conservar el contexto entre peticiones.
• La respuesta: el texto del agente más los metadatos de la ejecución (uso, herramientas invocadas).

Respuestas en streaming

Esperar a que el agente termine de pensar antes de mostrar algo hace que la interfaz se sienta lenta, aunque el tiempo total sea el mismo. El streaming resuelve esa percepción: la respuesta llega en fragmentos a medida que se genera, y tu interfaz los pinta en tiempo real, como si el agente escribiera frente al usuario. Para un chat, el streaming no es un lujo: es lo que separa una experiencia que se siente viva de una que parece congelada. La API v3 lo soporta de forma nativa, y activarlo suele ser cuestión de pedir la respuesta en modo incremental y consumir los fragmentos conforme llegan.

Manejar errores desde el primer día

El código que solo contempla el camino feliz funciona en la demo y falla en producción. Desde la primera integración conviene tratar tres situaciones que ocurrirán: la petición que se rechaza por autenticación —clave inválida o ausente—, la que se frena por límite de uso, y la que falla por un problema transitorio de red. Las dos primeras se resuelven revisando la clave y respetando los límites; la tercera se maneja reintentando con una espera creciente, nunca en un bucle inmediato que empeora la congestión.

La API responde con un envoltorio uniforme: en el éxito, los datos que pediste; en el error, un mensaje claro y un código que puedes ramificar en tu lógica. Apóyate en ese código para distinguir «reintenta» de «arregla tu petición»: no tiene sentido reintentar una clave inválida, ni rendirse ante un fallo de red pasajero. Ese pequeño discernimiento, escrito una vez al principio, es lo que hace que tu integración aguante el día que algo, inevitablemente, se tuerza.