ACP TypeScript SDK

Qué implementación documenta

@agentclientprotocol/sdk es la biblioteca TypeScript oficial para implementar ambos lados de Agent Client Protocol: el cliente y el agente. La guía de la biblioteca, consultada el 2026-11-09, describe client() y agent() para registrar handlers tipados y conectar participantes. El protocolo y sus fronteras conservan su hogar en agent-client-protocol.

ACP significa aquí Agent Client Protocol. Un cliente puede ser un editor o una interfaz propia; el participante agente incorpora la lógica de trabajo que esa interfaz utiliza. La elección del SDK no define el modelo, los prompts ni las herramientas del agente. Tampoco convierte una interfaz ACP en cliente MCP: son responsabilidades de integración diferentes.

Entrada estable y funciones experimentales

El repositorio oficial distingue la entrada predeterminada @agentclientprotocol/sdk, que selecciona ACP v1, de entradas unstable y experimental/v2. Las entradas v2 permanecen experimentales; seleccionar un subconjunto denominado estable del borrador no constituye una garantía de estabilidad del protocolo o de sus APIs.

El proyecto también indica que elegir una entrada experimental no anuncia capacidades automáticamente. La aplicación debe usar imports coherentes para sus tipos y métodos y comprobar qué admite la contraparte. Compilar contra una biblioteca nueva y comunicar correctamente con un editor existente son comprobaciones distintas.

Esta nota se centra en la entrada estable v1. Antes de actualizar, registrar versión del paquete, entrypoint, versión del protocolo y funciones requeridas. No se fija una versión patch ni se presupone que todas las interfaces consumidoras incorporen de inmediato cada función nueva.

Del cliente al turno de trabajo

La inicialización de ACP v1 exige que el cliente inicialice la conexión antes de crear una sesión. El intercambio comunica versión, capacidades e información de autenticación. Las capacidades ausentes se consideran no soportadas; la integración debe responder a esa ausencia sin asumir acceso general al cliente.

Un recorrido conceptual para evaluar una integración es:

cliente y agente conectan
→ acuerdan versión y capacidades
→ establecen una sesión compatible
→ cliente envía el encargo
→ agente informa actividad y solicita lo necesario
→ cliente presenta progreso y decisiones al usuario
→ turno termina con un resultado o estado observable

La sesión permite organizar interacción; la evidencia de que el cambio satisface la tarea sigue necesitando generated-code-verification. Una notificación de progreso no prueba que una prueba haya pasado ni que un efecto remoto se haya completado.

Solicitudes de permiso y controles efectivos

El contrato de tool calls v1 permite al agente solicitar permiso mediante session/request_permission. El cliente devuelve una elección o cancelación; también puede aplicar decisiones automáticas conforme a su configuración. El SDK facilita representar el intercambio, mientras el producto debe implementar su política y manejar la respuesta.

Mostrar «rechazado» en la interfaz requiere que el ejecutor respete ese resultado. Los permisos de filesystem, procesos o red deben analizarse donde realmente corre la operación. agent-permissions-and-approval-boundaries y agent-sandboxing conservan la distinción entre aprobación de una acción y restricciones técnicas de ejecución.

Si un agente accede a recursos del cliente, revisar qué capacidades expone este y para qué sesión. El hecho de integrar un editor no concede al agente autoridad sobre otros proyectos, credenciales o publicaciones. Conviene mantener el encargo humano separado de los mensajes externos que el sistema procesa.

Ejercicio práctico y mantenimiento

Como prueba propuesta por el Atlas, usar un cliente y agente de laboratorio con una tarea sin efectos de producción. Observar inicialización, capacidad opcional ausente, solicitud de permiso aceptada, rechazada y cancelada, y finalización del turno. Registrar qué participante ejecuta cada acción y cuál solo la muestra.

Después de probar el par de ejemplo, repetir la integración con el editor o cliente elegido. Verificar comportamiento ante desconexión y compatibilidad de actualizaciones antes de agregar funciones experimentales. Esta nota se basa en documentación; no instala la biblioteca ni verifica en vivo una integración particular.

coding-agent explica el sistema que realiza el trabajo y ai-technology-catalog organiza las implementaciones. ai-supply-chain-risk aporta el criterio para incorporar adapters, paquetes y agentes de terceros sin confundir compatibilidad con confianza.