Guía: Llama a tu agente desde código
Una sola API HTTP mueve la página web, el terminal y tus programas. Abierta en tu máquina, con tokens cuando la compartes. Llámala con curl, el cliente de BoxLang o cualquier herramienta OpenAPI.
En esta página
Llama a tu agente desde código
Todo agente construido sirve una API HTTP en /__bxagents. La página de chat web, el chat de terminal y los gateways usan la misma, así que todo lo que ellos hacen, tu programa también puede hacerlo. Esta guía es el recorrido; cada ruta, con su petición y su respuesta, está en el documento OpenAPI que entrega el servidor, y los ajustes están en agentApi.
El proyecto en examples/api-agent/ ejecuta todo lo de abajo.
Abierta o con token
Dos maneras de ejecutar, elegidas con agentApi en Agent.yaml.
| Ajustes | Quién puede llamar | |
|---|---|---|
| Abierta (por defecto) | nada | Cualquiera que llegue al puerto. Todos son un solo usuario, local. Déjala en 127.0.0.1; serve imprime un aviso cuando una API abierta escucha en todas las interfaces. |
| Con token | tokenEnvVar: MY_SECRET y/o tokens: true | Quien envíe x-bxagents-token. El secreto compartido es admin; los tokens emitidos son chat o admin. Todo lo demás recibe 401. |
También puedes limitar quién llama con allowedIPs y cuántas veces con rateLimit; ambos sirven abierta o cerrada.
agentApi:
tokenEnvVar: TOKEN_FOR_ADMIN # el NOMBRE de una variable de entorno
tokens: true # acepta también tokens hechos con `bxAgents token create`
manageTokens: true # un admin puede crear y revocar tokens por la API
Con curl
export T="x-bxagents-token: $TOKEN_FOR_ADMIN"
curl -H "$T" http://127.0.0.1:8080/__bxagents/whoami
curl -H "$T" -H "Content-Type: application/json" \
-d '{"input":"¿Qué puedes hacer?"}' \
http://127.0.0.1:8080/__bxagents/invoke
invoke responde { "success": true, "output": "...", "threadId": "..." }. Envía conversationId para continuar una conversación; el agente la recuerda por ti.
Con BoxLang
import bxModules.bxagents.models.api.AgentApiClient;
client = new AgentApiClient( url = "http://127.0.0.1:8080", token = getSystemSetting( "TOKEN_FOR_ADMIN" ) );
first = client.invoke( "¿Qué puedes hacer?" );
println( first.output );
// el texto a medida que se escribe
client.stream( "Dilo más corto.", ( text ) => print( text ), first.threadId );
Construye el cliente con argumentos con nombre. Hay un método por cada ruta: invoke, stream, events, resume, cancel, steer, sessions, history, export, notes, preferences, command, tokens y el resto. Una petición incorrecta vuelve como { success: false, error, code }; un token rechazado, una ruta que falta o un fallo del servidor se lanzan como error. Pasa path cuando el servidor movió la API con agentApi.path, y source para nombrar tu programa en la lista de conversaciones.
Streams
stream y events responden con eventos enviados por el servidor: cada frame es event: <nombre> y luego data: <json>.
| Frame | Significado |
|---|---|
thread | Primer frame: el id de la ejecución, para cancel, steer y resume. |
chunk | Un trozo de lo que dice el modelo. |
tool | Una llamada a tool empezó (running) o terminó (ok). Solo events. |
suspended | La ejecución se detuvo a la espera de aprobación. Responde con resume. Solo events. |
error | La ejecución falló. |
done | Último frame. |
stream lleva thread, chunk y done. events los lleva todos, y el cliente los convierte en eventos para tu callback: thread, delta, reasoning, tool, suspended, error.
Control de ejecuciones
Una ejecución pertenece a quien la empezó.
| Llamada | Hace |
|---|---|
cancel( threadId ) | La detiene. Solo su dueño, o un admin. |
steer( threadId, input ) | Añade un mensaje a una ejecución en marcha. |
pending( threadId ) y resume( threadId, decision ) | Aprobar, rechazar o editar lo que quiere hacer una ejecución detenida. |
Conversaciones, notas y ajustes
Las conversaciones también pertenecen a quien llama: sessions() las lista, las más nuevas primero (un admin puede pasar all = true para ver las de todos), y createSession, renameSession, forkSession, deleteSession, history y export trabajan sobre una. notes() y preferences() guardan lo que el agente debe recordar de quien llama. command( "/context" ) ejecuta cualquier comando de barra que esa persona pueda usar.
Tokens de acceso por la API
Con manageTokens: true un admin puede crear tokens sin una shell en el servidor:
made = client.createToken( name = "ci", scope = "chat", expires = "90d" );
println( made.token ); // se muestra una vez; el servidor guarda solo una huella
client.revokeToken( "ci" );
La misma lista, creación y revocación están en el panel Tokens de la página web (se muestra a los admins en un servidor que lo permite). Un token chat recibe 403. Sin manageTokens, las rutas no existen.
Errores
Todo error es { "success": false, "error": "texto para personas", "code": "codigo_para_maquinas" }.
| Estado | Códigos |
|---|---|
| 400 | bad_request, bad_profile, bad_attachment |
| 401 | unauthorized |
| 403 | forbidden, csrf, not_your_run |
| 404 | not_found, no_notes |
| 405 | method_not_allowed |
| 409 | busy (ya hay una ejecución en esa conversación) |
| 429 | rate_limited de una comprobación de token; la guarda rateLimit (Throttle de cbSecurity) responde { "error": true, "messages": [...] } con una cabecera Retry-After |
El documento OpenAPI
curl -H "$T" http://127.0.0.1:8080/__bxagents/openapi > agent-api.json
Es un documento OpenAPI 3 de las rutas que este servidor realmente tiene: cada ruta, lo que recibe y responde, la cabecera de token en una API cerrada y los frames del stream. Pásalo a un generador de clientes o a una herramienta como Swagger UI o Postman. Las rutas, el documento y el cliente de BoxLang salen de una sola lista, y una prueba falla cuando discrepan.