Pi Coding Agent por RPC: protocolo JSON, providers y una Web UI personalizada

No solo se puede interactuar con Pi Coding Agent en el terminal. Su modo RPC ejecuta el Agente como un proceso secundario, recibe comandos JSON a través de entrada estándar y devuelve continuamente respuestas y eventos desde la salida estándar. Esta ruta es adecuada para shells de escritorio, consolas de navegador, sistemas de órdenes de trabajo internos o pruebas automatizadas, pero no es tan simple como adaptar la salida del terminal a una página web. Lo que realmente hay que abordar es la duración del proceso, los números de solicitud, los eventos de transmisión, los directorios de sesiones, los permisos y la recuperación de excepciones.

El modo RPC no resuelve las llamadas de red remota

RPC aquí es el protocolo de proceso nativo. El programa host inicia pi --mode rpc, escribe un objeto JSON por línea y lee la salida estándar de Pi línea por línea. No escucha automáticamente en los puertos HTTP y no realiza autenticación de usuario, TLS ni acceso entre máquinas por usted. Para proporcionar una interfaz de usuario web, el proceso secundario de Pi debe estar retenido por su propio backend y el navegador solo debe conectarse a este backend. No permita que las páginas web públicas generen directamente comandos nativos ni toque el directorio de trabajo.

Primero confirme que el comando y la versión sean de la misma instalación

Después de instalar Pi, primero verifique en la misma cuenta donde planea ejecutar el servicio:

1
2
3


pi --version
pi --help
pi --mode rpc --help

Los servicios de Windows, WSL y PowerShell simple pueden resolverse en diferentes ejecutables. Confirme la ruta usando el siguiente comando en PowerShell:

1

Get-Command pi | Select-Object Source, Version

Para registrar versiones antes de actualizar, los clientes RPC deben probarse con una versión explícita en lugar de cambiar de forma predeterminada todos los campos de eventos para siempre.

Observe el protocolo con comandos mínimos

Comience en un directorio de prueba vacío:

1
2
3


mkdir pi-rpc-lab
cd pi-rpc-lab
pi --mode rpc --no-session

Una vez iniciado el proceso, la interfaz interactiva tradicional no aparecerá, pero esperará la línea JSON en la entrada estándar. Al enviar una solicitud, debes finalizarla con una nueva línea; simplemente escriba JSON sin una nueva línea y el analizador puede seguir esperando. La experimentación manual es adecuada para ver la primera respuesta; la integración formal debe hacer que el programa lea tanto stdout como stderr.

Trate la salida estándar como canal de protocolo

Cada línea de la salida estándar debe analizarse primero como un mensaje JSON completo. No escriba sugerencias de depuración, sus propios prefijos de registro o controles de color en la misma tubería. Los registros de diagnóstico del programa host se escriben en stderr o en un archivo independiente. Cuando reciba una línea que no se puede analizar, registre el texto original, la versión y los números de mensaje antes y después, pero no envíe la línea completa que pueda contener la clave al registro público.

Un ciclo de lectura robusto consta de cuatro pasos:

Divida el flujo de bytes por nuevas líneas.
Realice el análisis JSON en una sola línea.
Distribuya respuestas o eventos según el tipo de mensaje.
Los tipos desconocidos entran en la rama de compatibilidad en lugar de bloquear todo el proceso.

El ID de solicitud es el núcleo de la correlación concurrente

El cliente puede enviar comandos de control mientras la tarea anterior aún está transmitiendo la salida. Por lo tanto, no se puede utilizar el supuesto de posición de que “la siguiente respuesta pertenece a la solicitud anterior”. Genere una ID única para cada comando y mantenga la asignación pending. La desasignación ocurre después de que llega la respuesta final; los eventos intermedios son manejados por la sesión o el estado de turno actual.

1
2
3
4
5
6
7


type Pending = {
  resolve: (value: unknown) => void;
  reject: (reason: Error) => void;
  timer: ReturnType<typeof setTimeout>;
};

const pending = new Map<string, Pending>();

El tiempo de espera solo significa que el host no recibió la respuesta final a tiempo, pero no significa que el proceso secundario de Pi se haya detenido. Después del tiempo de espera, también debe decidir si cancela el envío, continúa recibiendo o finaliza todo el proceso secundario.

Esqueleto mínimo de Node.js para iniciar procesos secundarios

El siguiente esqueleto no vincula deliberadamente campos de eventos específicos, sino que solo es responsable de la bifurcación confiable y la salida del proceso:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


import { spawn } from "node:child_process";
import readline from "node:readline";

