Apuntes de Certificación

1 · Bucle agéntico y tool use

Un agente es, en la definición que usa Anthropic, un LLM usando herramientas en bucle de forma autónoma. El ciclo tiene cinco pasos: recibir prompt → el modelo evalúa y responde → se ejecutan las tools que ha pedido → los resultados vuelven → repetir. Termina cuando el modelo produce una respuesta sin llamadas a tools.

Cómo se sabe que hay que seguir

A nivel de API, cuando Claude quiere usar una tool la respuesta trae stop_reason: "tool_use" y uno o más bloques tool_use con id, name e input. Cuando ha terminado, stop_reason: "end_turn". Ese campo es el control de flujo del bucle.

Valores posibles de stop_reason: end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal, model_context_window_exceeded.

Cómo vuelven los resultados

En un mensaje con role: "user" que contiene bloques tool_result. Campos: tool_use_id (obligatorio), content (opcional) e is_error (opcional). No existe rol tool ni function en la API de Claude, a diferencia de otras APIs de chat.

Dos reglas de formato que devuelven 400 si se incumplen: el mensaje con los tool_result debe ir inmediatamente después del assistant que emitió el tool_use, y los bloques tool_result deben ir los primeros del array content. Cualquier texto va detrás.

Errores de tool

Un fallo de tool no es una excepción de tu aplicación: es información para el modelo. Se devuelve como tool_result con is_error: true y una causa legible, para que el agente pueda reintentar con otros parámetros, escalar o informar.

Definir tools

Tres campos obligatorios: name (regex ^[a-zA-Z0-9_-]{1,64}$), description e input_schema (JSON Schema).

Buenas prácticas oficiales: consolidar operaciones relacionadas en menos tools con un parámetro de acción, en vez de create_pr/review_pr/merge_pr; namespacing por servicio (github_list_prs); devolver identificadores semánticos estables, no referencias internas opacas.

La capacidad de elegir bien la tool se degrada por encima de 30-50 tools disponibles. Con catálogos grandes se recomienda tool search. Repartir las tools entre varios servidores MCP conectados a la vez no soluciona nada: el modelo sigue viendo el total.

tool_choice: cuatro valores

Con any o tool la API hace prefill del mensaje del asistente, así que no habrá texto natural antes del tool_use. Si tu interfaz muestra ese texto como razonamiento visible, desaparece.

El uso paralelo de tools está activado por defecto; se desactiva con disable_parallel_tool_use: true dentro de tool_choice.

Client tools vs server tools

Client tools: las defines tú, la respuesta llega con stop_reason: "tool_use", tú ejecutas y devuelves tool_result. Incluye también las de esquema Anthropic como bash, text_editor, memory o computer.
Server tools: se ejecutan en la infraestructura de Anthropic dentro de la misma request, sin ida y vuelta por tu parte — búsqueda web, web fetch, ejecución de código, conector MCP.

2 · Subagentes y orquestación multi-agente

Arquitectura hub-and-spoke: un coordinador gestiona toda la comunicación entre subagentes, el manejo de errores y el enrutado de información. Se elige por observabilidad y control, no por ahorro — los sistemas multi-agente consumen del orden de 15× los tokens de un chat (los agentes simples, ~4×). Por eso solo se justifican en tareas de alto valor.

Lo que más se pregunta: el aislamiento de contexto

Consecuencia práctica: si el subagente de síntesis produce informes vacíos de detalle, casi siempre es porque el coordinador no incluyó los hallazgos previos en su prompt. Y al pasar contexto entre agentes conviene usar formatos estructurados que separen contenido de metadatos (URLs de origen, nombres de documento, páginas) para no perder la atribución.

Spawning y paralelismo

• La tool de spawn debe estar en allowedTools o la invocación se deniega.
• Paralelizar = emitir varias llamadas de spawn en una sola respuesta del coordinador. Una por turno es ejecución secuencial disfrazada.
• AgentDefinition: obligatorios description y prompt. Opcionales: tools, disallowedTools, model (incluido 'inherit'), skills, memory, mcpServers, maxTurns, effort, permissionMode. Si omites tools, hereda todas las disponibles.
• Los agentes definidos programáticamente tienen precedencia sobre los del filesystem con el mismo nombre.

