ADR-002: AnthropicAdapter — decisiones de diseño
Estado: Aceptado Fecha: 2026-05-05
Estado actual: varias de las decisiones de abajo eran “diferir para después”. Hoy el adapter ya hace streaming (
LiveEvents), prompt caching con precios diferenciados y aprobaciones opcionales (Approvals). El resto del ADR queda como registro de por qué se eligió cada camino.
Contexto
Sección titulada «Contexto»Después de cerrar la abstracción AgentRuntimeAdapter, el siguiente paso natural es validar el diseño contra un segundo runtime. Anthropic es el caso obvio: cualquier usuario con ANTHROPIC_API_KEY debería poder operar TAIA standalone, sin levantar OpenClaw.
Antes de escribir código se evaluaron varias bifurcaciones de diseño. Este ADR documenta lo que se descartó y por qué — para que un revisor de PR o un contributor futuro entienda el contexto sin tener que reconstruirlo.
Decisión 1 — Surface: Messages API directo (no Managed Agents)
Sección titulada «Decisión 1 — Surface: Messages API directo (no Managed Agents)»Opciones evaluadas
Sección titulada «Opciones evaluadas»| Opción | Descripción |
|---|---|
| A. Messages API directo ✅ | client.messages.create() stateless. TAIA mantiene la conversación en su DB, ejecuta el tool loop client-side. |
| B. Managed Agents | client.beta.agents.create() + sessions.create(). Anthropic corre el loop server-side, container Linux por sesión, file mounts. |
| C. Ambos como providers separados | anthropic (Messages) + anthropic-managed (Managed Agents) como dos adapters. |
Decisión
Sección titulada «Decisión»Messages API directo. Capabilities: Sessions, Transcripts, LiveEvents, Health.
Por qué no Managed Agents
Sección titulada «Por qué no Managed Agents»- Rompe la abstracción
AgentRuntimeAdapter. El adapter está diseñado para que TAIA controle el loop (spawn → tool_use → call → tool_result → next turn). Managed Agents corre eso server-side, así que el adapter pasaría a ser un envoltorio fino sobre SSE — y las TAIA-native tools tendrían que viajar comocustom toolscon callbacks vía stream, agregando latencia y complejidad. - Costos extra de container. Después del free tier (1550 hrs/mes), cada sesión paga compute además de tokens. Messages API solo paga tokens.
- El modelo de container hosted no encaja con TAIA. TAIA ya tiene
runtime_sessionsen su DB (agregada junto con este adapter), worktrees propios, y un modelo de attachments en roadmap. Duplicar eso con file mounts hosted en Anthropic es contradictorio. - Managed Agents tiene su propio versionado de agents. TAIA ya versiona agents en su tabla
agents. Mantener ambos sistemas alineados (cuándo crear nueva versión, cómo pinear sessions a versión, cuándo archive) es complejidad sin payoff inmediato.
Por qué no ambos
Sección titulada «Por qué no ambos»Crear anthropic-managed como segundo provider es trabajo neto sin demanda probada. Si más adelante un usuario pide “quiero el container Linux dedicado por sesión”, se agrega como adapter aparte. La abstracción está hecha exactamente para eso. Mientras tanto, evitar superficie no usada.
Consecuencia
Sección titulada «Consecuencia»El AnthropicAdapter es stateless del lado de Anthropic: cada messages.create es una llamada nueva con el historial reconstituido desde TAIA DB. Esto implica que TAIA paga el costo full de input tokens en cada turno (sin prefijo cachado server-side). Mitigación posterior con cache_control (prompt caching cliente-side, donde la cache vive en Anthropic pero TAIA dispara los breakpoints).
Decisión 2 — Tools: nativas en el adapter (no MCP)
Sección titulada «Decisión 2 — Tools: nativas en el adapter (no MCP)»Opciones evaluadas
Sección titulada «Opciones evaluadas»| Opción | Descripción |
|---|---|
| A. Tools nativas en el adapter ✅ | tools.ts define taia_tasks_list, taia_tasks_create, taia_stats_get, etc. como Anthropic.Tool[]. Tool execution loop hace HTTP fetch interno a la API de TAIA. |
B. Reusar el MCP server existente (apps/mcp/) |
El agent corre con el MCP server de TAIA conectado. El adapter no expone tools propias; las tools vienen del MCP. |
| C. Ambos: nativas + MCP opcional | Tools nativas siempre disponibles. MCP queda para casos donde el agent corre fuera del adapter (Claude Code, Cursor). |
Decisión
Sección titulada «Decisión»Tools nativas en el adapter.
Por qué no MCP-only
Sección titulada «Por qué no MCP-only»- Anthropic Messages API no es MCP-aware. El SDK no tiene “registrar un MCP server”; espera
tools: Anthropic.Tool[]en la request. Para usar MCP habría que correr un proceso intermediario MCP→Tool, lo cual es más complejidad. - Latencia extra. Tools nativas hacen HTTP a
localhost:13333/api/tasks. MCP agrega un hop más (proceso MCP server → HTTP). - El MCP server existente sigue siendo útil para clients externos (Claude Code, Cursor, agentes que viven fuera de TAIA). No se descarta — sigue corriendo. El adapter simplemente no lo usa para sus propios tool calls.
Por qué no ambos
Sección titulada «Por qué no ambos»Mismo argumento que Decisión 1: superficie no demandada. Si un usuario quiere conectar el adapter al MCP server por algún motivo, se puede sumar después como capability opcional. Hoy no hay caso de uso.
Consecuencia
Sección titulada «Consecuencia»El adapter expone una lista fija de tools (~6 al inicio). La lista es la misma que ya expone el MCP server, solo expresada en formato Anthropic.Tool vs MCP. Si en el futuro las tools cambian (nueva tool, schema actualizado), hay dos lugares para mantener: el MCP server y el archivo tools.ts del adapter. Mitigación: posible refactor más adelante para generar ambos desde una fuente única (deferido — premature abstraction hasta que cambien).
Decisión 3 — Capabilities omitidas
Sección titulada «Decisión 3 — Capabilities omitidas»Decisión
Sección titulada «Decisión»AnthropicAdapter.capabilities = [Sessions, Transcripts, LiveEvents, Health]. Sin Cron, ConfigRead, ConfigWrite, Approvals.
Por qué cada omisión
Sección titulada «Por qué cada omisión»| Capability omitida | Razón |
|---|---|
Cron |
Anthropic no tiene cron server-side. Hay dos caminos posibles: (a) declarar Cron y implementar un scheduler TAIA-side que dispare heartbeats, (b) no declararla y dejar que cron.service tire RuntimeCapabilityError. Elegimos (b). Implementar cron TAIA-side queda para más adelante (junto con Batch API, que reduce 50% el costo de heartbeats periódicos). Hoy: solo trigger manual desde la UI. |
ConfigRead / ConfigWrite |
Anthropic no tiene “config remota del runtime” — la config es la API key + modelo, ambos son TAIA-side. No hay nada que leer ni patchear. |
Approvals |
OpenClaw emite exec.approval.requested para tools sensibles. Anthropic no tiene esto nativo. Se puede simular con un gate en el executor + UI de approval, pero no en la primera versión. |
Consecuencia
Sección titulada «Consecuencia»Servicios que requieren Cron (cron.service.listCrons, cron.service.createCron, etc.) tiran RuntimeCapabilityError claro cuando el adapter activo es Anthropic. La UI de cron management debería ocultar esos controles cuando el provider activo no soporta Cron (mejora UI deferida — por ahora la API rechaza con mensaje claro).
Decisión 4 — Streaming: diferido a una segunda iteración
Sección titulada «Decisión 4 — Streaming: diferido a una segunda iteración»Opciones evaluadas
Sección titulada «Opciones evaluadas»| Opción | Descripción |
|---|---|
| A. Streaming después ✅ | La primera versión usa messages.create() (no .stream()). LiveEvents capability declarada pero on() es no-op. El streaming completo llega en una segunda iteración. |
| B. Streaming desde el inicio | Implementar messages.stream() desde el día 1, mapear deltas a eventos chat/agent compatibles con SSE existente. |
Decisión
Sección titulada «Decisión»El streaming va en una segunda iteración.
Por qué deferir
Sección titulada «Por qué deferir»- Reduce el alcance de la primera versión a algo verificable rápido. Con streaming, el adapter tiene que coordinar con el broadcast layer interno de TAIA (
apps/web/app/api/agents/[agentId]/stream/route.ts) — eso es trabajo de mapeo no trivial. - Permite validar la abstracción primero. Si el contrato
AgentRuntimeAdapterno aguanta Anthropic en su forma más simple (request-response), no aguanta streaming tampoco. Mejor descubrir el problema temprano. - El polling es un fallback aceptable.
awaitSessionCompleteya está pensado para soportar polling (fallbackPollIntervalMs). El adapter usa polling sobreruntime_sessions.statushasta que llegue el streaming.
Consecuencia
Sección titulada «Consecuencia»En la primera versión, los transcripts en la UI no se actualizan en tiempo real para agents Anthropic — el usuario tiene que refrescar. Con el streaming eso desaparece.
Decisión 5 — Cache pricing: diferido
Sección titulada «Decisión 5 — Cache pricing: diferido»Decisión
Sección titulada «Decisión»El pricing de la primera versión es flat — total_tokens × pricing_table[model]. Las columnas cache_creation_input_tokens y cache_read_input_tokens existen en el schema (runtime_sessions) pero el cost calculator las ignora.
Por qué deferir
Sección titulada «Por qué deferir»Prompt caching va aparte porque requiere:
- Decidir dónde poner los
cache_controlbreakpoints (system prompt, tools, last user message). - Auditar que no haya silent invalidators (timestamps en system prompt, etc.).
- Extender la
PRICING_TABLEcon tarifas diferenciadas (cached input ~0.1×, cache write ~1.25×). - Sumar dashboard metrics (cache hit rate por agent/modelo).
Implementarlo prematuramente lleva a hacer placement subóptimo y tener que rehacer. Mejor: primero costos flat (sobrestimados, lo cual es seguro), después caching real.
Consecuencia
Sección titulada «Consecuencia»En la primera versión, los costos reportados por TAIA pueden estar sobrestimados — el usuario ve $X cuando Anthropic le cobró $X×0.6 (porque parte del input fue auto-cacheado por Anthropic en sus internals). Esto es conservador: nunca sub-reporta. El caching real lo ajusta.
Decisión 6 — Persistencia de sesiones: tabla genérica runtime_sessions
Sección titulada «Decisión 6 — Persistencia de sesiones: tabla genérica runtime_sessions»Opciones evaluadas
Sección titulada «Opciones evaluadas»| Opción | Descripción |
|---|---|
A. Tabla genérica runtime_sessions ✅ |
Schema agnóstico de provider. Cualquier adapter futuro (Cursor, Aider) que necesite session storage la usa. |
B. Tabla específica anthropic_sessions |
Dedicada al AnthropicAdapter. Schema afinado para necesidades específicas. |
C. Reusar session_costs con metadata JSONB |
No agregar tabla; meter messages en una columna JSONB de session_costs. |
Decisión
Sección titulada «Decisión»Tabla genérica runtime_sessions + runtime_messages.
Por qué no específica
Sección titulada «Por qué no específica»Premature specialization. El schema que necesita Anthropic (session_key, agent_id, provider, model, status, token columns, messages) es básicamente el mismo que necesita cualquier adapter stateless. Hacer una tabla anthropic_sessions y después una cursor_sessions y otra aider_sessions es duplicación.
Por qué no reusar session_costs con JSONB
Sección titulada «Por qué no reusar session_costs con JSONB»session_costs está diseñada para tracking de costos, no para storage de transcripts. Meter messages array en JSONB:
- Hace queries para listar sessions más caras (la JSONB rota cada turno).
- Pierde la posibilidad de indexar por
positionpara paginar mensajes. - Convierte una tabla focused en cost en algo “todopoderoso” — antipattern.
Consecuencia
Sección titulada «Consecuencia»Schema agnóstico desde el día 1. Cuando se sume Cursor/Aider/etc., esos adapters reusan runtime_sessions directamente. La columna provider ('anthropic', 'cursor', etc.) discrimina. Nada que migrar.
Resumen de decisiones
Sección titulada «Resumen de decisiones»| # | Decisión | Alternativas descartadas |
|---|---|---|
| 1 | Messages API directo | Managed Agents; ambos como providers |
| 2 | Tools nativas en el adapter | MCP-only; ambos |
| 3 | Capabilities [Sessions, Transcripts, LiveEvents, Health] |
Cron, ConfigRead/Write, Approvals (deferidos) |
| 4 | Streaming en una segunda iteración | Streaming desde el inicio |
| 5 | Cache pricing diferido | Cache pricing desde el inicio |
| 6 | Tabla genérica runtime_sessions |
Tabla anthropic_sessions; JSONB en session_costs |
Cuándo revisar este ADR
Sección titulada «Cuándo revisar este ADR»Revisar (y posiblemente reemplazar con un ADR-XXX nuevo) si:
- Se decide implementar un adapter para Managed Agents y queremos rejustificar la coexistencia.
- Anthropic agrega cron / config endpoints server-side y conviene declarar esas capabilities.
- El tool loop client-side resulta demasiado lento o caro y conviene migrar a PTC (Programmatic Tool Calling).
- Aparece un segundo adapter stateless (Cursor, Aider) y descubrimos que
runtime_sessionsnecesita extensiones que las hacen específicas.