const child = spawn("pi", ["--mode", "rpc", "--no-session"], {
  cwd: process.cwd(),
  stdio: ["pipe", "pipe", "pipe"],
  shell: false,
  env: { ...process.env },
});

const lines = readline.createInterface({ input: child.stdout });

lines.on("line", (line) => {
  try {
    const message = JSON.parse(line);
    routeMessage(message);
  } catch (error) {
    console.error("invalid RPC JSON", { line, error });
  }
});

child.stderr.on("data", (chunk) => {
  process.stderr.write(`[pi] ${chunk}`);
});

child.on("exit", (code, signal) => {
  rejectAllPending(new Error(`pi exited: ${code}/${signal}`));
});

shell: false es importante: los parámetros se pasan como matrices para evitar que el shell vuelva a interpretar las rutas del proyecto o el texto del usuario. Si Windows no puede encontrar pi, la ruta absoluta debe resolverse durante la fase de inicio en lugar de concatenar la cadena de comando.

Función de envío de encapsulación unificada

Todas las escrituras pasan por una entrada para limitar el tamaño del mensaje, verificar el estado del proceso y garantizar las nuevas líneas finales.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


function send(message: Record<string, unknown>) {
  if (!child.stdin.writable) {
    throw new Error("Pi RPC stdin is not writable");
  }

  const payload = JSON.stringify(message);
  if (Buffer.byteLength(payload, "utf8") > 256 * 1024) {
    throw new Error("RPC message is too large");
  }

  child.stdin.write(payload + "\n");
}

No incruste cadenas JSON en archivos grandes. Coloque el archivo en un directorio de trabajo controlado, deje que el agente lo lea a través de la herramienta y verifique en el servidor si la ruta real todavía está en el directorio.

El flujo de eventos requiere una máquina de estado explícita

Un mensaje puede pasar por la cola, el inicio, el incremento de texto, la llamada a la herramienta, el resultado de la herramienta, el final o el error. No se limite a mantener una cadena agregada constantemente en la interfaz; de lo contrario, los eventos y reintentos de la herramienta pueden aparecer repetidamente. Se recomienda guardar el siguiente estado para cada turno:

queued: La solicitud ha sido escrita y aún no se ha confirmado su inicio.
running: Se están recibiendo eventos de modelo o herramienta.
aborting: La solicitud del usuario está abortada y esperando el estado final.
completed: La respuesta final está completa.
failed: Error de protocolo, error de modelo o salida de proceso.

Cuando los eventos llegan en un orden anormal, los números de secuencia originales se conservan y la interfaz de usuario puede mostrar “estado incompleto” en lugar de pretender que se realizó correctamente.

Primero, ocúpese de la contrapresión y luego hable sobre la experiencia de transmisión

stdin.write() Devolver false indica que el buffer está bajo presión. En este momento la transmisión se suspende y continúa a la espera del evento drain. El lado del navegador también debe limitar la cola pendiente de WebSocket y los clientes lentos no pueden ocupar la memoria del servidor indefinidamente. Los deltas de texto se pueden fusionar y enviar cada 30 a 80 milisegundos, lo que reduce las actualizaciones de DOM y los paquetes de red. Los resultados de las herramientas normalmente se envían como eventos en su totalidad y no son adecuados para el corte a nivel de personaje.

El proveedor y el modelo están fijados por los parámetros de inicio

La documentación oficial de RPC proporciona los parámetros de inicio --provider y --model. Por ejemplo, un servicio puede iniciar diferentes trabajadores para diferentes propósitos:

1

pi --mode rpc --provider anthropic --model MODEL_NAME --no-session

No permita que los usuarios habituales del front-end envíen nombres de proveedores o parámetros de modelo arbitrarios. El backend mantiene la lista de permitidos y asigna “Rápido”, “Alta calidad” y “Local” a las combinaciones revisadas. Verifique las credenciales, las limitaciones del contexto y las capacidades de las herramientas antes de cambiar de proveedor; Los modelos con el mismo nombre también pueden tener un comportamiento de facturación o salida diferente.

La clave solo ingresa al entorno del proceso hijo

Las claves API se almacenan en herramientas de administración secreta del lado del servidor o en variables de entorno restringidas. No escriba claves en RPC JSON, almacenamiento local del navegador, encabezados de sesión ni devoluciones de datos de error. Al iniciar un proceso hijo, puede construir un entorno mínimo en lugar de heredar incondicionalmente todas las variables del proceso de servicio.

1
2
3
4


const childEnv = {
  PATH: process.env.PATH,
  ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
};

El nombre real de la variable depende del proveedor seleccionado; si falta, se informará un error antes de comenzar para evitar que la solicitud falle a la mitad.