Diseño del coordinador

Prompts de objetivos y criterios de calidad, no de pasos procedimentales, para que los subagentes se adapten. El coordinador debe seleccionar dinámicamente qué subagentes invocar según la complejidad de la consulta, en vez de recorrer siempre el pipeline completo, y particionar el alcance para minimizar duplicación. El fallo típico es una descomposición demasiado estrecha que deja lagunas: se corrige con un bucle donde el coordinador evalúa la síntesis, detecta huecos y re-delega con queries dirigidas.

Cifras del sistema de investigación de Anthropic

• Multi-agente (Opus como lead, Sonnet como subagentes) superó al single-agent en 90,2% en su eval interna.
• Tres factores explican el 95% de la varianza de rendimiento; el uso de tokens por sí solo explica el 80%. Los otros dos: número de tool calls y elección de modelo.
• Reglas de escalado del prompt del lead: dato simple = 1 agente y 3-10 tool calls; comparación directa = 2-4 subagentes con 10-15 calls cada uno; investigación compleja = más de 10 subagentes.
• El lead lanza 3-5 subagentes en paralelo y cada uno usa 3+ tools en paralelo: hasta 90% menos tiempo en consultas complejas.
• Cada subagente puede gastar decenas de miles de tokens y devolver un resumen destilado de 1.000-2.000 tokens.

3 · Workflow vs agente: los cinco patrones

Criterio: los workflows dan predictibilidad y consistencia en tareas bien definidas; los agentes se eligen cuando hace falta flexibilidad y decisión dirigida por el modelo a escala. Y la recomendación previa a todo: para muchas aplicaciones basta con optimizar una sola llamada con retrieval y ejemplos in-context. Añadir complejidad solo cuando mejore el resultado de forma demostrable.

El bloque base de todo es el augmented LLM: modelo + retrieval + tools + memoria.

Tres principios de cierre: simplicidad, transparencia (mostrar los pasos de planificación) y diseño cuidadoso de la ACI (agent-computer interface).

4 · Context engineering

Context engineering = curar y mantener el conjunto óptimo de tokens durante la inferencia. Es la progresión natural del prompt engineering, que se limitaba a escribir instrucciones. Principio guía: el conjunto más pequeño posible de tokens de alta señal.

Las tres técnicas para tareas largas, y cuándo cada una

Compaction

Se pasa el historial al modelo para que lo resuma. Preserva decisiones arquitectónicas, bugs sin resolver y detalles de implementación; descarta tool outputs redundantes. En Claude Code continúa con el contexto comprimido más los cinco archivos accedidos más recientemente. Al afinarla: primero maximizar recall, después iterar precisión.

Tool result pruning

«La forma más segura y ligera de compactación es el tool result clearing». El razonamiento oficial: una vez que una tool se llamó hace mucho, el agente no necesita volver a ver su resultado crudo.

Just-in-time vs monolítico

En JIT el agente mantiene identificadores ligeros (rutas, queries guardadas, links) y carga los datos en runtime con tools, en vez de precargarlo todo. Ventajas: descubrimiento progresivo, y los metadatos como señal (nombres, jerarquía de carpetas, timestamps). Contrapartida reconocida: la exploración en runtime es más lenta que el retrieval precomputado. Claude Code usa un modelo híbrido: CLAUDE.md se carga por adelantado, glob y grep recuperan just-in-time.

5 · Claude Code: memoria, permisos, hooks, sesiones

Ojo al reparto: en el Developer pesa solo 3,1%. Si es tu terreno diario, es justo donde no debes gastar tiempo de estudio.

Jerarquía de CLAUDE.md

Orden de alcance: managed policy → usuario (~/.claude/CLAUDE.md) → proyecto (./CLAUDE.md) → local (./CLAUDE.local.md).

Precedencia de settings (distinta de la de CLAUDE.md)