El directorio de sesión determina la recuperabilidad

--no-session es adecuado para tareas únicas, CI y pruebas de protocolo. No se basa en sesiones históricas posteriores a la salida del proceso. Cuando necesite reanudar la sesión, utilice las capacidades de sesión de Pi y coloque los datos en una ubicación explícita a través de --session-dir.

1

pi --mode rpc --session-dir ./runtime/sessions

El servidor debe asignar los ID de usuario de la aplicación a nombres de directorios aleatorios internos. Los usuarios tienen prohibido ingresar directamente ../, letra de unidad o ruta compartida de red. Antes de realizar una copia de seguridad de una sesión, confirme si contiene mensajes, fragmentos de código, resultados de herramientas o datos comerciales y establezca un período de retención.

`--name` se utiliza para distinguir instancias controladas

Establecer un nombre distinguido para instancias de larga ejecución ayuda con la correlación de registros:

1

pi --mode rpc --name support-agent --session-dir ./runtime/support

El nombre debe ser generado por la configuración de implementación; no utilice directamente la dirección de correo electrónico, el nombre del cliente ni el texto completo de la orden de trabajo. El registro también registra el ID de la instancia de la aplicación, el PID del proceso Pi y la versión de inicio, para que pueda restaurar a qué subproceso pertenece una excepción.

La interfaz de usuario web debe estar separada por su propio backend

El enlace recomendado es:

1
2
3
4
5
6


Browser
  -> HTTPS / WebSocket
Application backend
  -> stdin/stdout JSON lines
Pi RPC child process
  -> model provider and local tools

El backend es responsable del inicio de sesión, la limitación de velocidad, el directorio de trabajo, la lista blanca de proveedores y la auditoría. El navegador solo recibe los campos necesarios para la presentación y no debería ver rutas absolutas nativas, variables de entorno ni resultados de herramientas desenmascarados. Si el WebSocket se desconecta, el turno puede continuar en el backend y el cliente puede reponerse de acuerdo con el número de secuencia del evento; también se puede rescindir activamente de acuerdo con las reglas del producto.

Un usuario, un proceso no siempre es correcto

El proceso secundario residente se recupera rápidamente, pero ocupa memoria y guarda más contexto. Cada solicitud crea un nuevo proceso con un aislamiento más claro, pero aumenta los costos de inicio y recuperación de sesiones. Un compromiso común es crear trabajadores basados en espacios de trabajo, salir después de estar inactivos durante un período de tiempo y colocar solicitudes simultáneas en la cola en serie de cada trabajador. No permita que dos solicitudes modifiquen el mismo espacio de trabajo de Git al mismo tiempo. Cuando se requiera paralelismo, cree árboles de trabajo independientes o copias temporales de tareas.

Los permisos de herramientas son más importantes que la selección del modelo

El proceso secundario de Pi hereda los archivos y comandos a los que puede acceder la cuenta en ejecución. Al implementar la interfaz de usuario web, realice al menos el siguiente aislamiento:

Utilice una cuenta dedicada que no sea de administrador.
El directorio de trabajo utiliza una lista de permitidos.
Deniega el acceso a claves SSH, perfiles de navegador y configuraciones de producción.
Primero haga una copia temporal o de solo lectura del repositorio externo.
Los eventos de auditoría se conservan para escribir archivos, ejecutar comandos y acceder a la red.

Los contenedores pueden reducir el alcance del sistema de archivos, pero aún así deben limitar los montajes, las redes y los sockets de host. Conectar el socket Docker al Agente equivale a otorgar altas capacidades de control del host.

La suspensión y el apagado deben estar separados

“Detener la respuesta actual” no es lo mismo que “matar el proceso Pi”. Priorice el uso del comando de cancelación proporcionado por el protocolo para que el turno actual reciba un estado final reconocible. El proceso hijo finaliza solo si el protocolo deja de responder, se cierra la salida estándar o se excede el período de terminación forzada. Cuando el servicio sale, primero deja de recibir nuevas solicitudes, espera un breve período de gracia, luego cierra la entrada estándar y recicla el proceso. La semántica de señales de Windows y Linux es diferente y las pruebas de salida deben realizarse por separado.

La recuperación tras fallo no puede reproducir automáticamente las operaciones de escritura