Managed (no anulable) → argumentos de CLI → local → proyecto → usuario. Las reglas de permisos se fusionan entre scopes en vez de sobrescribirse.

Permisos

Tres tipos: allow / ask / deny. Se evalúan en orden deny → ask → allow; el primero que casa decide y la especificidad no altera ese orden. Un deny con nombre desnudo (Bash) elimina la tool del contexto; con specifier (Bash(rm *)) bloquea solo las coincidencias.

Modos: default, acceptEdits, plan, auto, dontAsk, bypassPermissions. Plan mode bloquea ediciones hasta que apruebas el plan: su valor está en tareas de alto impacto con incertidumbre sobre el alcance del cambio.

Hooks

Eventos principales: PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStart/SubagentStop, PreCompact, SessionStart/SessionEnd, Notification, Setup.

• PreToolUse devuelve permissionDecision: allow, deny, ask o defer. Un deny impide la ejecución y Claude recibe el rechazo como tool result.
• PostToolUse puede añadir contexto o reemplazar la salida antes de que Claude la vea.
• Los hooks corren en tu proceso, fuera del context window: no consumen contexto salvo lo que devuelvan.
• Exit code 2 = error bloqueante, no anulable ni con un allow.
• Silencio no es aprobación: un hook puede denegar, pero callarse deja seguir el flujo normal de permisos.

Sesiones: tres mecanismos distintos

Headless

-p/--print con --output-format text|json|stream-json, --allowedTools, --continue/--resume. Es la vía para CI y automatización.

6 · Model Context Protocol

Arquitectura

Un MCP Host (la aplicación de IA) crea un MCP Client por cada MCP Server, con conexión dedicada 1:1. Dos capas: data layer (JSON-RPC 2.0, primitivas, notificaciones) y transport layer (framing, canales, autorización).

Las tres primitivas de servidor y quién las controla

Métodos: tools/list, tools/call; resources/list, resources/read; prompts/list, prompts/get. Los recursos llevan URI única y MIME type, en dos patrones: Direct Resources (URI fija) y Resource Templates (URI parametrizada).

Transportes

Dos estándar: stdio (JSON-RPC delimitado por newline sobre un subproceso que lanza el cliente) y Streamable HTTP (POST a un endpoint único; respuesta JSON o stream SSE).

Autorización

• Es opcional y aplica a transportes HTTP. stdio no debería usarla: toma credenciales del entorno.
• El MCP Server actúa como OAuth 2.1 Resource Server; el cliente como OAuth 2.1 Client.
• PKCE obligatorio. El token va siempre en cabecera Authorization: Bearer, nunca en query string.
• Códigos: 401 no autorizado o token inválido, 403 scopes insuficientes, 400 request malformado.

MCP dentro de Claude Code

Tres scopes: local (por defecto, por máquina), project (.mcp.json versionado en el repo, requiere aprobación interactiva la primera vez), user (todos tus proyectos). Precedencia local > project > user.

Nomenclatura: tools = mcp__servidor__tool; prompts = slash commands /mcp__servidor__prompt; resources = menciones @servidor:protocolo://ruta.

7 · Skill, MCP, hook o CLAUDE.md: el árbol de decisión

Coste de contexto de cada mecanismo

• CLAUDE.md: contenido completo en cada request.
• Skills: solo las descripciones al inicio.
• MCP: nombres de tools al inicio, esquemas diferidos.
• Subagentes: contexto aislado.
• Hooks: cero, salvo que devuelvan output.

Agent Skills: progressive disclosure en tres niveles

Frontmatter obligatorio del estándar: solo name y description. description ≤1024 caracteres, en tercera persona, y debe decir qué hace y cuándo usarla. Cuerpo por debajo de 500 líneas.

8 · Messages API, errores, streaming y batch

El dominio más pesado del Developer con diferencia. Buena parte es ingeniería de software genérica: puntos baratos.

Estructura básica

POST /v1/messages. Obligatorios: model, messages, max_tokens.

Errores