Cuando el Pi falla después de una llamada a la herramienta, el host no necesariamente sabe si se ha completado la escritura del archivo. No reproduzca el último mensaje incondicionalmente; de lo contrario, podría volver a enviar, reenviar la solicitud o sobrescribir el archivo. La interfaz de recuperación debe mostrar el último evento de confirmación y brindarle al usuario la opción de verificar el espacio de trabajo, continuar la conversación o crear una nueva sesión. Las consultas de sólo lectura se pueden diseñar con reintentos idempotentes; las operaciones de escritura requieren ID de operación o validación posterior a la ejecución.

Los registros se dividen en tres categorías: protocolo, operación y auditoría

El registro del protocolo registra el tipo de mensaje, el ID de solicitud, el número de secuencia de eventos y el consumo de tiempo, y no guarda el texto completo de forma predeterminada. Ejecute registros de registro PID, versión, código de salida, memoria y resumen estándar. Los registros de auditoría registran quién abrió qué espacio de trabajo, qué capacidades de herramienta estaban permitidas y qué cambios se realizaron. Los permisos de acceso y los períodos de retención se establecen para los tres tipos de registros respectivamente. Las reglas de enmascaramiento cubren al menos la clave API, el encabezado de autorización, el correo electrónico, la ruta absoluta del usuario y el secreto del repositorio.

Escriba primero la prueba del protocolo en lugar de hacer clic manualmente en

El cliente de prueba puede iniciar pi --mode rpc --no-session, enviar una solicitud fija y verificar:

Cada línea de salida estándar se puede analizar como JSON.
El ID de la solicitud se puede asociar con la respuesta final.
Los eventos de texto y herramientas no se liquidan dos veces.
La promesa pendiente se borrará después del tiempo de espera.
Todos los camareros reciben una falla cuando el proceso secundario sale de manera anormal.

Agregue entradas que contengan chino, barra invertida, nueva línea y texto demasiado largo para verificar el escape UTF-8 y JSON. No llame a modelos reales costosos en CI; reemplace los subprocesos con implementaciones falsas que generen eventos fijos de acuerdo con el mismo protocolo.

Realice cuatro simulacros de fallas antes de conectarse

Primero, desconecte el navegador durante la operación y confirme que el backend no almacene eventos en caché de forma indefinida. En segundo lugar, permita que el proveedor devuelva la limitación actual o el error de autenticación para confirmar que el error no expondrá la clave. En tercer lugar, elimine el Pi durante la ejecución de la herramienta para confirmar que el sistema no reproduce las escrituras automáticamente. Cuarto, permita que el tipo de mensaje desconocido aparezca en la salida estándar, confirme el registro del cliente y continúe procesando los mensajes compatibles posteriores. Estos resultados son una mejor evidencia de que la integración se puede mantener que “la página recibe el primer texto”.

Elija RPC o use la biblioteca directamente

Las ventajas de RPC son la independencia del lenguaje, un claro aislamiento del proceso y la capacidad de reutilizar la configuración de inicio oficial de la CLI. La compensación es mantener los subprocesos, las ramas JSON, las máquinas de estado y la compatibilidad de versiones. Si el host en sí es TypeScript y necesita un control profundo del ciclo de vida del Agente, puede evaluar la integración directa de la interfaz de biblioteca correspondiente. Si el host es Python, Go, un programa de escritorio o el Agente necesita ser un trabajador independiente, RPC suele ser más fácil de establecer límites.

¿Cuál es la versión mínima entregable

? Una primera versión confiable debe tener al menos: versión Pi fija, cola en serie de un solo espacio de trabajo, lista blanca de proveedores, autenticación de backend, número de secuencia de eventos, tiempo de espera y cancelación, registro stderr, verificación del directorio de sesión y limpieza de salida de excepciones. En la segunda etapa, se agregarán grupos de trabajadores de múltiples espacios de trabajo, reanudación de la desconexión, aprobación de herramientas y estadísticas de uso. No hagas hermosas burbujas de chat primero y luego dejes los permisos de archivos y la recuperación de fallas hasta que te conectes.

Conclusión

El valor de Pi Coding Agent RPC es colocar el ciclo de ejecución del Agente maduro detrás de un límite de proceso claro. La calidad de la integración depende de que el host administre correctamente las filas JSON, los ID de solicitud, los estados de los eventos, los directorios de sesiones y los permisos de las herramientas. Primero use --no-session para completar la prueba del protocolo de solicitud única, luego agregue sesiones persistentes y interfaz de usuario web y, finalmente, verifique la estrategia de recuperación mediante desconexión, limitación de corriente y simulacros de fallas. Lo que se obtiene de esta manera no es un “reenviador de terminal que pueda chatear”, sino un conjunto de servicios de Agente que se pueden auditar, aislar y actualizar continuamente.

Entrada de documento Pi RPC

Documentación del modo Pi RPC