Los SDK oficiales reintentan fallos transitorios con backoff exponencial, 2 reintentos por defecto, respetando retry-after. Toda respuesta trae cabecera request-id.

Streaming

Secuencia: message_start → por cada bloque content_block_start + N content_block_delta + content_block_stop → message_delta → message_stop. Los usage del message_delta son acumulativos.

Las llamadas no-streaming están limitadas a un timeout de 10 minutos. Para operaciones largas: streaming o Batch.

Message Batches API

• Descuento del 50% sobre input y output.
• Límite: 100.000 requests o 256 MB, lo que se alcance primero.
• La mayoría termina en menos de 1 hora; los resultados están disponibles al completar o a las 24 h, lo que ocurra antes. Los batches expiran si no completan en 24 h.
• Resultados descargables durante 29 días.
• Estados del batch: solo in_progress y ended. Por request: succeeded, errored, canceled, expired (los tres últimos no se facturan).
• No soporta stream: true. El progreso se sigue por los contadores del batch.
• Se recomienda TTL de caché de 1 hora, porque suelen tardar más de 5 minutos.

9 · Modelos, thinking, effort y tokens

Criterio de selección

Thinking

• Adaptive thinking: el modelo decide cuándo y cuánto pensar. En los modelos actuales está siempre activo sin configuración.
• Extended thinking con budget_tokens es el mecanismo antiguo, deprecado y rechazado con 400 en los modelos recientes.
• Facturación: los tokens de razonamiento se facturan como output y cuentan contra max_tokens, aunque el texto no se devuelva. Se cobran los tokens generados, no los del resumen visible.
• Los bloques thinking llevan signature y deben devolverse sin modificar, o 400.

Effort

Niveles max, xhigh, high, medium, low, con default high. Es una señal conductual, no un presupuesto estricto, y afecta a todos los tokens incluidas las llamadas a tools.

Tokens y límites

• POST /v1/messages/count_tokens es gratuito, con rate limits independientes de los de creación de mensajes. Devuelve una estimación.
• Rate limits por organización y usage tier, medidos en RPM, ITPM y OTPM.
• ITPM es cache-aware: cuentan input_tokens + cache_creation_input_tokens; cache_read_input_tokens no cuenta en la mayoría de modelos.
• max_tokens no influye en el cálculo de OTPM: se cuentan los tokens realmente generados.

10 · Prompt caching

Jerarquía del prefijo

tools → system → messages, hasta el bloque marcado inclusive. Consecuencia: cambiar las tools invalida todo lo que hay por debajo. De ahí la disciplina de mantener el catálogo de tools estable en sesiones largas.

Otras invalidaciones: cambios de thinking o de effort invalidan messages; tool_choice e imágenes, solo messages. Poner un parámetro explícitamente en su valor por defecto equivale a omitirlo y no invalida.

La vida de la caché se mide desde el inicio de la request, y cada uso la refresca sin coste extra.

11 · Salida estructurada

Dos features: JSON outputs (schema en la configuración de salida) y strict tool use. El mecanismo es constrained decoding: la gramática garantiza el cumplimiento del schema, sin reintentos.

Detalles finos

• Orden de propiedades: se respeta el del schema, pero las requeridas van primero. Si el orden importa, márcalo todo como required.
• Grammar caching: la primera request con un schema nuevo tiene latencia extra de compilación; se cachea 24 h desde el último uso. Cambiar solo name o description no la invalida.
• Structured outputs inyecta un system prompt adicional y cambiar el formato invalida el prompt cache del hilo.
• Citations + structured outputs = 400. Son incompatibles.

Consistencia sin schema

Cuando no hay schema, la técnica más efectiva es restringir con ejemplos: la doc dice explícitamente que es más efectivo que las instrucciones abstractas. Los adjetivos describen una aspiración; los ejemplos la definen.

12 · Evals y alucinaciones

Criterios de éxito

Deben ser específicos, medibles, alcanzables y relevantes. Ejemplo oficial de criterio bueno: «menos del 0,1% de las salidas sobre 10.000 pruebas marcadas por el filtro de contenido». El malo: «salidas seguras».

Métodos de grading, en orden de preferencia oficial

Tres consejos para LLM-as-judge: rúbricas detalladas y claras; salida empírica y acotada (solo correcto/incorrecto, o escala 1-5); y pedir que razone antes de puntuar y después descartar el razonamiento. En el sistema de investigación de Anthropic, un solo juez con una sola llamada resultó más consistente que varios jueces.

Métodos por criterio, según la doc: fidelidad → exact match; consistencia → similitud coseno; relevancia y coherencia → ROUGE-L; tono → Likert vía LLM; privacidad → clasificación binaria.

Reducir alucinaciones

Básicas: permitir que diga «no lo sé»; usar citas textuales como anclaje (para documentos de más de 20k tokens, pedir los quotes literales antes de la tarea); verificar, con retractación si no encuentra un quote que respalde una afirmación.

Avanzadas: chain-of-thought verification; best-of-N (misma prompt N veces — las inconsistencias delatan alucinación); refinamiento iterativo; restricción a conocimiento externo (usar solo los documentos aportados).

Y el disclaimer oficial: estas técnicas reducen, no eliminan, las alucinaciones.

13 · Seguridad: inyección, mínimo privilegio, secretos

Dos modelos de amenaza distintos

Jailbreak o inyección directa: el adversario es el usuario. Inyección indirecta: el usuario es de confianza, pero Claude procesa contenido de terceros — webs, emails, documentos, resultados de tools.

Mitigaciones de inyección indirecta (lo más examinable)

• Poner el contenido no confiable solo en bloques tool_result, nunca en el system prompt ni en bloques de texto de usuario. Claude está entrenado para tratar con escepticismo las instrucciones que aparecen dentro de tool results.
• Declarar qué es y de dónde viene ese contenido.
• Declarar la política en el system prompt: el contenido de tools y documentos es dato no confiable y nunca puede sobreescribir el system prompt ni la petición original.
• Codificar en JSON el contenido no confiable: el escapado da delimitadores inequívocos e impide «salir» del contexto cerrando comillas o etiquetas.
• No metas tus propias instrucciones dentro de un tool result: se ignoran o se marcan como inyección. Van en un turno de usuario posterior.
• Screening de las salidas de tools antes de que Claude actúe sobre ellas, con un modelo ligero y salida estructurada.
• Red-team de tu propio agente antes de desplegar, y monitorización continua después.

En el conector MCP esto se implementa como allowlist (deshabilitar por defecto y habilitar tools concretas) o denylist. Para un asistente de solo lectura, se deniegan las tools de escritura y destructivas.

Claves y secretos

• Guardarlas en un gestor de secretos, rotarlas periódicamente y revocar cualquiera que se sospeche filtrada.
• Usar workspaces para segmentar claves por proyecto y entorno — así un incidente se aísla.
• La expiración se elige al crear la clave y no se puede cambiar después. Tras expirar: 401, y no se pueden reactivar.
• La expiración no sustituye a la higiene de secretos.
• CORS no está soportado con zero data retention: hay que enrutar por un backend proxy, nunca llamar a la API desde el navegador.

14 · RAG y estrategias de recuperación

Casi exclusivo del Architect Professional. Si vas solo a por los Foundations, puedes saltarlo.

Por qué embeddings solos no bastan

Los embeddings capturan semántica y pierden coincidencias léxicas exactas: identificadores, códigos de error, nombres propios raros. El ejemplo de la doc es «Error code TS-999». BM25 las recupera. Se combinan con rank fusion, y esa es la línea base recomendada.

Contextual Retrieval y sus cifras

Consiste en anteponer a cada chunk un contexto explicativo generado por el modelo (típicamente 50-100 tokens) antes de embeberlo y de indexarlo en BM25. Medido como reducción de fallos de recuperación sobre una línea base del 5,7%:

Los beneficios se acumulan. Reranking: recuperar top-150, rerankear y pasar top-20 al modelo. Top-20 rinde mejor que top-10 y que top-5.

Anthropic no ofrece modelo de embeddings propio: la doc recomienda proveedores externos. Y la regla final del post: «Always run evals».

15 · Compliance: ZDR, HIPAA, retención

Certificaciones

HIPAA-ready (con BAA), ISO 27001:2022, ISO/IEC 42001:2023 (gestión de sistemas de IA), SOC 2 Tipo I y II. FedRAMP no está en esa lista corporativa: llega por terceros (Bedrock en GovCloud, Claude for Government).

Zero Data Retention

• Se habilita por organización y no se extiende automáticamente a otras organizaciones de la misma cuenta.
• No elegibles: procesamiento por lotes (retiene resultados), Files API, ejecución de código, conector MCP, Agent Skills, y CORS.
• Los datos retenidos nunca se usan para entrenar sin permiso expreso.

HIPAA

• Requiere BAA firmado, se aplica a nivel de organización y una vez habilitado es permanente: un admin no puede desactivarlo. Para cargas HIPAA y no-HIPAA hacen falta organizaciones separadas.
• Si tienes HIPAA, no necesitas además ZDR.

Retención pese a cualquier acuerdo: si el contenido lo marcan los sistemas automáticos de trust & safety o hay requerimiento legal, se puede retener hasta 2 años.

En Bedrock o Google Cloud el proveedor cloud es el data processor, no Anthropic: hay que consultar su documentación.

17 · Claude Code en equipo: permisos, revisión y portabilidad

Este bloque vale casi cuatro veces más en el Architect Foundations que en el Developer. Estúdialo pensando en el CCAR-F.

Y el matiz que completa la respuesta: una regla deny sobre la ruta que no se debe tocar, puesta a nivel de proyecto o de empresa, cubre el hueco que el modo por sí solo no cubre. Modo y reglas son capas distintas: el modo decide cuánto pregunta, la regla decide qué es directamente inalcanzable.

Revisión de código con IA

Dos consecuencias de diseño: la puerta humana va donde un hallazgo se convierte en una acción difícil de revertir, no en cada comentario; y la forma de subir la precisión del revisor es darle las convenciones del equipo que si no tendría que adivinar. Es exactamente el escenario 5 del CCAR-F (Claude Code en CI/CD), donde el objetivo declarado es dar feedback accionable y minimizar falsos positivos.

Portabilidad de skills

El mismo SKILL.md corre en Claude Code, en la Messages API y a través del Agent SDK, pero cada runtime lo carga y lo aísla distinto: descubrimiento por filesystem en Claude Code, beta headers y contenedor de ejecución de código en la API, y setting sources en el SDK.

• Una skill acotada a una descripción clara y libre de suposiciones sobre el entorno local se porta limpia. Una que da por hecho la terminal en la que se escribió, no.
• En todos los runtimes, los subagentes arrancan limpios: no precargan skills automáticamente.

Los cuatro mecanismos de contexto duradero

Que el montaje sea compartible

Un plugin que referencia una ruta absoluta al directorio personal del autor se instala en una máquina y falla en todas las demás. Reglas: rutas relativas a la raíz del proyecto en todo lo que se vaya a compartir, requisitos de variables de entorno documentados o validados en la instalación, y probar la instalación desde una máquina limpia antes de distribuir.

18 · MCP: transporte, scope y requisitos de empresa

De ahí sale la frase que más se presta a ítem: un servidor stdio declarado en .mcp.json es una configuración que parece compartible y no lo es. El fichero viaja con el repo, pero el proceso que lanza solo existe en la máquina del que lo escribió. Un servidor de equipo requiere transporte HTTP y scope de proyecto o de empresa: las dos cosas a la vez.

Los cuatro requisitos que trae un cliente regulado

19 · Números que caen

Repaso rápido la víspera. Si te sabes esta tabla, tienes cubierta la parte memorística de los cuatro exámenes.

20 · Trampas por versión

La documentación de Anthropic se reescribe deprisa. Estos puntos aparecen en material de terceros con la respuesta antigua, que hoy es incorrecta. Son los ítems donde más gente falla por haber estudiado en blogs.