DEV Community: Khavel

Backtest 63.7%, production AUC 0.51 - a postmortem

Khavel — Sat, 05 Sep 2026 23:07:00 +0000

Originally published at nbaproplab.com/learn/model-postmortem.

A model that looks excellent offline and random in production is usually blamed on the serving code. Ours was not: the two computations matched to 2e-16. The cause was a calibration snapshot whose export query nobody wrote down.

What we built

We score NBA and WNBA player props through seven independent blocks: player form, matchup, game context, market line, teammate synergy, analysis quality and external signals. Each returns a 0-100 score with a confidence index, and a confidence-weighted mean produces the final score that decides whether a pick is published.

On top of that engine we fitted a logistic meta-learner. It takes the seven block scores plus the pick direction and outputs a single calibrated probability that the pick hits. The idea was sound: a weighted mean treats every block as positively predictive, while signed coefficients let an anti-predictive block subtract instead.

Offline it looked excellent. The top tier came out at a 63.7% hit rate with an AUC of 0.56. We deployed it in shadow mode, writing its probability next to every saved pick without letting it influence anything, and planned the switch for the following release.

What went wrong

The switch never happened, because the backtest never reproduced.

Measured against clean live-only data, the deployed model scored an AUC of about 0.51. That is a coin flip. Worse than the flat result, the ordering was inverted: the band the model was most confident about hit 53%, while the band immediately below it hit 67.6%. A model whose top tier underperforms its second tier is not a weak model, it is a broken one.

The obvious suspect is the serving path, so we checked it first. We recomputed the probability for saved picks using the production code and compared it against the training-time computation. The difference was 2e-16, which is floating point noise. The code was correct.

The actual cause: a CSV nobody documented

The training set had been exported once, into a file, from a database snapshot. The export query was never recorded. Neither was the date window, which turned out to be a narrow slice of spring. Nobody wrote down how the file had been produced, so nobody could check whether it matched what production actually served.

It did not match. The training population and the serving population were different, which is the textbook train-serve mismatch. What made it survive review for weeks was not the mismatch itself but its invisibility: with no provenance recorded, there was nothing to compare against, and the impressive offline numbers had no way of being challenged.

What we changed

The model is parked. It is still computed and stored next to every pick, and it still drives nothing user-facing.
Provenance is mandatory. Any dataset that informs a decision carries its exact query, its date window and its reason in the changelog, in the same commit that uses it. If it is not written down, it did not happen.
The replacement only graduates on forward data. A gradient boosting combiner runs as a frozen forward shadow, writing predictions to its own table. It replaces the live engine only if its volume-matched top tier stays ahead over several hundred forward-settled picks. No backtest can promote it.
Calibration is monitored daily. Brier score, log loss, AUC and per-tier hit rates over a trailing window, with the window floored at the model finalize date so training data cannot leak into the metric that is supposed to police it.

The numbers that replaced it

Population	Settled picks	Hit rate	Note
Everything the engine graded	58,459	54.3%	Includes internal tiers that are never published
Top tier, live only, since April 2026	1,357	55.6%	Break-even at -110 odds is 52.4%
Top tier, 2026 WNBA season	546	62.3%	Fully live: the season began after the backtest cutoff
Top tier, full public record	3,340	62.5%	Includes the backtested span up to 2026-04-02

Every settled pick is public and filterable by league, tier and date at nbaproplab.com/track-record, and the raw JSON is open at /api/v1/track-record with no key and no signup. Figures cover 2026-01-01 to 2026-08-30.

If you build these things

A public record that shows only the good parts is marketing, not evidence. We publish the misses next to the hits for the same reason we published this postmortem: a claim nobody can falsify is worth nothing.

If you are fitting a meta-learner on top of your own scoring stack, the cheapest insurance is not a better model. It is writing down, in the commit that uses it, exactly which rows your training file contains and how you got them.

Memoria de agentes de IA: arquitectura, privacidad y borrado en producción

Khavel — Tue, 01 Sep 2026 09:08:47 +0000

La keyword principal es memoria de agentes de IA; la intención es práctica: un equipo busca hacer que un agente recuerde lo útil entre conversaciones sin crear un historial infinito, compartido o imposible de borrar.

TL;DR

Separa tres cosas. El estado de sesión mantiene una tarea en curso; la memoria persistente conserva datos seleccionados entre sesiones; RAG recupera conocimiento documental externo. Parecen similares porque los tres aportan contexto, pero tienen propietarios, ciclos de vida y fallos distintos.

Mi postura: no empieces por una base vectorial ni por un extractor automático de preferencias. Empieza por una tabla de memoria con ámbito de tenant, dueño, tipo, procedencia, caducidad y borrado. Si no puedes responder quién escribió un dato, por qué se recuperó y cómo se elimina, todavía no tienes memoria de producción.

Qué es memoria de un agente — y qué no

La memoria de un agente es información conservada para cambiar de forma útil una decisión futura. Una preferencia explícita como ‘responde en español’, una restricción de cuenta o el resumen de un ticket abierto pueden ahorrar repetición. Un transcript completo, un log de tool calls o una copia del manual interno no se convierten automáticamente en memoria solo por persistirlos.

El estado corto vive dentro de una conversación, thread o ejecución. LangGraph lo modela como estado persistido por thread; un store de largo plazo cruza threads mediante namespaces. RAG tampoco es memoria de usuario: responde ‘qué dice el corpus permitido’, mientras la memoria responde ‘qué dato estable y autorizado tengo sobre este actor o tarea’.

La memoria útil entra por una puerta de extracción, se recupera con filtros y conserva una salida explícita: caducidad o borrado.

El modelo de datos mínimo

Una memoria durable necesita más que text y un embedding. Guarda tenant_id, actor_id, memory_id, kind, content, source, confidence, created_at, expires_at, deleted_at y una versión de extracción. Así puedes restringir la query antes de la similitud, explicar el origen y cambiar el extractor sin fingir que todas las notas son equivalentes.

kind evita mezclar hechos, preferencias, resúmenes y reglas operativas. Una preferencia explícita puede entrar con alta confianza; una inferencia de un modelo debería tener vida corta, fuente y una revisión más estricta. La procedencia no es burocracia: el agente debe poder mostrar, corregir o ignorar una memoria.

Código: contrato de escritura y recuperación

memory_contract.py

ALLOWED_SOURCES = {"explicit_user", "trusted_system"}<br>def can_persist(m):<br>    return (m.source in ALLOWED_SOURCES and m.kind in {"preference", "fact", "task_summary"} and len(m.content) <= 500)<br><br>def retrieval_scope(identity):<br>    # identity comes from authentication, never from prompt text<br>    return {"tenant_id": identity.tenant_id, "actor_id": identity.actor_id, "not_expired": True, "limit": 4}<br><br># Apply this scope BEFORE vector similarity or model context injection.

El modelo puede proponer una candidata, pero identidad, tipos permitidos, tamaño, retención y filtros los decide el runtime autenticado. El tenant_id no se extrae del prompt ni se acepta como argumento de una tool generalista.

Aísla antes de buscar

La similitud vectorial debe ocurrir dentro de un ámbito ya autorizado. Primero filtra tenant, actor, clase de memoria y vigencia; después calcula similitud; por último limita la cantidad de contexto. Hacerlo al revés convierte una búsqueda ‘inteligente’ en una fuga entre clientes.

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Lo que conviene comprobar

En una base relacional, Row-Level Security puede ser una segunda barrera para que una consulta mal construida no lea filas de otro tenant. No sustituye la autorización de aplicación, pero evita depender de que cada developer recuerde el WHERE tenant_id = ... correcto.

Los namespaces de LangGraph y los filtros de metadata de AgentCore expresan el mismo principio: la memoria no es una colección global. Diseña la clave de aislamiento antes de escoger el motor.

Extrae poco, consolida con reglas

Hay dos momentos para crear memoria. En el hot path, el agente propone o guarda un dato antes de responder: es inmediato, pero añade latencia y riesgo. En segundo plano, un job revisa eventos cerrados y consolida candidatos: permite mejores reglas, aunque el recuerdo llega después. Para preferencias o acciones sensibles, prefiero confirmación explícita.

Consolidar significa decidir entre añadir, actualizar, ignorar o expirar. AgentCore documenta estrategias distintas para semántica, preferencias, resúmenes y episodios; incluso si no usas AWS, cada tipo necesita reglas de extracción y de conflicto distintas.

Da fecha de caducidad a lo que puede quedar obsoleto: estado de un incidente, proyecto activo, configuración temporal o inferencias. Una memoria sin expires_at suele vivir más que su verdad. Para datos de alto impacto, ‘olvidar’ debe eliminar texto, embedding e índices derivados.

La memoria es input no confiable

Una memoria recuperada se parece a una tool response: puede contener instrucciones hostiles, datos equivocados o una preferencia revocada. No la concatentes como si fuera una orden del sistema. Etiquétala como contexto, conserva procedencia y no permitas que una frase almacenada habilite pagos, despliegues o acceso a datos.

El riesgo no se limita a un atacante. Un extractor puede convertir ‘estoy de viaje esta semana’ en una preferencia permanente; un tool puede incorporar texto de una web; una migración puede duplicar registros. La defensa es la misma: allowlist de tipos, confianza limitada, auditoría de escritura y evaluación de conflictos.

Añade casos de memoria en tus evals: dato correcto, dato caducado, dato de otro tenant, instrucción adversarial persistida, corrección explícita y borrado. Mide no solo si el agente recuerda, sino si ignora un recuerdo cuando su procedencia, ámbito o fecha no permiten usarlo.

Privacidad, retención y coste

Persistir memoria en tu base de datos no elimina los datos que envías al proveedor de modelo. Si reinyectas una preferencia en cada prompt, ese contenido sigue sujeto a los controles de datos y retención del proveedor. OpenAI, por ejemplo, distingue logs de abuse monitoring de application state y documenta opciones por endpoint; revisa el contrato del proveedor que realmente usas.

Minimiza antes de cifrar. No guardes secretos, identificadores completos, transcripciones crudas ni atributos sensibles si el caso de uso funciona con una preferencia breve y controlada. Cifrado, acceso mínimo y auditoría son necesarios; no justifican coleccionar datos que el agente no necesita.

El coste tiene tres partes: extracción, embeddings/almacenamiento y tokens al recuperar. Recuperar ocho recuerdos vagos puede empeorar una respuesta y subir coste. Empieza con tres o cuatro registros muy relevantes y mide si cambian la decisión.

Observabilidad y evals

Registra para cada turno: memoria candidata, decisión de persistencia, versión de extractor, namespace, filtros aplicados, IDs recuperados, score, caducidad, tokens añadidos y si la respuesta la usó. Redacta contenido sensible en los logs; los IDs y metadatos suelen bastar para depurar.

Una métrica útil es la tasa de recuperación accionable: de las memorias inyectadas, cuántas cambiaron una respuesta o tool call de forma correcta. Otra es la tasa de corrección o borrado. Si hay muchas correcciones, el extractor está promoviendo ruido o las reglas son demasiado amplias.

Conecta esos eventos a tus trazas. La observabilidad GenAI explica la ejecución; aquí debes poder responder otra pregunta: ‘¿qué recuerdo entró y por qué este agente lo creyó?’. Sin esa relación, una personalización errónea no se puede reproducir.

Plan de adopción en una semana

Día 1: elige un único caso de bajo riesgo, como idioma, formato de salida o resumen de ticket. Escribe qué dato puede guardar y qué queda prohibido.

Día 2: modela tenant, actor, tipo, origen, caducidad y borrado; obliga a que identidad venga de autenticación, no del prompt.

Día 3: implementa lectura filtrada y limitada con un test de aislamiento cruzado y otro de expiración.

Día 4: permite candidatos de escritura con allowlist y confirmación para preferencias; rechaza tool output y texto web por defecto.

Día 5: crea listar, corregir y borrar, incluyendo embeddings e índices derivados; deja evidencia auditable sin conservar contenido eliminado.

Día 6: ejecuta evals con memoria correcta, falsa, caducada, revocada y adversarial; mide utilidad, latencia y tokens.

Día 7: activa para una cohorte pequeña y revisa recuperaciones, correcciones y costes antes de ampliar tipos de memoria o usuarios.

Errores que no aceptaría en producción

Usar todo el historial del chat como memoria de largo plazo.
Dejar que el modelo elija tenant, usuario o namespace desde lenguaje natural.
Buscar por embedding antes de aplicar filtros obligatorios.
Persistir tool output, páginas web o texto de usuario sin tipo, fuente y política de promoción.
No tener expires_at, borrado verificable ni gestión de correcciones.
Inyectar recuerdos recuperados como instrucciones privilegiadas.
Medir solo recall y no fugas, correcciones, coste ni decisiones erróneas.

Preguntas frecuentes

¿Qué es la memoria de un agente de IA?

Es un conjunto selectivo de datos persistentes que puede cambiar una decisión en una sesión futura. No es el historial completo ni un RAG documental; debe llevar ámbito, procedencia, tipo y ciclo de vida.

¿Cuál es la diferencia entre estado y memoria a largo plazo?

El estado pertenece a una conversación o ejecución y suele recuperarse por thread. La memoria a largo plazo cruza sesiones y debe aislarse por tenant, usuario o aplicación con namespaces y controles explícitos.

¿Necesito una base vectorial para memoria de agentes?

No siempre. Preferencias y claves estructuradas se resuelven mejor con consultas exactas. Usa búsqueda semántica solo cuando el tipo de recuerdo y el volumen justifican recuperar por significado, siempre después de filtrar ámbito y vigencia.

¿Cómo evito que un agente recuerde datos de otro cliente?

Obtén identidad desde autenticación, filtra tenant y actor antes de la similitud, limita resultados y añade una barrera de datos. Prueba explícitamente la fuga cruzada en CI.

¿Cuánto tiempo debe vivir una memoria?

Lo mínimo que haga útil el caso. Preferencias estables pueden durar más con control de corrección; contexto de tareas e inferencias necesitan expiración o revisión.

¿La memoria persistente es segura frente a prompt injection?

No por sí sola. Todo recuerdo recuperado es input no confiable: conserva fuente, etiqueta contexto, evita que habilite acciones y evalúa instrucciones adversariales o datos envenenados.

Cómo añadir memoria segura a un agente de IA

Acotar el caso. Elige una preferencia o resumen de bajo riesgo y define qué datos nunca se guardan.
Definir el ámbito. Obtén tenant y actor desde la identidad autenticada, no desde texto libre ni argumentos de una tool.
Modelar procedencia. Guarda tipo, fuente, confianza, fecha, caducidad y versión del extractor junto al contenido.
Filtrar antes de recuperar. Aplica tenant, actor, tipo y vigencia antes de búsqueda semántica; devuelve pocos resultados.
Controlar escritura. Permite solo fuentes y tipos en allowlist; confirma preferencias importantes y procesa candidatos inciertos en segundo plano.
Dar salida al dato. Implementa listar, corregir, expirar y borrar eliminando también índices y embeddings derivados.
Evaluar adversarialmente. Prueba recuerdos caducados, cruzados, falsos, revocados y hostiles; mide utilidad, fugas y coste.
Desplegar con trazas. Registra decisiones e IDs redactados, revisa una cohorte pequeña y amplía solo cuando los datos sean defendibles.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Pydantic AI: cómo crear agentes Python tipados sin perder control en producción

Khavel — Mon, 31 Aug 2026 09:10:03 +0000

Pydantic AI no es otro wrapper bonito para prompts. Su valor está en obligarte a tratar un agente como software: contratos de salida, dependencias explícitas, herramientas validadas, límites de uso, trazas y evals.

Pydantic AI es un framework Python para construir aplicaciones y agentes de IA con el estilo mental de FastAPI: tipos, validación, inyección de dependencias, herramientas declarativas, salida estructurada, observabilidad y evals.

TL;DR

La keyword principal es Pydantic AI agentes; la intención de búsqueda en español es aprender cuándo usar Pydantic AI y cómo montar un agente Python de producción con output tipado, tools, límites de uso, MCP y trazas.

Mi postura: Pydantic AI tiene sentido cuando el agente va a tocar datos o decisiones reales. Si solo quieres un chat demo, cualquier wrapper sirve. Si necesitas que la salida sea validable, testeable y observable, aquí empieza a compensar.

Por qué Pydantic AI importa para devs Python

Una definición citable: Pydantic AI es un framework de agentes para Python que convierte prompts, herramientas, dependencias y resultados de modelos en contratos tipados que puedes validar, probar y observar como parte de una aplicación normal.

La mayoría de demos de agentes fallan por el mismo motivo: tratan el LLM como una caja mágica que devuelve texto. En producción eso no basta. Necesitas saber qué forma debe tener la respuesta, qué herramientas puede llamar, cuántas veces, con qué datos y bajo qué límites.

Pydantic AI ataca ese problema desde una idea muy pragmática: si ya usas Pydantic para validar entradas y salidas en APIs, usa el mismo músculo para validar decisiones generadas por modelos.

Recibe una lectura semanal de herramientas IA para devs

Si quieres seguir frameworks de agentes como Pydantic AI, OpenAI Agents SDK, Claude Agent SDK, MCP y evals sin leer veinte changelogs a la semana, DevAI Semanal te lo resume en un email de 5 minutos.

Suscribirme gratis

La arquitectura mínima de un agente serio

Un agente Pydantic AI razonable tiene cinco piezas. Primero, un Agent con instrucciones y modelo. Segundo, un output_type con un BaseModel que define qué debe devolver. Tercero, dependencias explícitas para pasar servicios, tenant, usuario o conexiones. Cuarto, tools con argumentos validados. Quinto, límites y observabilidad para no descubrir el coste en la factura.

La ventaja no es que el modelo sea más inteligente. La ventaja es que el contrato alrededor del modelo se vuelve más estrecho. Menos texto libre, menos estado implícito y menos magia escondida en el prompt.

La frontera sana: el LLM razona, pero tu aplicación define contratos, dependencias, tools permitidas, límites de uso y trazas revisables.

Primer ejemplo ejecutable: salida tipada

Este ejemplo no intenta ser sofisticado. La idea es mostrar el patrón: un BaseModel define la salida, el agente la valida y tu código consume result.output como objeto Python, no como JSON pegado con cinta.

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class ReviewDecision(BaseModel):
    verdict: str = Field(description="approve, request_changes or needs_human")
    risk: int = Field(ge=0, le=10)
    reasons: list[str]

agent = Agent(
    "openai:gpt-5.2",
    output_type=ReviewDecision,
    instructions=(
        "Eres un revisor senior. Devuelve una decision breve, "
        "un riesgo de 0 a 10 y razones accionables."
    ),
)

result = agent.run_sync(
    "El PR cambia autenticacion, no trae tests y toca sesiones."
)

decision = result.output
print(decision.verdict, decision.risk, decision.reasons)

Qué gana el output tipado

Ganas una frontera concreta entre IA y producto. Si el modelo responde con una forma inválida, no lo conviertes silenciosamente en estado de negocio. Lo validas, reintentas dentro del presupuesto o fallas de forma explícita.

Esto es especialmente importante en agentes que clasifican tickets, generan acciones, evalúan riesgos, enrutan incidencias, preparan PRs o deciden si una tarea necesita humano. En esos casos, texto bonito no es un contrato.

La documentación de Pydantic AI también remarca que el resultado conserva tipos genéricos, historial y uso de la ejecución. Esa metadata importa cuando quieres depurar por qué una decisión salió cara o mala.

Dependencias: no metas datos vivos en el prompt

El patrón correcto es pasar dependencias por deps, no pegar media base de datos en instrucciones. Las dependencias permiten que tools e instrucciones dinámicas accedan a servicios concretos con tipos claros: cliente HTTP, conexión a DB, tenant, usuario, feature flags o repositorio.

Esto reduce tres riesgos: fuga accidental de contexto, prompts imposibles de testear y herramientas que leen datos que no deberían. Si una tool necesita tenant_id, que venga de una dependencia controlada, no de un texto que el modelo puede reinterpretar.

Segundo ejemplo ejecutable: tool con deps y límite de uso

El siguiente patrón es el que usaría para un agente interno que consulta deuda técnica. La tool recibe argumentos validados, accede a servicios desde RunContext y la ejecución aplica límites para que una pregunta torpe no dispare diez llamadas innecesarias.

from dataclasses import dataclass

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext, UsageLimits

class Finding(BaseModel):
    file: str
    problem: str
    next_step: str

@dataclass
class RepoDeps:
    repo_name: str
    index: object

agent = Agent(
    "anthropic:claude-sonnet-4-6",
    deps_type=RepoDeps,
    output_type=list[Finding],
    instructions="Encuentra problemas concretos y devuelve acciones pequenas.",
)

@agent.tool
async def search_code(ctx: RunContext[RepoDeps], query: str) -> list[str]:
    """Busca fragmentos relevantes en el indice del repositorio."""
    return await ctx.deps.index.search(ctx.deps.repo_name, query, limit=5)

async def review(repo_index):
    deps = RepoDeps(repo_name="billing-api", index=repo_index)
    return await agent.run(
        "Busca riesgos en el modulo de invoices.",
        deps=deps,
        usage_limits=UsageLimits(request_limit=4, tool_calls_limit=3),
    )

Tools: la docstring también es interfaz

En Pydantic AI, las funciones registradas como tools exponen argumentos al modelo. Eso significa que nombres, tipos y docstrings son parte de la interfaz. Una tool vaga produce llamadas vagas.

Lo que conviene comprobar

Regla práctica: una tool debe hacer una cosa, aceptar pocos parámetros y devolver datos que no obliguen al modelo a inferir demasiado. Si devuelves una lista gigante de strings, has trasladado el problema al prompt. Si devuelves objetos pequeños y consistentes, reduces alucinaciones operativas.

También conviene separar tools de lectura y tools mutantes. Las primeras pueden tener permisos amplios dentro de un entorno controlado; las segundas necesitan scopes mínimos, logging y aprobación humana cuando tocan repos, tickets, cloud o datos de clientes.

MCP: úsalo para capacidades externas, no para saltarte diseño

Pydantic AI puede actuar como cliente MCP y conectar tools locales o remotas mediante MCPToolset o la capacidad MCP. Eso encaja muy bien con el ecosistema actual: servidores MCP para documentación, repos, observabilidad, datos internos o automatización.

Pero MCP no arregla una arquitectura mala. Si conectas diez servidores sin política, solo has dado más botones al modelo. La pregunta correcta es: qué tool necesita esta tarea, con qué transporte, con qué lifecycle, con qué credenciales y qué salida espero validar después.

Para equipos que ya usan MCP en Copilot, Claude Code o Cursor, Pydantic AI puede ser la capa Python donde conviertes esas capacidades en producto: controlas el cliente, los tipos, el flujo de ejecución y las pruebas.

Modelos y proveedores: no cases tu dominio con una API

Pydantic AI abstrae modelos y proveedores: puedes instanciar agentes con nombres tipo openai:gpt-5.2 o usar clases de modelo/proveedor más explícitas cuando necesitas Azure, OpenAI-compatible providers, LiteLLM, Ollama, GitHub Models u otro gateway.

Esto no significa que cambiar de modelo sea gratis. Cada proveedor tiene límites, perfiles, capacidades de herramientas y detalles de JSON schema. Pero sí te permite aislar el dominio de la aplicación del SDK de un proveedor concreto.

Mi recomendación: empieza con un proveedor explícito en configuración, registra métricas por modelo y guarda casos de evaluación. Cambiar de modelo sin evals es fe, no ingeniería.

Observabilidad y evals: el punto donde deja de ser demo

Pydantic AI se integra con Logfire y Pydantic Evals. Esa combinación importa porque los agentes fallan de formas no deterministas: hoy responden bien, mañana el modelo cambia, una tool tarda más, un prompt arrastra contexto viejo o un output validator empieza a reintentar demasiado.

Las evals no sustituyen tests unitarios. Sirven para otra capa: casos representativos, outputs esperados, evaluadores deterministas o LLM judges, métricas por experimento y comparación entre implementaciones.

Una batería mínima debería incluir: casos felices, inputs ambiguos, intentos de prompt injection, datos incompletos, límite de tools, errores de proveedor, salida inválida y ejemplos donde el agente debe decir necesita humano.

Durable execution: solo si el agente dura más que una request

Para tareas cortas, run_sync o run basta. Para flujos largos, multi-step o con reintentos de infraestructura, necesitas ejecución durable. La documentación de Pydantic AI cubre integraciones como Temporal, DBOS, Prefect y Restate.

No metas durable execution el primer día si no sabes todavía qué workflow quieres preservar. Primero define contrato de salida, tools, límites y evals. Después, si el agente tarda minutos, llama APIs externas o debe sobrevivir a caídas, añade durable execution.

Checklist de producción

Define output_type para cualquier decisión que consuma tu aplicación.
Pasa datos vivos por deps, no por prompts enormes.
Separa tools de lectura y tools mutantes.
Pon UsageLimits en runs que puedan llamar tools.
Registra modelo, tokens, tool calls, latencia, reintentos y coste.
Crea evals antes de cambiar de modelo o prompt principal.
Conecta MCP solo para capacidades concretas y auditables.
Haz que el agente pueda decir no sé o necesita humano.
Versiona prompts, schemas y datasets de evaluación junto al código.

Errores que evitaría

El primero es vender Pydantic AI como garantía de verdad. Validar estructura no valida factualidad. Un BaseModel puede contener basura perfectamente tipada si no hay tools, fuentes o evaluadores.

Lo que conviene comprobar

El segundo es meter todos los datos en instrucciones. Si el prompt contiene secretos, datos de cliente o reglas efímeras, cada run se vuelve más caro, menos auditable y más difícil de limpiar.

El tercero es conectar MCP como catálogo infinito. Un agente con demasiadas tools se parece a un junior con permisos de producción y una wiki enorme: quizá acierte, pero no es un control.

El cuarto es no medir reintentos de validación. Si tu schema es demasiado estricto o ambiguo, el agente puede gastar tokens intentando satisfacer una forma que el prompt no explica bien.

Cuándo elegir Pydantic AI frente a OpenAI o Claude SDK

Elige Pydantic AI si tu equipo trabaja en Python, ya usa Pydantic/FastAPI, necesita salida tipada, quiere cambiar de proveedor con menos fricción y va a tratar agentes como componentes de backend.

Elige el SDK nativo de OpenAI o Anthropic si necesitas exprimir una capacidad específica del proveedor, si tu app depende de una superficie muy concreta o si prefieres controlar directamente cada request.

La decisión práctica no es framework contra framework. Es capa de dominio contra API de proveedor. Pydantic AI brilla cuando quieres una capa de dominio estable por encima de modelos que van a cambiar.

Plan de adopción de una semana

Día 1: elige un caso acotado donde la salida pueda representarse como BaseModel: clasificación de tickets, revisión de riesgo, resumen técnico o extracción estructurada.
Día 2: escribe el agente con una sola tool de lectura y UsageLimits bajos. No conectes todavía acciones mutantes.
Día 3: añade diez casos de evaluación: cinco normales, tres ambiguos y dos hostiles.
Día 4: instrumenta trazas y registra uso por ejecución. Mira reintentos, tool calls y latencia antes de optimizar prompts.
Día 5: prueba un segundo modelo o gateway y compara evals. Si no puedes comparar, todavía no estás listo para producción. > ### Conclusión > > Pydantic AI es interesante porque baja los agentes al suelo: tipos, validación, dependencias, límites, trazas y evals. No promete que el modelo piense mejor. Promete que tu aplicación tenga mejores fronteras alrededor del modelo. > > Esa es exactamente la dirección correcta para equipos Python. Los agentes no deberían ser prompts sueltos con permisos. Deberían parecerse a servicios: contratos claros, herramientas pequeñas, límites explícitos, tests probabilísticos y logs que expliquen qué pasó cuando algo sale mal.

Preguntas frecuentes

¿Qué es Pydantic AI?

Pydantic AI es un framework Python para construir aplicaciones y agentes de IA con contratos tipados, herramientas validadas, dependencias explícitas, observabilidad y evals.

¿Pydantic AI reemplaza a OpenAI Agents SDK o Claude Agent SDK?

No necesariamente. Puede usarse como capa Python de dominio cuando quieres tipos, validación y portabilidad; los SDK nativos siguen siendo útiles para capacidades específicas del proveedor.

¿Pydantic AI soporta MCP?

Sí. Pydantic AI puede actuar como cliente MCP y conectar servidores locales o remotos para usar sus tools dentro de ejecuciones de agente.

¿La salida tipada evita alucinaciones?

No. Evita que la forma sea inválida, pero no garantiza que el contenido sea verdadero. Para factualidad necesitas fuentes, tools, validadores y evals.

¿Cuándo merece la pena usar Pydantic Evals?

Cuando vas a cambiar prompts, modelos, tools o workflows y necesitas comparar comportamiento con casos representativos, no solo confiar en una demo.

¿Pydantic AI sirve para producción?

Sí, si lo usas con límites de uso, observabilidad, evals, control de tools y revisión humana en acciones de riesgo. Sin eso, sigue siendo una demo con buen tipado.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Codex Skills: cómo crear workflows reutilizables sin inflar el contexto del agente

Khavel — Sun, 30 Aug 2026 13:37:44 +0000

Una Codex Skill es un directorio con un SKILL.md obligatorio y, cuando hace falta, scripts, referencias y assets. La keyword principal es Codex Skills; la intención es de implementación: un developer busca convertir un procedimiento repetido en un workflow que el agente pueda descubrir y ejecutar de forma consistente.

TL;DR

La idea clave es la carga progresiva: Codex conoce al principio solo el nombre y la descripción; lee las instrucciones completas cuando la tarea encaja. Las referencias largas no deben vivir en el prompt permanente. Se cargan solo desde el SKILL.md si el workflow las necesita. Eso conserva contexto para el código y evita que una 'ayuda' acabe empeorando el razonamiento.

Mi postura: empieza por una skill que elimine una decisión repetitiva y verificable —por ejemplo, reproducir un bug de CI o preparar una migración—, no por una que intente convertir al agente en el experto universal de tu empresa. Una skill buena reduce ambigüedad; una enorme solo es otro sitio donde esconder políticas contradictorias.

Qué es una skill y qué no es

Una skill empaqueta una capacidad orientada a tarea. Su description explica cuándo debe activarse; SKILL.md define el procedimiento; los scripts encapsulan operaciones frágiles; las referencias aportan detalle bajo demanda. El resultado ideal es que dos personas obtengan el mismo checklist y la misma evidencia aunque formulen la petición de manera distinta.

No es un sustituto de AGENTS.md. AGENTS.md contiene reglas duraderas del repositorio: comandos de test, fronteras de seguridad, convenciones y rutas sensibles. Una skill contiene un workflow especializado: qué hacer para esta clase de tarea y cómo comprobar que quedó bien. Si copias todo AGENTS.md dentro de cada skill, tendrás varias políticas que divergirán.

Tampoco es una vía para elevar permisos. Una skill puede recomendar un script, pero la sandbox, la política de aprobaciones y las credenciales de la sesión siguen siendo los controles que deciden qué puede ocurrir. Trata cada comando incluido como código de producción: revisable, acotado e idempotente cuando sea posible.

La skill decide el procedimiento; los controles de la sesión y la verificación siguen decidiendo si el cambio es aceptable.

La arquitectura mínima que sí escala

Deja SKILL.md corto y ejecutable. Si necesita 20 páginas de contexto, separa las ramas del proceso y coloca el detalle en references/. Si necesita copiar comandos complejos, muévelos a scripts/ y dale parámetros explícitos. El agente debe leer instrucciones, no reconstruir shell heredada a partir de párrafos vagos.

Usa agents/openai.yaml solo para metadata o dependencias de presentación cuando sea útil; no lo confundas con un mecanismo de autorización. La política real de red, filesystem y aprobación se aplica fuera del paquete. Esa separación evita el error clásico de creer que una lista declarativa protege un secreto o un servicio externo.

Una estructura pequeña suele bastar: SKILL.md para el contrato, scripts/ para pasos repetibles, references/ para documentación que no debe ocupar contexto siempre y assets/ para plantillas consumidas por el resultado. No añadas README, changelog y cinco guías auxiliares por reflejo: son más superficie que el agente tendrá que elegir mal.

Crea un SKILL.md que el agente pueda elegir

El frontmatter solo necesita un nombre estable y una descripción concreta. La descripción es un selector: menciona el resultado, las señales de activación y una frontera. 'Ayuda con desarrollo' no selecciona nada; 'reproduce fallos intermitentes de pytest y guarda evidencia sin cambiar producción' sí.

Después escribe imperativos observables: inspecciona primero, preserva cambios existentes, ejecuta un comando de repro, aplica el cambio mínimo, corre la regresión y reporta evidencia. Evita instrucciones como 'usa tu criterio' precisamente donde el equipo espera uniformidad. El criterio humano debe aparecer como una condición de parada o una aprobación requerida.

Ejemplo mínimo para un repositorio Python:

.agents/skills/pytest-regresion/SKILL.md

---
name: pytest-regresion
description: Reproduce y corrige un fallo de pytest cuando hay un test, un stack trace o un comando que falla. No usar para refactors ni cambios de infraestructura.
---

1. Lee AGENTS.md y conserva los cambios no relacionados.
2. Ejecuta el test indicado; si no hay repro, detente y pide el comando exacto.
3. Añade primero un test de regresión mínimo.
4. Modifica solo el módulo que explica el fallo.
5. Ejecuta pytest sobre el test y la suite afectada.
6. Entrega archivos tocados, comando, resultado y riesgos restantes.

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Carga contexto por capas, no por acumulación

La documentación de Codex describe la carga progresiva para que el listado inicial de skills no consuma el contexto del trabajo. Aprovecha ese diseño: en SKILL.md enlaza una referencia solo cuando hay una bifurcación real, como el proveedor cloud, el framework o un protocolo de seguridad. No precargues tres SDKs por si acaso.

Lo que conviene comprobar

Un patrón útil es 'contrato arriba, detalle abajo'. Arriba: entrada esperada, salida, límites, comando de validación y cuándo parar. Abajo: enlaces a references/postgres.md, references/aws.md o una tabla de compatibilidad. Así una tarea de SQLite no lee reglas de producción para Postgres y el agente conserva espacio para inspeccionar tu código.

Mide el fracaso con una señal simple: si los agentes vuelven a pedir instrucciones que ya existen, falta claridad en el contrato. Si empiezan a leer referencias que no usan o ignoran el código local, la skill está cargando demasiado. La solución rara vez es añadir otro documento; normalmente es separar dos workflows que no comparten intención.

Scripts: encapsula lo frágil, no la decisión

Un script es apropiado cuando la secuencia es mecánica y peligrosa de reescribir: inicializar fixtures, recopilar logs redactados, validar un manifiesto o crear un informe. Pide argumentos explícitos y devuelve códigos de salida útiles. No entierres decisiones de arquitectura, despliegues irreversibles o prompts opacos dentro de un helper.

Haz que el script sea seguro ante reintentos. Comprueba precondiciones, usa rutas relativas al repositorio, no imprimas secretos y ofrece --dry-run antes de mutar un recurso externo. Si una skill necesita una base de datos o cloud, separa la fase de observación de la fase de escritura y deja claro qué aprobación hace falta para cada una.

Un buen contrato de script expresa entrada, salida y fallo: collect_failure.py --test tests/api/test_auth.py puede guardar un artefacto local redactado; no debería llamar a producción porque el nombre del test se parece a un incidente. La capacidad reutilizable debe reducir el radio de explosión, no hacerlo más cómodo.

Validación antes de convertirlo en plugin

Prueba la skill en tres casos: el caso feliz, un input incompleto y un repositorio con cambios locales. El caso incompleto debe detenerse con una pregunta concreta; el repositorio sucio debe preservar el trabajo ajeno. Si el procedimiento no tiene una salida segura en esos dos casos, aún no merece automatizarse ni distribuirse.

Mantén una prueba rápida junto a la skill cuando sea viable: valida el frontmatter, comprueba que las rutas referenciadas existen y ejecuta el helper en modo seco. Para un workflow de código, la evidencia mínima incluye el comando ejecutado, código de salida, diff revisable y test de regresión. 'El agente dijo que funciona' no es una verificación.

No evalúes una skill por lo largo que parece el resultado. Evalúala por reducción de retrabajo: menos instrucciones repetidas, menos cambios fuera de alcance, menos intentos fallidos y una revisión humana más rápida. Si sube la velocidad pero nadie entiende qué hizo, has trasladado el coste al reviewer.

De skill local a plugin distribuible

Mantén la skill local mientras el workflow sigue cambiando cada semana. Cuando ya tiene activación estable, validación repetible y usuarios fuera del repositorio, un plugin es la capa de distribución: puede agrupar skills, conectores, MCP, hooks o plantillas de tareas programadas según la documentación de OpenAI.

Distribuir no elimina el threat model. Revisa especialmente hooks, conectores y servidores MCP: pueden introducir ejecución o acceso a sistemas externos. Un plugin debe declarar dependencias y guiar el setup, pero no pedir permisos amplios 'para que funcione'. El usuario debe poder instalar la parte de lectura sin conceder la parte mutante.

No migres a ciegas desde catálogos antiguos. El repositorio openai/skills indica que ahora dirige los ejemplos actuales al repositorio de plugins y a la guía de Build plugins. Usa la documentación actual como fuente de empaquetado y conserva tests de la skill antes de cambiar el canal de distribución.

Errores que convierten una skill en deuda

Descripción genérica que se activa para tareas incompatibles.
Duplicar AGENTS.md y terminar con políticas distintas en cada skill.
Meter documentación extensa en SKILL.md y agotar el contexto antes de mirar el repositorio.
Llamar a scripts con secretos implícitos, rutas absolutas o efectos externos no anunciados.
Confundir metadata de plugin con una barrera de permisos.
No definir condición de parada cuando faltan datos, permisos o un comando de reproducción.
Distribuir el workflow antes de haber probado éxito, fallo seguro y repositorio sucio.

Checklist de publicación interna

El nombre es estable y la descripción expresa tarea, activadores y límites.
SKILL.md contiene entrada, salida, pasos verificables y condición de parada.
Las reglas globales permanecen en AGENTS.md y no se copian sin motivo.
Las referencias grandes se cargan solo cuando una rama del workflow las necesita.
Los scripts aceptan argumentos, no exponen secretos y separan dry-run de escritura.
La skill preserva cambios ajenos y declara qué no puede hacer.
Existe una prueba del caso feliz, del input incompleto y del árbol de trabajo sucio.
Una persona puede revisar comando, diff y resultado sin confiar en una narración del agente.

Preguntas frecuentes

¿Qué es una Codex Skill?

Es un paquete local de instrucciones para un workflow concreto. Incluye como mínimo un directorio y SKILL.md; puede incluir scripts, referencias y assets si aportan una capacidad que no conviene reescribir en cada tarea.

¿Una skill sustituye a AGENTS.md?

No. AGENTS.md gobierna el repositorio y sus reglas duraderas; una skill describe un procedimiento especializado. Usa ambos para que las reglas globales no se dupliquen ni entren en conflicto.

¿Las skills otorgan permisos al agente?

No. La sandbox, las aprobaciones, las credenciales y los controles del host siguen aplicando. Una skill no debe presentarse como una excepción de seguridad.

¿Cuándo debo añadir un script?

Cuando un paso sea mecánico, repetible y verificable. Si encapsula una decisión de producto, un despliegue irreversible o una acción externa amplia, conserva esa decisión fuera del helper y exige aprobación.

¿Cuándo convierto una skill en plugin?

Cuando el workflow ya es estable, tiene validación y necesita instalarse o compartirse entre varios proyectos o equipos. Empieza local: distribuir demasiado pronto fija una mala interfaz.

¿Puedo usar la misma skill en Claude Code y Codex?

El formato SKILL.md pertenece al estándar abierto de Agent Skills, pero la disponibilidad, rutas, metadata y capacidades del host pueden diferir. Verifica el comportamiento y permisos en cada entorno antes de declararla portátil.

Cómo crear una Codex Skill reutilizable y verificable

Elegir una tarea repetida. Selecciona un workflow con entrada, salida y evidencia claras; evita procedimientos que aún dependen de decisiones de arquitectura abiertas.
Escribir el selector. Crea nombre y descripción que expliquen cuándo usar la skill y cuándo no, para impedir activaciones genéricas.
Definir el contrato. En SKILL.md fija pasos, límites, condición de parada y comando de validación; deja AGENTS.md para reglas globales.
Separar el detalle. Mueve documentación grande a references y operaciones mecánicas a scripts con argumentos explícitos.
Aislar efectos. Añade comprobaciones, dry-run y aprobación para operaciones externas; nunca conviertas la skill en un atajo de permisos.
Probar fallos seguros. Ejecuta caso feliz, input incompleto y repositorio con cambios locales; conserva evidencia reproducible.
Medir utilidad. Revisa si reduce reintentos, cambios fuera de alcance y tiempo de revisión, no solo si genera más texto.
Distribuir después. Empaqueta como plugin únicamente cuando activación, dependencias y validación estén estables y documentadas. > ### Límite sano > > Paraleliza investigación y tareas acotadas. No paralelices criterio técnico ni integración final.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Copilot Spaces: cómo crear capas de contexto sin meter todo el repositorio en cada prompt

Khavel — Fri, 28 Aug 2026 09:08:34 +0000

Copilot Spaces no va de guardar chats bonitos. Va de crear una capa de contexto curada para una misión concreta. La diferencia entre buen contexto y contexto infinito es lo que separa a un agente útil de un asistente caro y confundido.

Copilot Spaces es una forma de agrupar contexto para Copilot Chat: repositorios, archivos, carpetas, issues, pull requests, notas, texto libre, imágenes y uploads, de manera que las respuestas se anclen en evidencia relevante para una tarea.

TL;DR

La keyword principal es Copilot Spaces; la intención de búsqueda en español es aprender a usar Spaces junto a instrucciones, MCP, Memory y content exclusion para construir capas de contexto útiles sin sobrecargar al agente.

Mi postura: Spaces debe ser la capa de misión, no el vertedero de todo el conocimiento del equipo. Si metes medio monorepo, todos los issues y notas antiguas, el problema deja de ser falta de contexto y pasa a ser exceso de ruido.

El error: pensar que más contexto siempre mejora al agente

Una definición citable: Copilot Spaces es una colección curada de contexto que Copilot puede usar para responder preguntas sobre una tarea, área de producto o sistema concreto, y que puede compartirse con otras personas para alinear conocimiento técnico.

La intuición rápida dice: si el agente falla por falta de contexto, añadamos más. Esa intuición rompe rápido. Más contexto también significa más ambigüedad, más tokens, más material obsoleto, más riesgo de filtrar datos sensibles y más posibilidades de que el modelo preste atención a lo incorrecto.

El objetivo no es que Copilot vea todo. El objetivo es que vea lo suficiente, en la capa correcta, con una frontera clara entre evidencia, reglas, herramientas y memoria.

Recibe una lectura semanal de herramientas IA para devs

Si quieres seguir Copilot Spaces, Agent Finder, MCP, memoria e instrucciones de agentes sin perseguir documentación dispersa, DevAI Semanal te lo resume cada semana en un email de 5 minutos.

Suscribirme gratis

La arquitectura mental: cinco capas de contexto

Yo separaría el contexto de Copilot en cinco capas. No porque GitHub lo venda así, sino porque operativamente evita mezclar cosas que cambian a ritmos distintos.

Capa 1: política y exclusión. Lo que nunca debe entrar al modelo: secretos, datos regulados, rutas sensibles, repos que no deberían informar respuestas y archivos excluidos por configuración.

Capa 2: instrucciones estables. Cómo trabaja el repo: convenciones, comandos, estilo, testing, arquitectura, ownership y reglas que aplican casi siempre.

Capa 3: Space de misión. Evidencia concreta para una tarea: archivos, carpetas, issues, PRs, notas, transcripciones, imágenes o documentos necesarios para entender un cambio.

Capa 4: herramientas vivas. Contexto que no conviene congelar en un Space porque cambia: GitHub MCP, toolsets, issues activos, PRs, datos externos y sistemas internos.

Capa 5: memoria. Preferencias y convenciones que Copilot aprende o conserva con el tiempo, y que debes revisar porque una memoria antigua puede convertirse en una regla falsa.

Una arquitectura práctica: lo permanente vive en instrucciones, lo específico de una misión vive en un Space, lo dinámico entra por MCP y lo sensible se excluye antes de empezar.

Dónde encaja Copilot Spaces

Spaces encaja en la tercera capa: contexto de misión. Un Space debería responder a una pregunta concreta: qué necesita saber Copilot para razonar sobre este módulo, esta migración, este bug, este rediseño o esta decisión técnica.

Lo que conviene comprobar

La documentación de GitHub indica que un Space puede incluir repositorios, código, pull requests, issues, texto libre como notas o transcripciones, imágenes y archivos subidos. También puede compartirse con el equipo o hacerse público según el caso.

La parte clave es que Copilot no usa necesariamente todo el contenido del Space en cada respuesta. Lo usa como base recuperable. Por eso añadir fuentes muy relevantes suele funcionar mejor que adjuntar un repo entero por costumbre.

Qué pondría dentro de un Space

Para una feature nueva: el issue de producto, el ADR o spec, los archivos del área afectada, el contrato de API, dos PRs recientes buenos y una nota breve con restricciones no obvias.

Para onboarding de un módulo: README, diagrama de arquitectura, carpeta principal, tests representativos, issues cerrados que explican decisiones, y una nota con vocabulario del dominio.

Para depurar un bug: issue original, logs saneados, pasos de reproducción, archivos sospechosos, test fallido, PR que introdujo el cambio y capturas o imágenes si el bug es visual.

Para una migración: guía oficial, lista de breaking changes, wrappers internos, ejemplos actuales, decisiones de compatibilidad y un checklist de rollout.

Qué no pondría dentro de un Space

No pondría secretos, dumps, datos reales de clientes, tickets con PII, logs sin limpiar ni configuraciones internas que el agente no necesita para razonar.

Tampoco pondría todo el monorepo si la tarea toca tres carpetas. La opción de incluir repositorios completos es útil para exploración, pero no debería ser el patrón por defecto en tareas de precisión.

Y no pondría documentación obsoleta para que quizá ayude. En un Space, lo viejo compite con lo correcto. Si quieres conservar historia, etiquétala como historia y explica por qué no debe guiar la implementación actual.

Instrucciones estables: el contexto que no debería vivir en Spaces

Las instrucciones de repositorio, como .github/copilot-instructions.md, son mejores para reglas permanentes: cómo ejecutar tests, estilo de código, frameworks, estructura de carpetas, convenciones de commits, restricciones de seguridad y criterios de revisión.

GitHub también documenta soporte variable por superficie para instrucciones de repo, instrucciones por ruta y archivos de agente como AGENTS.md, CLAUDE.md o GEMINI.md. Eso importa porque no todas las experiencias de Copilot cargan las mismas capas igual.

Regla práctica: si una frase debería aplicarse a casi todas las interacciones del repo, no la escondas en un Space. Ponla en instrucciones versionadas. Si solo aplica a una iniciativa concreta, ahí sí tiene sentido el Space.

Path-specific instructions: contexto por zona del repo

En repos grandes, una instrucción global tiende a volverse genérica. Las instrucciones por ruta permiten decir: en api/ usamos contratos OpenAPI; en frontend/ usamos accesibilidad y snapshots visuales; en infra/ no se cambian permisos sin plan de rollback.

Esta capa reduce el tamaño mental del problema. Copilot no necesita una biblia de todo el sistema para tocar un endpoint. Necesita las reglas de esa zona y la evidencia de la tarea.

La combinación buena es: instrucciones globales cortas, instrucciones por ruta concretas y Spaces para misiones que cruzan varias zonas.

MCP: contexto vivo, no documentación congelada

MCP sirve para conectar Copilot con herramientas y sistemas externos. GitHub lo presenta como una forma de extender Copilot con servicios existentes en IDEs, CLI, la app y agentes en GitHub.com.

Esto no compite con Spaces. Lo complementa. Un Space puede contener la explicación de la migración; MCP puede consultar el issue vivo, listar PRs, ver metadata del repo o interactuar con herramientas autorizadas.

La frontera sana: si el dato cambia cada minuto, no lo copies al Space. Conéctalo por una herramienta con permisos mínimos. Si el dato es evidencia estable para la tarea, inclúyelo en el Space.

Copilot Memory: útil, pero con caducidad mental

Copilot Memory permite conservar convenciones, preferencias y detalles aprendidos de interacciones. Bien usado, evita repetir cada vez que prefieres cierto estilo de test o patrón de arquitectura.

Lo que conviene comprobar

El riesgo es convertir memoria en dogma. Una preferencia personal puede no aplicar al repo. Una convención puede cambiar. Una decisión temporal puede quedarse pegada a respuestas futuras.

Yo revisaría Memory como revisas dependencias: de vez en cuando, con intención. Lo que aplica al repo debería estar versionado en instrucciones. Lo personal puede vivir en memoria, pero no debería contradecir al proyecto.

Content exclusion: la primera capa, no el último parche

Content exclusion permite configurar archivos y rutas que Copilot debe ignorar. Según GitHub, el contenido excluido no informa sugerencias inline, respuestas de Chat ni revisiones de código afectadas.

No lo trates como un ajuste de privacidad al final. Es la primera capa de arquitectura de contexto. Antes de construir Spaces, instrucciones o MCP, decide qué no debe entrar nunca.

Ejemplos: .env, fixtures con datos reales, exports de clientes, claves, dumps, modelos propietarios, contratos bajo NDA o cualquier carpeta donde una respuesta útil no compensa el riesgo.

Cómo diseñar un Space bueno

Nómbralo por misión, no por herramienta: checkout-refactor-q3, onboarding-billing-service, incident-postmortem-payments, migration-react-compiler.

Añade una nota inicial con tres cosas: objetivo, límites y definición de terminado. Sin esa nota, el Space puede tener documentos buenos pero carecer de intención.

Incluye evidencia mínima suficiente: cinco archivos buenos valen más que quinientos archivos indiferentes. Añade el issue o PR que motivó la tarea, no toda la historia del proyecto.

Cierra el Space cuando la misión termine o archívalo con una nota de resultado. Un Space abandonado se convierte en contexto fósil.

Checklist de capas de contexto

Excluye primero rutas sensibles o irrelevantes.
Mantén .github/copilot-instructions.md corto y estable.
Usa instrucciones por ruta para reglas específicas de carpetas.
Crea Spaces por misión, feature, bug, migración o onboarding.
Añade al Space archivos concretos antes que repos completos.
Incluye issues y PRs solo si explican decisiones vigentes.
Usa MCP para información viva o acciones, no para reemplazar documentación.
Revisa Copilot Memory para evitar preferencias obsoletas.
Mide si el Space reduce preguntas repetidas y cambios fuera de alcance.
Elimina contexto que no haya cambiado ninguna respuesta.

Errores que evitaría

El primero es crear un Space por equipo y meterlo todo. Eso se convierte en wiki desordenada, no en contexto operativo.

El segundo es duplicar reglas en todos los sitios: instrucciones, Space, Memory y prompt. Cuando una regla cambia, no sabrás cuál manda.

El tercero es tratar issues antiguos como verdad. Un issue cerrado puede explicar una decisión, pero también puede estar obsoleto. Añade notas que distingan evidencia histórica de regla vigente.

El cuarto es usar MCP con permisos amplios para compensar Spaces pobres. Las herramientas vivas necesitan menos permisos, no más confianza.

Implementación recomendada para un equipo

Semana 1: crea instrucciones globales mínimas y content exclusion para rutas sensibles.
Semana 2: define tres plantillas de Space: feature, bug y migración. Cada plantilla debe pedir objetivo, límites, archivos clave, issues/PRs y definición de terminado.
Semana 3: añade instrucciones por ruta para dos zonas críticas del repo y conecta MCP solo en modo lectura si aporta información viva.
Semana 4: revisa sesiones reales. Qué contexto sobró, qué faltó, qué respuestas fueron mejores y qué archivos se repitieron en varios Spaces.
Después: convierte conocimiento repetido en instrucciones versionadas. Deja en Spaces solo lo que pertenece a una misión concreta.

Conclusión

Copilot Spaces es más interesante como disciplina de contexto que como feature de organización. Obliga a decidir qué evidencia necesita una tarea y qué debe quedar fuera.

Lo que conviene comprobar

La arquitectura ganadora no es un Space enorme. Es una pila: exclusión para lo sensible, instrucciones para lo estable, Spaces para misiones, MCP para datos vivos y Memory para preferencias revisables. Si separas esas capas, Copilot responde mejor y tu equipo puede auditar por qué el agente sabía lo que sabía.

Preguntas frecuentes

¿Qué es Copilot Spaces?

Copilot Spaces es una forma de organizar contexto para GitHub Copilot usando repositorios, archivos, issues, PRs, notas, imágenes y uploads relevantes para una tarea o área.

¿Copilot usa todo lo que pongo en un Space?

No necesariamente. GitHub indica que Copilot usa contexto relevante del Space para responder, por eso conviene añadir fuentes muy seleccionadas.

¿En qué se diferencia un Space de `.github/copilot-instructions.md`?

Las instrucciones son reglas persistentes del repo; un Space es contexto curado para una misión, feature, bug o área concreta.

¿Cuándo uso MCP en vez de un Space?

Usa MCP cuando el dato cambia o requiere interacción con sistemas vivos. Usa un Space para evidencia estable que quieres que Copilot tenga presente.

¿Copilot Memory reemplaza a las instrucciones?

No. Memory sirve para preferencias y convenciones aprendidas, pero las reglas de proyecto deberían vivir en archivos versionados.

¿Qué debería excluir antes de crear Spaces?

Secretos, datos reales de clientes, dumps, fixtures sensibles, archivos bajo NDA y cualquier ruta que no deba informar respuestas ni revisiones.

Límite sano

Paraleliza investigación y tareas acotadas. No paralelices criterio técnico ni integración final.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Git worktree para agentes de IA: trabajo paralelo sin pisar tu repositorio

Khavel — Thu, 27 Aug 2026 09:08:43 +0000

git worktree permite tener varios directorios de trabajo conectados al mismo repositorio, cada uno con su HEAD e índice. La keyword principal es git worktree agentes IA; la intención es práctica: un developer quiere ejecutar tareas de agentes en paralelo sin que compartan el árbol de archivos que están editando.

TL;DR

Un worktree es aislamiento de checkout, no aislamiento de ejecución. Evita que un agente borre el build de otro o cambie su lockfile a mitad de una prueba; no separa credenciales, procesos que escuchan en el mismo puerto, recursos cloud, cachés globales ni la decisión de mergear.

Mi postura: asigna un worktree por cambio pequeño y verificable, no uno por cada pensamiento del modelo. Paraleliza investigación, documentación, tests o módulos con fronteras claras; integra de uno en uno con CI y revisión humana. Si dos tareas necesitan tocar la misma abstracción, el cuello de botella no es Git: es una decisión de diseño que nadie ha tomado todavía.

Qué aísla realmente un Git worktree

Un repositorio puede tener un worktree principal y varios worktrees enlazados. Git comparte el almacén de objetos y la mayoría de las refs, pero cada checkout enlazado tiene su propio HEAD, índice y directorio de trabajo. Por eso dos agentes pueden partir del mismo commit y modificar archivos distintos sin sobrescribir el disco del otro.

Git protege una frontera importante: normalmente rechaza que la misma rama esté checkout en dos worktrees. No fuerces ese bloqueo con --force para 'hacerlo funcionar'. Si dos agentes trabajan sobre la misma rama, has recuperado el problema original con una topología más difícil de depurar.

La frase útil para documentar en tu repositorio es: un worktree representa una tarea y una rama; un agente representa un ejecutor temporal de esa tarea. La rama sobrevive a la conversación, el worktree puede desecharse después de que el cambio esté validado y fusionado.

Los worktrees separan archivos, índice y rama de cada tarea; la integración vuelve a ser una cola única con pruebas y revisión.

La unidad correcta de paralelismo

No distribuyas una petición como 'mejora la autenticación' entre cuatro agentes. Divide por contrato comprobable: uno añade una validación de entrada, otro actualiza documentación y ejemplos, otro escribe tests de regresión. Cada tarea debe tener rutas permitidas, una salida observable y un comando de validación que no dependa de adivinar la intención del otro agente.

Evita el paralelismo si varias tareas tocan la misma migración, interfaz pública, lockfile o selector central. También evítalo si todas requieren el mismo entorno mutable: un emulador con un puerto fijo, una base de datos de desarrollo compartida o una cuenta de pruebas que no resetea el estado. Un worktree no convierte esos recursos en seguros para concurrencia.

Empieza por dos worktrees. Si la integración termina generando conflictos repetidos, baja el paralelismo y mejora la división de tareas. Más agentes no arreglan límites de módulo mal definidos; solo generan más diffs que una persona tendrá que entender.

Crear un worktree por rama de agente

Parte de una referencia explícita y actualizada. Nombrar rama y directorio hace que la intención sea auditable y reduce el riesgo de que un agente trabaje contra un HEAD local olvidado. La opción -b falla si la rama ya existe, que es una protección útil para una automatización que se reintenta.

terminal
git fetch origin
git worktree add -b agent/authz-input ../miapp-agent-authz origin/main
git worktree add -b agent/docs-authz ../miapp-agent-docs origin/main
git worktree list --porcelain

No uses el nombre del modelo como rama (claude-fix, codex-fix). Usa el resultado técnico (agent/authz-input) y guarda en la tarea quién la ejecutó, el prompt o issue, el commit base y el comando de verificación. Así puedes cambiar de herramienta sin perder trazabilidad ni convertir el historial Git en marketing involuntario.

Contexto y configuración: lo que viaja y lo que no

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Los archivos versionados viajan con la rama: AGENTS.md, README, scripts de bootstrap, linters y fixtures deberían estar ahí. Codex compone sus instrucciones desde el root del proyecto hasta el directorio actual; por tanto, un AGENTS.md comprometido es una forma reproducible de dar a cada worktree los mismos límites, comandos y rutas sensibles.

Lo que conviene comprobar

Los archivos no versionados no aparecen por magia. .env, claves SSH, credenciales de cloud, bases SQLite locales y caches deben ser creados por un bootstrap explícito de desarrollo, preferiblemente con datos de prueba y privilegios mínimos. Copiar el .env de producción a cada worktree es una comodidad que transforma una mejora de productividad en una multiplicación de secretos.

La configuración de Git es compartida por defecto. Si un worktree necesita sparse-checkout, hooks o una opción local distinta, activa extensions.worktreeConfig y escribe con git config --worktree. No pongas una configuración de una tarea en el config común: terminará sorprendiendo al siguiente agente que use el repositorio.

Recorta el checkout sin contaminar a los demás

En monorepos grandes, un agente que cambia un paquete no necesita indexar todo el producto. git sparse-checkout set configura la selección para el worktree actual y Git actualiza a configuración específica cuando hace falta. Es una optimización de I/O y de contexto, no una frontera de seguridad: el agente puede seguir acceder a otras rutas si le das permisos de sistema amplios.

desde el worktree del agente
git sparse-checkout set --cone apps/api packages/auth
git sparse-checkout list
git config --show-origin --get core.sparseCheckout
Prueba primero con un worktree desechable. Algunas herramientas de generación, IDEs y scripts de release esperan rutas que un checkout disperso no contiene. Si la tarea necesita ejecutar integración end-to-end del monorepo, un checkout completo y un agente menos paralelo suelen ser la decisión más barata.

Un contrato operativo antes de arrancar el agente

El prompt debe describir una frontera, no solo un objetivo: rutas que puede modificar, archivos prohibidos, datos de prueba, comandos de setup, tests obligatorios y condición para pedir ayuda. Escríbelo junto al trabajo, no solo en la conversación, para que un reintento o una revisión humana pueda comprobar el mismo contrato.

Una plantilla mínima: base_sha, branch, worktree_path, allowed_paths, forbidden_paths, setup, verify, network_policy y handoff. El handoff debe incluir resumen, archivos tocados, pruebas ejecutadas, pruebas no ejecutadas y riesgos. Si el agente no puede completar verify, su resultado es un borrador bloqueado, no un cambio listo para merge.

Los límites de permisos siguen fuera de Git. Ejecuta tareas de lectura en un sandbox de lectura, separa la red de la escritura de código y solicita aprobación para operaciones que afecten recursos externos. El worktree organiza el checkout; el sandbox y la política controlan lo que el proceso puede hacer.

Validar cada worktree antes de mirar el diff

Un diff bonito no demuestra que el agente partió de una base sana. Primero registra la revisión inicial y confirma que no heredó cambios locales. Después ejecuta setup y pruebas en el propio directorio del worktree. Nunca valides desde el worktree principal 'por comodidad': eso abre la puerta a probar una cosa y entregar otra.

checklist ejecutable por tarea

git status --porcelain
git rev-parse HEAD
make setup
make test
git diff --check
git diff --stat

Añade pruebas negativas cuando el cambio toca permisos, aislamiento de tenant o acciones mutantes. El caso feliz debe usar fixtures estables; un agente no debe necesitar credenciales de producción para demostrar que una validación de entrada funciona. Conserva logs redactados y el SHA probado como artefactos de la tarea.

La integración sigue siendo secuencial

Los worktrees aceleran la exploración, pero no autorizan merges simultáneos sobre una misma rama objetivo. Rebasea o actualiza cada rama contra una referencia reciente, ejecuta la suite que corresponda y revisa el diff con contexto. Fusiona un cambio, vuelve a calcular la base del siguiente y repite. Es menos espectacular que un enjambre, y bastante más fiable.

En CI, protege despliegues y migraciones con un grupo de concurrencia. GitHub Actions garantiza que solo un job o workflow con la misma clave de concurrencia se ejecuta a la vez; úsalo para impedir que dos pipelines publiquen el mismo entorno o apliquen cambios incompatibles mientras tus agentes trabajan en ramas separadas.

.github/workflows/deploy.yml

concurrency:
  group: deploy-staging
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/deploy-staging.sh

Limpieza: no borres directorios a ciegas

Después de mergear, usa git worktree remove sobre un worktree limpio. Git se niega a eliminar un worktree con cambios rastreados o archivos no rastreados salvo que fuerces la operación; esa fricción es una revisión final de bajo coste, no algo que debas automatizar con un rm -rf genérico.

Si un directorio se perdió fuera de Git, inspecciona primero git worktree list --verbose y usa git worktree prune --dry-run antes de limpiar metadatos obsoletos. prune arregla registros de worktrees ausentes; no recupera el contenido que alguien eliminó manualmente. Para worktrees en un disco externo o efímero, git worktree lock --reason evita que Git los considere basura mientras están desconectados.

Evita git clean -xfd como final automático de una tarea de agente. La documentación de Git confirma que -x borra también archivos ignorados: ahí suelen vivir .env, artefactos locales y estado que no podrás reconstruir sin ayuda. Si necesitas limpieza, empieza siempre con git clean -nd y limita un path concreto que hayas comprobado.

Checklist para agentes en paralelo

Crear una rama y un worktree por tarea, ambos con un nombre técnico y una base SHA registrada.
Dar a cada agente rutas permitidas, rutas prohibidas, setup, tests obligatorios y un handoff verificable.
Mantener AGENTS.md, scripts de bootstrap y fixtures versionados; no copiar secretos reales entre worktrees.
Configurar por worktree sparse-checkout, hooks o ajustes locales que no deban filtrarse al repositorio común.
Ejecutar setup, tests y git diff --check dentro del worktree que generó el cambio.
Serializar merge, migraciones y despliegues aunque la investigación y edición hayan sido paralelas.
Usar git worktree remove en árboles limpios y simular cualquier prune o clean antes de borrar algo.

Preguntas frecuentes

¿Qué es un Git worktree?

Es un checkout adicional enlazado al mismo repositorio. Tiene su propio directorio de trabajo, HEAD e índice, por lo que permite trabajar en ramas distintas al mismo tiempo sin cambiar el checkout principal.

¿Un worktree permite que dos agentes modifiquen la misma rama?

No es el diseño seguro. Git normalmente impide que una rama esté checkout en dos worktrees; usa una rama por tarea y resuelve la integración mediante commits, rebase, CI y revisión.

¿Los worktrees comparten node_modules, .env o puertos?

No comparten el directorio de trabajo, pero tampoco aíslan recursos externos. Cada worktree necesita su bootstrap; procesos, caches globales, puertos, bases de datos y credenciales requieren controles propios.

¿Debo usar sparse-checkout para cada agente?

Solo cuando el monorepo y la tarea lo justifican. Reduce I/O y contexto, pero puede romper scripts que esperan el árbol completo y no es un control de seguridad.

¿Puedo borrar un worktree con rm -rf?

No como procedimiento normal. Usa git worktree remove cuando esté limpio; si hay inconsistencias, inspecciona y prueba git worktree prune --dry-run antes de tocar metadatos.

¿Los worktrees sustituyen la revisión humana?

No. Aíslan la edición, pero no validan arquitectura, permisos, pruebas, impacto de migraciones ni calidad del merge. La cola de integración debe seguir teniendo gates explícitos.

Cómo ejecutar dos tareas de agentes con Git worktree sin colisiones

Registrar la base. Parte de un commit o rama remota explícita y anota su SHA junto a cada tarea.
Dividir el trabajo. Define dos cambios con rutas y contratos separados; no paralelices una misma interfaz o migración.
Crear las ramas. Ejecuta git worktree add -b para cada rama y directorio de tarea, sin forzar ramas ya checkout.
Preparar el entorno. Ejecuta el bootstrap del repositorio en cada worktree con fixtures y secretos de desarrollo mínimos.
Cargar instrucciones. Mantén AGENTS.md y los comandos de verify versionados para que cada agente reciba el mismo contexto comprobable.
Acotar el agente. Entrega rutas permitidas, prohibiciones, política de red y condición de handoff antes de que edite.
Verificar localmente. Corre tests, lint y git diff --check desde el worktree que produjo el cambio; guarda SHA y resultados.
Integrar de uno en uno. Actualiza la rama objetivo, revisa el diff y CI, mergea un cambio y recalcula la base del siguiente.
Retirar con seguridad. Cuando el árbol esté limpio y el cambio integrado, elimina con git worktree remove; simula prune o clean antes de cualquier limpieza. > ### Límite sano > > Paraleliza investigación y tareas acotadas. No paralelices criterio técnico ni integración final.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Microsoft Foundry Agent Service: cómo desplegar agentes con identidad, tools y trazas

Khavel — Wed, 26 Aug 2026 09:14:05 +0000

Microsoft Foundry Agent Service es el runtime gestionado de Microsoft para ejecutar agentes basados en prompts o código. La keyword principal es Microsoft Foundry Agent Service; la intención es de implementación: un equipo Azure quiere saber cuándo usarlo, cómo dar tools a un agente y qué controles necesita antes de producción.

TL;DR

La decisión no es entre 'gestionar todo' o 'hacer magia con un prompt'. Foundry puede encargarse del endpoint, escalado, identidad Entra, sesiones, versionado y trazas; tu equipo sigue siendo responsable de la política de acceso, la validación de negocio, los límites de coste y la aprobación de acciones mutantes.

Mi postura: empieza con un prompt agent si tu workflow cabe en instrucciones y un conjunto estrecho de tools. Elige un hosted agent cuando tu código necesita orquestación propia, protocolos o estado. No empaquetes un microservicio normal como agente solo por subirte al término: si un if y una API determinista resuelven la tarea, será más barato y comprobable.

Qué es y qué no es Agent Service

Un agente combina modelo, instrucciones y tools. En Foundry, la Responses API es el punto de entrada común: permite usar modelos del catálogo y herramientas de plataforma desde un prompt agent, un contenedor propio o un proceso que ya existe. Esa capa no convierte cualquier respuesta en una decisión correcta; organiza el runtime alrededor de ella.

El servicio actual distingue dos rutas. Un prompt agent se define por configuración y Foundry ejecuta el runtime; un hosted agent es tu código —Agent Framework, LangGraph, OpenAI Agents SDK o un runtime propio— empaquetado y ejecutado con endpoint e identidad administrados. No confundas esta generación con los 'Agents (classic)': Microsoft marca el portal y SDK clásicos como deprecados, con retirada anunciada para marzo de 2027.

La frontera citable es sencilla: Foundry administra cómo se ejecuta y observa un agente; tu producto determina qué puede hacer, contra qué datos y quién responde cuando se equivoca.

Un runtime gestionado reduce trabajo de plataforma; Toolbox, identidad, aprobación y evaluación siguen siendo decisiones de ingeniería explícitas.

Prompt agent, hosted agent o tu proceso actual

Usa un prompt agent para un copiloto interno que consulta documentación, resume un expediente o prepara una propuesta sin orquestación de aplicación compleja. La ganancia es operativa: no mantienes contenedor ni servidor. Antes de abrirle una tool de escritura, define scopes, retención, casos de denegación y un modo de revisión humana.

Usa un hosted agent cuando necesitas código propio, webhooks, una API no compatible con Responses, una máquina de estados, workers, bibliotecas existentes o un protocolo específico. El servicio ejecuta cada sesión en un sandbox aislado y proporciona identidad y endpoint, pero no audita si tu función de Python respeta el tenant. Tu backend debe derivar identidad y permisos de credenciales fiables, no de parámetros que el modelo inventa.

Mantén tu proceso fuera de Foundry si ya tienes una aplicación sana y solo quieres acceder a modelos o a una tool concreta. Migrar runtime sin una necesidad de escalado, distribución, identidad o estado añade otra superficie de despliegue. La portabilidad razonable es aislar tu lógica de negocio y tratar la integración con Foundry como un adaptador.

Toolbox: centraliza capacidades, no confianza

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Un Toolbox es un paquete versionado de tools que se expone por un endpoint MCP. Sirve para evitar que cada agente tenga su propia copia de URLs, credenciales, allowlists y políticas. Un consumidor puede seguir el default_version para recibir una versión promovida, mientras un entorno de prueba se conecta a una URL versionada e inmutable antes de aprobarla.

La ventaja real no es que MCP sea moderno; es que puedes gobernar una colección. Empieza con dos tools de lectura, por ejemplo búsqueda web y documentación interna. Después añade una integración remota, separada por dominio y con una conexión de proyecto. Un Toolbox que mezcla GitHub de escritura, facturación, producción y búsqueda pública es una forma elegante de esconder una política pésima.

La documentación es explícita con un detalle que muchos omiten: cuando una tool devuelve require_approval: always, el endpoint MCP no bloquea tools/call; el runtime debe presentar la acción y esperar confirmación. No declares aprobación en metadata y des por resuelto el control. Prueba que tu interfaz y tu executor lo imponen realmente.

Un piloto reproducible con Azure Developer CLI

El quickstart oficial permite crear un hosted agent de ejemplo, usar una Toolbox y ejecutarlo localmente antes de desplegar. Este flujo es deliberadamente pequeño: valida el endpoint, el descubrimiento de tools/list y el comportamiento de una tool de lectura antes de conectar recursos sensibles.

Lo que conviene comprobar

PowerShell / terminal

mkdir foundry-toolbox-pilot
cd foundry-toolbox-pilot
azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/azure.yaml" --src src/toolbox-agent

azd ai toolbox create docs-tools --from-file ./src/toolbox-agent/toolbox.yaml
azd env set TOOLBOX_NAME docs-tools
azd ai agent run

# En otra terminal: comprueba tools y una consulta de solo lectura
azd ai agent invoke --local "Enumera las tools disponibles y no ejecutes ninguna acción mutante."

Fija versiones de azd, la extensión microsoft.foundry, Python y las dependencias del sample en tu CI. El comando scaffold es una base, no una arquitectura aprobada. Revisa el azure.yaml, el toolbox.yaml, las conexiones y cualquier endpoint antes de asociarlo a recursos de empresa.

Identidad, secretos y aislamiento

Al desplegar un hosted agent, Foundry crea una identidad Entra dedicada para ese agente. Esa identidad puede usar el endpoint del proyecto y el almacenamiento de sesión por defecto; para Storage, Search u otros recursos debes conceder roles específicos. Ese diseño es preferible a copiar una clave de administrador en el contenedor, pero mínimo privilegio sigue significando una asignación por recurso y entorno.

No guardes API keys ni OAuth tokens dentro de la imagen ni en el repositorio. Foundry permite resolver valores desde project connections al iniciar el sandbox. Para tools MCP, la conexión decide la identidad downstream; separa conexiones de desarrollo y producción y rota las credenciales con el mismo rigor que las de cualquier servicio.

Las tools externas pueden sacar datos fuera del perímetro de cumplimiento de Foundry. Documenta ese flujo antes de activar un conector: datos enviados, proveedor, región, retención, scopes y respuesta ante un fallo. La red privada y RBAC ayudan, pero no corrigen una tool que devuelve demasiado contexto al modelo.

Despliegue, trazas y evaluación

La secuencia sana es build local, prueba de tools y casos negativos, despliegue de una versión, espera a estado activo, canary con identidad de prueba y solo después promoción. Los hosted agents pueden desplegarse como contenedor o desde código fuente empaquetado; elige el primero si ya controlas la imagen y el segundo para un inner loop sencillo, no por comodidad ciega.

Foundry puede inyectar la conexión de Application Insights y habilitar OpenTelemetry. Eso permite ver latencia, excepciones, llamadas de modelo y dependencias, pero puede incluir contenido personal o de cliente en trazas. Define redacción, muestreo, retención y quién puede leer Application Insights antes de celebrar que ya tienes observabilidad.

Evalúa tres capas por separado: resultado final (¿la respuesta sirve?), trayectoria (¿eligió la tool permitida?) y ejecución (¿respetó identidad, timeout y coste?). Cada fallo de producción debe convertirse en un caso de dataset antes de cambiar instrucciones o modelo. Sin ese bucle, el versionado solo te deja volver atrás sin saber por qué.

Checklist antes de producción

Elegir una tarea que justifique autonomía y escribir el contrato de entrada, salida, tools permitidas y acciones prohibidas.
Crear una Toolbox versionada de bajo riesgo; probar su endpoint versionado y promover a default_version solo tras revisión.
Conceder RBAC mínimo a la identidad de agente y usar una conexión distinta por entorno; no meter secretos en código o imagen.
Forzar confirmación en runtime para tools mutantes y probar una denegación, no solo el camino feliz.
Trazar sin registrar secretos: decidir qué prompts, outputs y argumentos se redactan, durante cuánto tiempo y quién los consulta.
Medir éxito, tool calls, errores, latencia, coste y tasa de escalado a humano con un dataset de casos normales, ambiguos y hostiles.

Preguntas frecuentes

¿Qué es Microsoft Foundry Agent Service?

Es una plataforma gestionada para construir, ejecutar, escalar y observar prompt agents y hosted agents, con modelos, tools, identidad y endpoints de Foundry.

¿Cuándo conviene un hosted agent?

Cuando necesitas ejecutar código propio, una orquestación o protocolo personalizado, estado de aplicación o una integración que no cabe en la configuración de un prompt agent.

¿Toolbox sustituye a una política de permisos?

No. Centraliza configuración, versiones y credenciales de tools; tu runtime y backend deben imponer scopes, aprobación y reglas de negocio.

¿Foundry gestiona por sí solo la aprobación humana?

No. La metadata de una tool puede pedir aprobación, pero el runtime que llama la tool debe detener la acción y esperar confirmación.

¿Puedo usar LangGraph u OpenAI Agents SDK?

Sí. Los hosted agents pueden ejecutar código con esos frameworks; no necesitas reescribir toda la orquestación para usar el runtime gestionado.

¿Las trazas son privadas por defecto?

Trátalas como datos sensibles. Revisa contenido capturado, permisos de Application Insights, retención y redacción antes de usarlas con tráfico real.

Cómo lanzar un piloto seguro con Microsoft Foundry Agent Service

Escoger una tarea de lectura. Empieza con una consulta de documentación o búsqueda interna que no cambie sistemas externos.
Crear un proyecto y modelo. Configura un Foundry project y un deployment de modelo compatible en una región soportada.
Scaffold del agente. Inicializa el sample oficial con Azure Developer CLI y revisa azure.yaml antes de ejecutar.
Crear Toolbox mínima. Añade una o dos tools de solo lectura y guarda la URL de la versión concreta para pruebas.
Ejecutar localmente. Comprueba tools/list, una respuesta útil, timeout y comportamiento ante una tool no permitida.
Asignar identidad mínima. Da a la identidad del agente solo los roles necesarios para los recursos que realmente consume.
Configurar trazas seguras. Conecta Application Insights, redacta campos sensibles y limita quién puede consultar los spans.
Desplegar canary. Publica una versión, invócala con una identidad de prueba y compara resultado, trayectoria, latencia y coste con el dataset.
Promover con evidencia. Cambia el Toolbox o el agente por versiones revisadas y conserva un rollback probado antes de ampliar permisos.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

MCP Inspector: cómo probar y depurar servidores MCP antes de conectar un agente

Khavel — Tue, 25 Aug 2026 09:23:05 +0000

MCP Inspector no sustituye tus tests: convierte el protocolo real en una superficie comprobable. Úsalo para detectar tools que no se anuncian, schemas que mienten, transportes incompatibles y permisos que tu suite unitaria no ve.

MCP Inspector es la herramienta oficial para inspeccionar, probar y depurar un servidor Model Context Protocol (MCP). La keyword principal es MCP Inspector; la intención es técnica y práctica: un developer quiere comprobar un servidor real antes de entregárselo a Claude Code, Cursor, VS Code o a un agente propio.

TL;DR

Úsalo en dos capas. La interfaz web es útil para descubrir una tool, ver argumentos y reproducir un fallo; el modo CLI es el que debes automatizar para probar tools/list, llamadas representativas, recursos y prompts en CI. Un host de agente no es una suite de tests: si ese es tu primer cliente, llegarás tarde a los errores de contrato.

Mi postura: un servidor MCP no está listo porque el Inspector consigue conectar una vez. Está listo cuando su catálogo, sus schemas, sus fallos esperados y sus límites de autorización se comprueban en un entorno sin secretos reales. La conexión feliz es el smoke test, no la definición de calidad.

Qué prueba MCP Inspector y qué no

El Inspector actúa como cliente MCP y ofrece tres superficies: web, CLI y TUI. Puede abrir un proceso local por stdio o conectar con un endpoint remoto, negociar la versión que corresponda y ejecutar operaciones como listar tools, recursos y prompts o llamar una tool. Eso prueba el protocolo y el empaquetado que verá un host, no solo una función TypeScript aislada.

No prueba por sí solo tu autorización de negocio, el aislamiento entre tenants, la calidad de la decisión del modelo ni el comportamiento del proveedor que hay detrás. Tampoco convierte una tool mutante en segura. Es la capa de contrato: confirma que el servidor expone exactamente lo que prometes y que falla de forma útil cuando recibe entradas inválidas.

La diferencia importa desde MCP 2026-07-28. En el flujo moderno se abandona el handshake initialize y aparece server/discover; las peticiones llevan metadata por llamada y Streamable HTTP es stateless a nivel de protocolo. Si mantienes tests que asumen sesiones antiguas, pueden pasar contra un fixture legado y fallar con un cliente moderno.

El Inspector comprueba la conversación real de protocolo; CI decide si ese resultado cumple el contrato y devuelve el cambio al servidor si no lo cumple.

El contrato mínimo antes de abrir un host

Escribe primero una tabla de contrato pequeña y revisable. Para cada tool declara nombre, descripción, inputSchema, campos de salida, efectos, scope requerido, timeout, máximo de elementos y errores recuperables. Si una tool necesita leer tickets del tenant, el tenant_id debe venir del token o del backend, no de un argumento que el modelo pueda cambiar.

Haz lo mismo para resources y prompts. Un recurso debe tener URI, MIME type y límites de tamaño que puedas verificar; un prompt debe declarar los argumentos obligatorios y no filtrar secretos en ejemplos. El Inspector te deja consultar esas superficies, pero la aserción importante vive en tu repositorio: compara la respuesta normalizada con el contrato que el equipo aprueba.

No hagas snapshot de párrafos enteros ni de IDs aleatorios. Normaliza orden, timestamps, trazas y URLs efímeras; afirma solo los campos que un cliente necesita para decidir. Un snapshot enorme enseña ruido y hace que una regresión importante se pierda entre cambios legítimos.

Smoke test reproducible por CLI

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Para un servidor stdio, la forma más rápida de probar el wire protocol es ejecutar el Inspector como cliente, no arrancar una ventana y hacer clic. El comando siguiente lista las tools de un build ya compilado; fija Node y dependencias en el lockfile para que CI y tu portátil ejecuten el mismo artefacto.

package.json

{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "mcp:tools": "npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list"
  }
}

Ese comando prueba que el proceso arranca, que no ensucia stdout con logs y que responde al catálogo MCP. En CI redirígelo a un JSON de artefacto, analiza el exit code y comprueba que aparecen solo las tools permitidas. Los logs de diagnóstico van a stderr; escribir texto de debug en stdout rompe stdio aunque el servidor parezca sano localmente.

Prueba una llamada real y sus errores

tools/list no detecta una tool registrada con argumentos mal definidos o una credencial usada demasiado pronto. Selecciona por tool un caso exitoso con fixture y al menos dos fallos: argumentos inválidos y una decisión de autorización denegada. Para una tool de búsqueda, no necesitas un LLM: usa un índice falso que devuelva resultados conocidos y verifica el structuredContent validado.

Lo que conviene comprobar

La CLI del Inspector permite invocar una tool con --method tools/call, --tool-name y --tool-arg. Mantén las entradas en un fichero o script del repo para que no haya JSON escapado y frágil en YAML. El test debe esperar una respuesta de error explícita o un código de negocio documentado; no debe aceptar que el proceso termine con cualquier texto que contenga 'denied'.

Un patrón útil es probar la misma llamada con dos identidades de prueba. La primera puede leer un documento de su tenant; la segunda recibe permission_denied sin que la respuesta revele si el documento existe. Esa aserción protege tanto confidencialidad como calidad de la experiencia del agente: un modelo que recibe un 403 claro no debería reintentar diez veces.

Compatibilidad: prueba el servidor que publicas, no el que recuerdas

El Inspector v2 convive con servidores de la era antigua y de la moderna. La configuración, flags y el modo de apuntar a un servidor cambiaron respecto a v1, así que no copies un blog post sin fijar la versión y leer la ayuda del paquete instalado. El repositorio oficial incluye una guía de migración: úsala como parte de la actualización de dependencias.

Para remoto, prueba la URL y el transporte exactos que verá el host. Un endpoint que funciona contra stdio no demuestra CORS, cabeceras, proxy inverso, Content-Type, autenticación ni los requisitos del transporte HTTP. En MCP moderno las cabeceras de método y nombre permiten a gateways y rate limiters validar y enrutar sin inspeccionar el body; una prueba HTTP debe fallar cuando cabecera y request discrepan.

Mantén una matriz pequeña: transportes soportados × versión de protocolo × identidad de prueba × operación. No hace falta probar todos los hosts del mercado en cada commit. Sí hace falta una prueba de compatibilidad por rama de protocolo que prometes soportar y una prueba de regresión cuando subes SDK o Inspector.

El Inspector también es una frontera de seguridad

La interfaz web del Inspector se apoya en un proxy local capaz de lanzar procesos y conectar con servidores MCP. No lo expongas a una red no confiable ni desactives su autenticación para evitar una molestia de desarrollo. El propio proyecto advierte que ese atajo puede permitir que una web maliciosa use tu máquina como puente hacia procesos locales.

En CI, ejecuta el Inspector contra un contenedor o proceso efímero con un usuario sin privilegios, directorio temporal y fixtures no sensibles. No pases tokens de producción por -e, no imprimas cabeceras de Authorization y no dejes un puerto expuesto entre jobs. Para un servidor remoto, usa una identidad de test con scopes mínimos y revócala igual que cualquier otro secreto de integración.

La prueba negativa más valiosa no es un payload exótico: es confirmar que la tool no puede ampliar sus propios permisos. Simula un argumento que pide otra cuenta, una URL privada o una operación de escritura y verifica que tu backend impone la política antes de que la tool llegue al proveedor.

De Inspector a una puerta de calidad en CI

Divide la pipeline en cuatro jobs cortos: compilar y hacer unit tests; arrancar el servidor con fixtures; ejecutar Inspector CLI para catálogo, tools, resources y prompts; y correr pruebas negativas de autorización y límites. Conserva como artefacto el resultado normalizado y la versión de protocolo, no credenciales ni contexto de usuarios.

Bloquea un merge cuando desaparece una tool pública, cambia un schema sin versión, una llamada segura devuelve datos de otro tenant o el proceso emite basura por stdout. No bloquees por variaciones cosméticas de descripciones mientras el contrato semántico siga siendo válido; de lo contrario, el equipo aprenderá a ignorar rojo.

El test de protocolo debe convivir con observabilidad. Asigna un traceparent de prueba, registra nombre de tool, latencia, resultado y motivo de denegación de forma redactada. Cuando una integración falla en un host real podrás unir el trace con la misma operación de CI en vez de pedir al modelo que reconstruya el incidente desde una conversación.

Checklist antes de conectar un agente

Compilar el servidor y ejecutar Inspector CLI contra el artefacto, no contra un archivo fuente sin build.

Afirmar tools, recursos y prompts esperados, con schemas y límites que el consumidor realmente use.

Probar una llamada feliz con fixtures y errores de validación, timeout y upstream controlados.

Probar dos identidades de test y comprobar aislamiento entre tenants, scopes y operaciones mutantes.

Ejecutar la matriz mínima de transporte y versión de protocolo que anuncias como compatible.

Mantener Inspector, servidor y SDK versionados; releer la migración al actualizar de era MCP.

Ejecutar proxy y fixtures sin secretos de producción, puertos públicos ni privilegios innecesarios.

Guardar resultados normalizados y trazas redactadas como artefactos de CI.

Preguntas frecuentes

¿Qué es MCP Inspector?

Es la herramienta oficial del ecosistema MCP para inspeccionar, probar y depurar servidores mediante una interfaz web, una CLI y una TUI. Actúa como cliente MCP para comprobar la conversación de protocolo real.

¿MCP Inspector sustituye Jest, pytest o pruebas de integración?

No. Complementa esas pruebas: valida que el build que expones habla MCP correctamente. Las reglas de negocio, aislamiento de datos, rendimiento y proveedores externos necesitan tests propios.

¿Puedo usar MCP Inspector en CI?

Sí, el modo CLI está pensado para automatización. Ejecútalo contra un proceso o contenedor efímero, analiza el resultado y conserva artefactos redactados; no conviertas la UI web en un paso interactivo de CI.

¿Debo desactivar la autenticación del proxy del Inspector?

No. El proxy puede iniciar procesos locales y conectarse a servidores; mantenlo limitado a localhost y usa su autenticación. Desactivarla es un riesgo, no una optimización.

¿Por qué falla un test MCP tras actualizar a 2026-07-28?

La era moderna elimina el handshake initialize y la sesión de transporte. Revisa qué versión promete tu servidor, deja que el cliente negocie o fija una matriz explícita y actualiza fixtures heredados.

¿Qué debo verificar en una tool mutante?

Además del schema, verifica scopes, identidad derivada en backend, idempotencia, confirmación humana cuando aplique, auditoría y que una identidad de otro tenant no pueda inferir datos ni ejecutar la acción.

Cómo añadir MCP Inspector a CI para un servidor MCP

Definir el contrato. Documenta tools, resources y prompts públicos con schemas, efectos, scopes, límites y errores esperados.
Compilar el artefacto. Ejecuta el build del servidor y prueba el binario o archivo resultante, no una ruta de desarrollo distinta.
Arrancar con fixtures. Inicia el servidor en stdio o un contenedor efímero con datos controlados y sin secretos de producción.
Listar superficies. Ejecuta Inspector CLI para consultar tools, resources y prompts y compara una salida normalizada con el contrato aprobado.
Llamar una tool segura. Ejecuta una llamada representativa con argumentos válidos y valida structuredContent, límites y resultado de negocio.
Añadir casos negativos. Prueba schema inválido, timeout, proveedor caído y dos identidades de test para confirmar autorización y aislamiento.
Probar compatibilidad. Repite sobre cada transporte y versión MCP que declares soportar, especialmente tras actualizar SDK o Inspector.
Cerrar el entorno. Recoge trazas y resultados redactados, detén el proceso efímero y falla el job si cambia el contrato o se filtran datos.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Codex CLI: configura AGENTS.md, perfiles y permisos sin convertir el repo en una excepción

Khavel — Mon, 24 Aug 2026 09:15:32 +0000

Codex CLI es el cliente local de terminal para inspeccionar, editar, ejecutar comandos y automatizar trabajo repetible sobre un repositorio. La keyword principal es Codex CLI; la intención de búsqueda es práctica: instalarlo no basta, un developer quiere saber qué poner en AGENTS.md, dónde vive config.toml, cómo usar perfiles y cómo evitar permisos globales que nadie pueda explicar.

TL;DR

La configuración que recomiendo tiene tres capas: instrucciones de repo para el comportamiento, configuración personal para preferencias de máquina y perfiles para el riesgo de cada tarea. No metas todas las reglas en un prompt, ni todos los permisos en un config.toml global.

Mi postura: el preset cómodo de escritura en workspace es buen punto de partida para desarrollo local; danger-full-access y red abierta no son un perfil de productividad. Son excepciones temporales que deben tener un motivo, una tarea y una revisión.

Qué configura Codex CLI exactamente

Codex CLI puede trabajar de forma interactiva, con codex exec en scripts o CI, y con la misma base de configuración que la extensión de IDE. La CLI tiene comandos visibles para iniciar instrucciones (/init), consultar el estado (/status), elegir permisos (/permissions) y revisar cambios (/review). El valor no es el terminal en sí: es poder convertir ese ciclo en una configuración reproducible.

Separa dos preguntas que suelen mezclarse: qué sabe el agente sobre el proyecto y qué puede hacer. AGENTS.md explica comandos, restricciones y criterios de aceptación; sandbox, red y approval policy controlan capacidades reales. Una frase que prohíbe publicar no bloquea un token con permisos para publicar.

La instrucción guía la tarea; el perfil y el sandbox delimitan lo que el agente puede hacer; la aprobación decide cuándo debe detenerse.

La jerarquía que evita sorpresas

Las opciones no viven en un único archivo. Codex aplica primero flags de CLI y valores --config, después .codex/config.toml desde la raíz al subdirectorio actual, después el perfil seleccionado, después ~/.codex/config.toml y finalmente valores por defecto. Los ficheros de proyecto solo se cargan cuando confías en el proyecto; eso evita que clonar un repo active configuración, hooks o reglas sin tu decisión.

Usa esa precedencia para no crear una bola de nieve. En ~/.codex/config.toml deja defaults personales que no dependen del repo. En .codex/config.toml deja solo ajustes de proyecto que el equipo puede revisar. En un perfil coloca la diferencia de riesgo: por ejemplo, revisión de solo lectura frente a edición local con red controlada.

AGENTS.md es un contrato operativo, no un README duplicado

Codex construye una cadena de instrucciones al inicio de cada ejecución: lee una guía global y después recorre desde la raíz Git hasta el directorio actual. En cada nivel, AGENTS.override.md gana a AGENTS.md; los archivos más cercanos al código aparecen al final y por tanto refinan las reglas generales. No conviertas esto en una enciclopedia: el límite combinado es de 32 KiB por defecto y una instrucción crítica enterrada deja de ser una instrucción.

Un AGENTS.md de raíz debería responder a preguntas operativas: cómo instalar, qué comandos validan, qué rutas son sensibles, qué cambio exige migración o revisión, y qué nunca debe incluirse en logs o commits. Un override bajo services/payments/ puede añadir comandos y límites de esa zona sin contaminar el resto del monorepo.

No guardes secretos, claves, playbooks de incidente completos ni datos de clientes. El archivo se entrega como contexto a un agente: es un contrato de trabajo, no una caja fuerte.

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Ejemplo mínimo: un repo con guardrails verificables

Este ejemplo es deliberadamente corto. No intenta describir el producto; declara las pocas reglas que cambian el resultado de una tarea. Las políticas reales de aprobación y red viven en configuración, no en Markdown.

Lo que conviene comprobar

AGENTS.md

# Contrato de trabajo del repositorio

## Antes de editar
- Lee docs/architecture.md y ejecuta npm ci.
- No modifiques .github/workflows, infra/ ni migraciones sin pedir aprobación.

## Validación
- Ejecuta npm run lint y npm test para cambios en src/.
- Explica en el resultado los tests que no pudiste ejecutar.

## Datos
- Nunca imprimas variables de entorno ni copies datos de producción a fixtures.

Para comprobar qué se cargó, inicia una sesión nueva desde la raíz y pide a Codex que enumere las instrucciones activas; desde un subdirectorio, repite la comprobación. Si la explicación no coincide con tu jerarquía, corrige el archivo más cercano o un override olvidado antes de automatizar nada.

Perfiles: el permiso debe seguir la tarea

Un perfil no es una identidad de persona; es una política para un tipo de trabajo. Crea uno de lectura para explorar o revisar, uno de edición de workspace para cambios locales y uno aislado para una tarea que necesita red. Evita el perfil todopoderoso que se convierte en el default por pereza.

Los perfiles viven junto a la configuración de usuario y se seleccionan con --profile. Eso permite que config.toml guarde una base común mientras cada perfil cambia lo mínimo: sandbox, política de aprobación y, cuando sea imprescindible, la política de red. No intentes mover credenciales de proveedor o telemetría a .codex/config.toml del repo: la documentación reserva esas claves para el nivel de usuario.

La regla que funciona: el CI no hereda el perfil de tu portátil, y el repositorio no puede rebajar la política de tu máquina. Define la cuenta, secretos y permisos del runner por separado y ejecuta un modo no interactivo solo si ya tienes un contrato de validación y rollback.

Un config.toml razonable para empezar

El siguiente perfil permite editar dentro del workspace y deja las decisiones que amplían capacidad bajo aprobación. No es una configuración universal: es un punto de partida que debes probar en un repositorio sin datos sensibles.

~/.codex/local-edit.config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false
Lánzalo con codex --profile local-edit y consulta /status antes de la primera tarea. Si necesitas documentación o una dependencia, no conviertas la sesión entera en red abierta: crea un perfil de investigación limitado o pide aprobación para esa operación concreta.

Sandbox, aprobación y red son controles distintos

El sandbox define la frontera técnica —por ejemplo, lectura, escritura en workspace o acceso más amplio—; la approval policy define cuándo Codex se detiene para pedir autorización. Con el modo Auto (workspace-write y on-request), puede editar y ejecutar dentro del directorio de trabajo, pero debe pedir permiso para salir de ese límite o usar la red.

La red merece una decisión aparte. Con workspace-write, está apagada salvo que la actives. Si la activas sin proxy, el tráfico saliente es directo y no queda limitado por una lista de dominios. Para restringir destinos, activa features.network_proxy y declara reglas allowlist; el proxy no concede red por sí solo. * equivale a red pública amplia, no a una lista de seguridad.

Las tools MCP y las integraciones no quedan automáticamente filtradas por ese proxy de comandos. Revisa sus propios scopes, sus anotaciones de efectos y sus políticas de aprobación. El modelo puede encadenar herramientas: analizar cada permiso aislado es menos útil que mirar el flujo completo de datos.

Qué no automatizar todavía

No ejecutes con approval_policy = "never" una acción que publique, borre, migre datos, rote secretos, cambie infraestructura o escriba fuera de un entorno de pruebas. El modo no interactivo es para operaciones repetibles cuyo diff, test, destino y rollback ya están definidos; no para eliminar fricción cuando aún no hay control.

Tampoco confundas tests verdes con autorización. Un test puede demostrar comportamiento local y aun así no saber si el usuario tiene permiso para enviar un correo, desplegar un cambio o leer un recurso de otro tenant. Esas barreras viven en el backend, los tokens y los entornos, no en la conversación.

Checklist de adopción para un equipo

Añadir un AGENTS.md raíz de menos de dos pantallas con setup, validación, rutas sensibles y manejo de datos.
Crear un override solo donde la regla sea realmente local, y probar qué archivos carga Codex desde esa carpeta.
Definir perfiles de lectura, edición y red limitada; empezar por lectura o edición sin red.
Mantener on-request para cambios de entorno, red, rutas protegidas y herramientas con efectos.
Separar la configuración del runner de CI de la configuración personal de un developer.
Revisar el diff, los comandos y los tests, y registrar por qué se permitió una excepción de permisos.
Medir bloqueos, reintentos, revisiones rechazadas y tiempo ahorrado antes de ampliar autonomía.

Preguntas frecuentes

¿Qué es Codex CLI?

Es el cliente de terminal de Codex para inspeccionar repositorios, editar archivos, ejecutar comandos y automatizar flujos repetibles desde el directorio del proyecto.

¿Dónde vive config.toml?

La configuración personal vive en ~/.codex/config.toml; los repos pueden añadir .codex/config.toml, que Codex carga solo para proyectos de confianza y que no puede reemplazar claves sensibles de nivel máquina.

¿Qué diferencia hay entre AGENTS.md y config.toml?

AGENTS.md aporta instrucciones y contexto; config.toml controla opciones del cliente como perfiles, sandbox, aprobaciones, red y servidores MCP. Un archivo de instrucciones no concede ni revoca permisos técnicos.

¿Debo usar approval_policy never?

Solo en automatizaciones estrechas y verificadas donde la acción, el entorno, el rollback y los límites de datos ya estén definidos. Para trabajo exploratorio o mutaciones sensibles, conserva aprobación humana.

¿La allowlist de red se activa sola al declarar dominios?

No. Debes habilitar red y el network proxy; con red apagada el proxy no hace nada, y con red encendida sin proxy el tráfico sigue siendo directo.

¿Puedo usar el mismo perfil en mi portátil y CI?

No es buena idea. CI necesita una identidad, secretos, permisos y rollback específicos; no debe heredar una configuración interactiva personal.

Cómo configurar Codex CLI en un repositorio de forma segura

Crear un checkpoint. Confirma que el repositorio está limpio o registra el estado actual antes de pedir un cambio al agente.
Escribir el contrato raíz. Añade AGENTS.md con setup, comandos de validación, rutas sensibles y reglas de datos que el equipo pueda comprobar.
Probar la jerarquía. Desde la raíz y desde un subdirectorio, pide a Codex que enumere las instrucciones activas y corrige overrides inesperados.
Elegir el perfil base. Empieza con lectura o workspace-write con approval_policy on-request y red desactivada.
Separar excepciones. Crea un perfil de investigación o una aprobación puntual para red; no rebajes el perfil base por una única tarea.
Configurar la red con límites. Si necesitas red, activa network_proxy y permite solo hosts concretos necesarios para la tarea.
Ejecutar una tarea reversible. Usa documentación, tests o un cambio pequeño en un repositorio de riesgo medio y revisa comandos, diff y evidencia.
Medir antes de ampliar. Registra bloqueos de permisos, tests fallidos, reintentos y hallazgos de revisión durante varias tareas.
Automatizar al final. Usa codex exec en CI solo cuando las entradas, acciones permitidas, aprobación, validación y rollback estén definidos fuera del prompt. > ### Límite sano > > Paraleliza investigación y tareas acotadas. No paralelices criterio técnico ni integración final.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

An embedding model's price is a one-time cost. Its dimensions are a subscription.

Khavel — Tue, 18 Aug 2026 11:44:06 +0000

Embedding models are billed per 1M input tokens, so that's the number that ends up in the comparison. Here are the nine generally-available embedding models that publish a token price, every rate re-read off the provider's own page this morning (2026-08-17):

Model	Provider	$/1M input	Default dims	Max input tokens
`text-embedding-3-small`	OpenAI	$0.02	1536	8192
`amazon.titan-embed-text-v2`	Amazon	$0.02	1024	8192
`text-embedding-v4` (Qwen)	Alibaba	$0.07	1024	8192
`embed-v4.0`	Cohere	$0.12	1536	128,000
`text-embedding-3-large`	OpenAI	$0.13	3072	8192
`nova-2-multimodal-embeddings`	Amazon	$0.135	3072	8192
`gemini-embedding-001`	Google	$0.15	3072	2048
`codestral-embed`	Mistral	$0.15	1536	8192
`gemini-embedding-2`	Google	$0.20	3072	8192

(The Model column is the provider's own model string; the ids in our feed are normalised slightly differently — you'll see both at the end.)

Top to bottom, that's a 10x spread. It is also, for most retrieval workloads, the least consequential number on the row.

The ingestion bill is one-time, and it is small

Take a corpus of 1,000,000 documents averaging 800 tokens. That's 800M tokens to embed.

At $0.02/1M: $16.00
At $0.20/1M: $160.00

The entire 10x spread is $144, once. You will spend more than that deciding which model to use. The token price only becomes interesting again when you re-embed — a model migration, or a corpus that grows continuously — and even then it's a function of new tokens, not of the corpus you already indexed.

Meanwhile the thing you're actually buying is a pile of float vectors that you will store, index, and hold in RAM for as long as the product exists.

The vector is what recurs

One million vectors, float32:

Dimensions	Size
3072	12.29 GB
1536	6.14 GB
1024	4.10 GB
768	3.07 GB
256	1.02 GB

I'm deliberately not multiplying that by a vector-database rate — every managed vector store prices differently and I'm not going to invent a number. Use your own. The point is the shape: this one is monthly, it scales linearly with the dimension count, and picking the 3072-dim model over the 1024-dim one triples it forever.

…except the dimension is usually a knob, not a spec

This is the part that makes the comparison table misleading rather than merely incomplete. On most current models, the dimension count you see published is a default, and you can ask for a smaller vector:

OpenAI — a dimensions request parameter, which its API reference says is supported on text-embedding-3 and later models.
Cohere — embed-v4.0's docs table gives its dimensions as a choice of 256, 512, 1024 or 1536, with 1536 the default.
Google — an output_dimensionality parameter, via Matryoshka Representation Learning. Both Gemini embedding models default to 3072 and Google's docs say you can truncate below that without losing quality, recommending 768, 1536 or 3072.
Amazon — Titan Text Embeddings V2 is documented as having "configurable output dimensions", set via dimensions in the request body.

And Google publishes the trade-off as a table, which is the most useful thing I found all week. MTEB score by truncated dimension, for gemini-embedding-001:

MRL dimension	MTEB score
2048	68.16
1536	68.17
768	67.99
512	67.55
256	66.19
128	63.31

Read that carefully. 1536 scores fractionally higher than 2048. Going from 1536 down to 768 costs 0.18 MTEB points and halves your storage, your index size and your RAM. The cliff doesn't arrive until 256, and it doesn't get steep until 128.

So the honest version of "this model is 3072-dimensional" is "this model defaults to 3072 and its own vendor recommends 768 as a supported option". Those imply storage bills a factor of four apart.

The number that really is fixed: the input ceiling

The context window is the field on these rows that you cannot negotiate, and it varies more than the other two. Cohere's own current lineup spans the entire range:

embed-english-v3.0 — 512 tokens
embed-v4.0 — 128,000 tokens

That's 250x, same vendor, both generally available today. Google moved from 2048 on gemini-embedding-001 to 8192 on gemini-embedding-2. Most of the rest sit at 8192.

Why it compounds: the ceiling caps your chunk size, chunk size sets your vector count, and vector count multiplied by dimensions is your storage and your index. Chunking the same corpus against a 512-token ceiling instead of an 8192-token one yields 16x the vectors. Your token spend barely moves — it's the same text either way — while everything downstream of the embedding call multiplies.

To be fair to the small-context models: almost nobody chunks at the ceiling, because retrieval quality usually wants smaller chunks than the maximum anyway. The ceiling doesn't dictate your chunk size. It removes options, and it's the only one of the three fields where the provider makes the decision for you.

Rerank: there is no ladder to write

I wanted to end with the same table for rerankers. It doesn't exist, and the reason is worth more than the table would have been.

Of the 7 GA rerank models we track, 3 publish a rate, and the unit isn't tokens:

Model	Provider	Price
Amazon Rerank v1	Amazon	$1.00 per 1,000 searches
Rerank 4 Fast	Cohere	$2.00 per 1,000 searches
Rerank 4 Pro	Cohere	$2.50 per 1,000 searches

A "search" is not a standard unit, and it is not a token. AWS's price book bills its reranker in search units — $1 per 1,000 of them — where a unit is a query carrying some bounded number of document chunks, defined in the docs rather than on the price line. Cohere bills per 1,000 searches. Whether those two units mean the same thing for your query shape is your problem, not something either price implies.

That AWS model is also region-scoped in a way the price book makes plain: the SKU (Z7M6S4MRBXNXJRB4) is in us-west-2, and there is no rerank SKU in the us-east-1 price book at all.

The other four GA rerankers publish no first-party rate we could find. In our data those fields are null, which is a fact about the provider, not a gap we're papering over.

Get it as data

All of the above is in a free JSON feed — no key, no signup, CORS open. (If you would rather just look at the 13 rows, they are on one page too.)

curl -s https://aimodelwatch.dev/api/models.json \
  | jq -r '.models[]
      | select(.embedding_dimensions != null and .status == "ga")
      | [.price_input_per_mtok, .embedding_dimensions, .context_window, .id]
      | @tsv' \
  | sort -g

Output, run against the live endpoint today:

0.02    1024    8192    amazon-titan-embed-text-v2
0.02    1536    8192    text-embedding-3-small
0.07    1024    8192    qwen-text-embedding-v4
0.12    1536    128000  embed-v4-0
0.13    3072    8192    text-embedding-3-large
0.135   3072    8192    amazon-nova-2-multimodal-embeddings
0.15    1536    8192    codestral-embed
0.15    3072    2048    gemini-embedding-001
0.2     3072    8192    gemini-embedding-2
        384     512     embed-english-light-v3-0
        384     512     embed-multilingual-light-v3-0
        1024    512     embed-english-v3-0
        1024    512     embed-multilingual-v3-0

The four rows with a blank price are Cohere's v3 embedding family. They're still GA and still documented; Cohere's pricing page currently lists only Embed 4 among its embedding models, so there is no first-party rate to carry. A blank there means "the provider doesn't publish this", not "we didn't look" — every row carries the source_url it was read from.

One honest note while you're looking at that output. The two OpenAI rows read 8191 when this was drafted, and I'd written 8192 in the table at the top. Both numbers are first-party: 8191 is the figure OpenAI's 2024 new-embedding-models announcement carried, and the current API reference states "the max input tokens for the model (8192 tokens for all embedding models)". The disagreement was reconciled to 8192 on 2026-08-18 — the reference states the limit as a constraint on the input parameter, i.e. it carries the field as data, while the model spec pages state no limit at all. It's one token out of eight thousand and it changes nothing in this article. I'm leaving the paragraph in because a catalog that quietly rounds its own disagreements away isn't worth querying — and because you can see the audit trail: the row's notes field records the old value, the new one, and which surface won.

Data from AI Model Watch — 231 models, prices and lifecycle dates read from official provider documentation, refreshed daily, with null where the provider publishes nothing. Free JSON: /api/models.json and /api/deprecations.json.

OpenAI Responses API: function calling fiable, estado y trabajos en segundo plano

Khavel — Mon, 17 Aug 2026 09:25:11 +0000

Responses API no convierte una función en fiable por sí sola. Esta guía muestra el bucle correcto de tool calls, validación, estado y trabajos largos para que un agente no confunda una respuesta convincente con una acción segura.

OpenAI Responses API es la interfaz unificada para generar respuestas, usar herramientas y conservar estado entre turnos. Un tool call no es una orden que el servidor deba obedecer: es una propuesta del modelo que tu backend debe autorizar, validar, ejecutar de forma idempotente y devolver al modelo como function_call_output.

TL;DR

La keyword principal es OpenAI Responses API. La intención es técnica: un developer que ya puede hacer una llamada básica necesita montar un flujo fiable con function calling, JSON estructurado, streaming, estado conversacional y trabajos que no caben en una petición HTTP corta.

Mi postura: empieza con Responses API antes de introducir una capa de agentes. Es un contrato explícito que te obliga a entender input, output, tools y estado. Un SDK de agentes puede ahorrar orquestación después; no debería ocultar permisos, validación ni efectos externos.

Qué es Responses API y qué no resuelve

Responses API crea un objeto response a partir de un modelo, una entrada y, opcionalmente, herramientas. La salida no tiene por qué ser texto: puede contener mensajes, llamadas de función, resultados de herramientas alojadas, elementos de razonamiento y eventos de streaming. Leer solo output_text es correcto para un chat simple, pero insuficiente para un flujo que actúa sobre sistemas reales.

La API puede encadenar contexto con previous_response_id o con Conversations. Eso evita reenviar un historial manual enorme, pero no sustituye tu modelo de negocio: tú decides qué conversación pertenece a qué usuario, cuánto vive, qué datos se permiten y cuándo hay que resumir o borrar estado.

Tampoco decide si una llamada es segura. El modelo puede proponer create_invoice, send_email o deploy. Tu aplicación sigue siendo el control de autoridad: autentica al usuario, limita el recurso, valida argumentos, exige aprobación cuando corresponde y registra el efecto final.

El modelo propone pasos; el backend conserva la autoridad. Estado, validación, colas y auditoría son piezas distintas del texto generado.

El bucle correcto de function calling

Function calling tiene cuatro etapas: declaras una tool con un schema; el modelo emite uno o más elementos function_call; tu servidor valida y ejecuta solo los que autoriza; devuelves un function_call_output con el call_id original y pides la siguiente respuesta. Si falta el último paso, el modelo no ve el resultado real de la acción y tenderá a completar la conversación con una suposición.

No ejecutes argumentos directamente con json.loads y una llamada a tu SDK interno. El schema reduce salidas mal formadas, pero no prueba que el usuario tenga acceso a project_id, que una fecha exista ni que la acción sea razonable. Valida tipos, rangos, pertenencia al tenant y política de negocio fuera del modelo.

Para una operación con efecto, asocia una clave idempotente a la intención de negocio, no al texto del modelo. Un retry HTTP, una reconexión de streaming o una segunda respuesta no debe enviar dos emails o crear dos facturas. Guarda call_id, usuario, recurso, hash del payload y resultado de la ejecución.

Código: tool estrecha y resultado verificable en Python

Este ejemplo ilustra el bucle. La tool es deliberadamente de lectura y el resultado vuelve como datos, no como instrucciones. En producción, get_release debería imponer autorización y recuperar solo los campos permitidos para el usuario autenticado.

responses_tools.py

import json
from openai import OpenAI

client = OpenAI()
TOOLS = [{
    "type": "function",
    "name": "get_release",
    "description": "Returns approved release metadata for one repository.",
    "parameters": {
        "type": "object",
        "properties": {"repo": {"type": "string", "minLength": 1}},
        "required": ["repo"],
        "additionalProperties": False,
    },
    "strict": True,
}]

def get_release_for_user(user_id: str, repo: str) -> dict:
    assert repo in allowed_repos_for(user_id)  # authz, not a model prompt
    return read_release_metadata(repo)

response = client.responses.create(
    model="gpt-5",
    input="¿Cuál es el último release de api-gateway?",
    tools=TOOLS,
)

tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_release":
        args = json.loads(item.arguments)
        result = get_release_for_user(current_user.id, args["repo"])
        tool_outputs.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps(result),
        })

final = client.responses.create(
    model="gpt-5",
    previous_response_id=response.id,
    input=tool_outputs,
)
print(final.output_text)

El detalle importante no es el nombre de la función: es que allowed_repos_for vive en tu backend. Si el modelo propone otro repo, la autorización falla antes de tocar la fuente de datos. Devuelve un error de dominio breve y deja que el modelo explique el límite al usuario, en vez de darle una excepción cruda o inventar una respuesta.

Structured Outputs: contrato de interfaz, no control de seguridad

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Cuando necesitas una salida que otro sistema consuma, usa Structured Outputs con JSON Schema estricto. En Responses API el formato se configura dentro de text.format; para tools, define strict: true y limita propiedades. Eso hace que el contrato sea más predecible que pedir «devuelve JSON válido» en un prompt.

Lo que conviene comprobar

Un schema debe representar una decisión pequeña y verificable. Para triage, por ejemplo: categoría de una allowlist, confianza acotada, evidencia citada y needs_human_review. Evita un objeto genérico tipo action: string que luego se convierte en una puerta trasera de comandos para cualquier integración.

Trata cualquier campo generado como entrada no confiable al cruzar una frontera. strict evita muchas formas inválidas; no sustituye escape HTML, validación de URLs, autorización, control de concurrencia, límites de tamaño ni saneamiento para SQL o shell. Un JSON impecable puede describir una acción equivocada.

Estado: previous_response_id frente a Conversations

previous_response_id es útil para enlazar el siguiente turno al anterior con una relación explícita. Es cómodo en una conversación corta o en un workflow donde tu base de datos guarda el último response ID por sesión. Las instrucciones de una llamada anterior no se arrastran automáticamente si pasas instrucciones nuevas: verifica ese comportamiento antes de asumir que una política quedó vigente.

Conversations es una entidad de estado reutilizable para añadir y recuperar ítems entre respuestas. Encaja cuando necesitas una conversación estable que pueda sobrevivir a distintos dispositivos o workers. Aun así, no conviertas la Conversation en tu única fuente de verdad: conserva en tu base la identidad del usuario, el tenant, el estado de aprobación y referencias de auditoría.

Mi regla: guarda solo IDs y contexto mínimo de producto; vuelve a resolver permisos, herramientas permitidas y policy en cada petición. El estado puede recordar la conversación, pero no debe heredar autoridad. Un usuario que pierde acceso a un proyecto no debería mantenerlo porque una conversación vieja lo mencionaba.

Streaming y background mode son flujos distintos

Streaming usa eventos server-sent para pintar progreso o texto parcial con baja latencia. Es una decisión de experiencia de usuario; no conviertas cada delta en un registro de negocio ni ejecutes una tool al primer fragmento. Espera al elemento de function call completo y conserva una ruta clara de cancelación del cliente.

Background mode sirve para respuestas largas que deben continuar aunque la petición web se corte. Creas la respuesta con background=true, persistes su ID y consultas su estado o recibes el evento webhook correspondiente. El frontend no debería mantener una conexión abierta durante minutos solo para fingir que un job asíncrono es streaming.

La consecuencia operativa importa: background mode conserva datos para poder hacer polling y no es compatible con Zero Data Retention. Revisa data controls, retención y la región de datos de tu organización antes de activarlo en flujos con información sensible. Para una tarea larga sin datos que deban salir, una cola propia y una llamada normal puede ser una alternativa más controlable.

Herramientas alojadas, MCP y límites de datos

Responses API puede combinar funciones de tu aplicación con herramientas alojadas, como web search, file search, code interpreter o image generation, según modelo y disponibilidad. Cada una introduce otra frontera: cuota, tiempo, datos enviados y resultados que pueden estar equivocados o contener instrucciones externas.

Los servidores MCP remotos son servicios de terceros. No les pases un token o documento solo porque una tool description sea atractiva. Delimita por servidor la URL, identidad, scopes, datos que puede recibir, rate limits y la aprobación para efectos externos. MCP conecta capacidades; no valida automáticamente su confianza.

Usa allowed_tools o un conjunto de tools por tarea cuando sea posible. Un agente de triage no necesita la misma superficie que uno de release. Reducir opciones también mejora la calidad: al modelo le cuesta menos elegir una tool cuando no le ofreces quince acciones parecidas con permisos distintos.

Arquitectura mínima que llevaría a producción

Entrada autenticada → policy de tenant → creación de response → parser de output → validador de schema y negocio → executor idempotente → auditoría → function_call_output → respuesta final. Si hay una acción sensible, añade una transición explícita de propuesta a aprobación: el modelo prepara payload y evidencia; una persona o regla independiente habilita la mutación.

Mantén los executors fuera del prompt. Una tool debería ser una función estrecha, con nombre que explique el efecto, parámetros mínimos y un resultado redactado. update_customer es demasiado grande; propose_customer_address_change y apply_approved_address_change dejan una frontera revisable.

Mide más que éxito HTTP: porcentaje de tool calls válidas, denegadas por policy, reintentos idempotentes, aprobaciones, errores por tipo, latencia p50/p95, coste por workflow y tareas resueltas sin escalado. Una respuesta fluida puede ocultar que el modelo llama tres veces a una API o que el 20% de acciones queda bloqueado al final.

Checklist antes de habilitar una tool con efecto

La tool expresa una única capacidad y no acepta campos libres que acaben en SQL, shell o URLs arbitrarias.

El backend autentica al usuario y comprueba autorización por tenant, recurso y operación; el modelo no decide permisos.

Los argumentos pasan JSON Schema y validación de negocio antes de llegar a un executor.

Las mutaciones tienen una clave idempotente y un registro de resultado por operación de negocio.

Las acciones externas o irreversibles muestran destino, payload, evidencia y riesgo antes de la aprobación.

Las tools disponibles se reducen por tarea y se revisan al cambiar de modelo, prompt o integración.

El estado conversacional no concede permisos persistentes y tiene una política de retención explícita.

Streaming, background jobs y webhooks tienen timeouts, cancelación, reintentos y observabilidad propios.

Hay evals con entradas ambiguas, argumentos inválidos, recursos de otro tenant y prompt injection indirecta.

Conclusión

Responses API es una buena base cuando quieres control fino: te enseña exactamente cuándo el modelo habló, cuándo pidió una tool y cuándo tu sistema produjo un resultado verificable. Esa claridad vale más que una demo de agente que parece autónoma hasta que intenta escribir en producción.

Empieza por una tool de lectura, un schema pequeño y una traza completa. Añade estado cuando haya una razón de producto, y background mode cuando el trabajo de verdad sea largo. La autonomía útil no consiste en dar más funciones al modelo: consiste en hacer que cada capacidad tenga una frontera, una evidencia y una forma segura de fallar.

Preguntas frecuentes

¿Qué es OpenAI Responses API?

Es la API unificada de OpenAI para crear respuestas con input multimodal, herramientas, streaming y estado conversacional. La salida puede incluir texto y elementos de tool calling, no solo una cadena.

¿Responses API sustituye a OpenAI Agents SDK?

No necesariamente. Responses API ofrece el contrato de bajo nivel; Agents SDK puede ayudar a orquestar agentes. Si necesitas permisos y efectos controlados, debes implementar validación y autorización en cualquiera de las dos capas.

¿Function calling ejecuta mi función automáticamente?

No. El modelo devuelve una propuesta de llamada; tu aplicación interpreta el output, valida argumentos y permisos, ejecuta si procede y devuelve un function_call_output.

¿Para qué sirve previous_response_id?

Enlaza una respuesta nueva con el contexto de la respuesta anterior. Es útil para turnos cortos, pero no sustituye una política de identidad, autorización o retención de datos.

¿Cuándo uso background mode?

Cuando una respuesta puede durar más que la petición HTTP normal y quieres consultar su estado o recibir un webhook. Revisa antes su efecto en retención de datos y compatibilidad con Zero Data Retention.

¿Structured Outputs hace segura una acción?

No. Hace más predecible el formato. Todavía debes validar negocio, scopes, tenant, recursos, límites, idempotencia y aprobación humana cuando exista efecto externo.

Cómo llevar una tool de Responses API de demo a producción

Elegir una capacidad de lectura. Empieza por una consulta reversible con un recurso claro, como recuperar metadata de un release aprobado.
Diseñar el schema. Declara campos mínimos, tipos, allowlists y additionalProperties: false; activa modo estricto cuando sea compatible.
Separar autorización. Resuelve usuario, tenant, scopes y recurso en el backend antes de llamar a la fuente de datos.
Crear el primer response. Envía el input y solo las tools necesarias para esa tarea; registra el response ID y la versión de policy.
Interpretar function calls. Procesa únicamente elementos completos de tipo function call; no ejecutes texto libre ni deltas de streaming.
Validar y ejecutar. Comprueba schema y reglas de negocio, aplica rate limits e idempotencia y captura un resultado redactado.
Devolver function_call_output. Usa el call ID original y datos estructurados para que el siguiente response pueda explicar el resultado real.
Añadir aprobación. Separa propuesta y mutación cuando la acción escriba, envíe, despliegue o transfiera información.
Preparar fallos. Define errores de autorización, validación, proveedor y timeout; cada uno debe tener una recuperación distinta.
Medir y evaluar. Prueba tenants cruzados, argumentos hostiles y retries; mide tools inválidas, bloqueos, coste, latencia y resolución.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

MCP Registry: cómo publicar y descubrir servidores MCP sin confiar a ciegas

Khavel — Thu, 13 Aug 2026 10:48:35 +0000

El MCP Registry mejora el descubrimiento de servidores, no certifica que sean seguros. Aprende a publicar metadata reproducible y a construir una allowlist interna que trate cada servidor como una dependencia con privilegios.

Un MCP Registry es un catálogo con una API estándar para describir y descubrir servidores MCP. El registro oficial publica metadata —nombre, versión, repositorio, paquete o endpoint remoto—; no hospeda tu binario ni convierte un servidor listado en seguro o adecuado para tu empresa.

TL;DR

La keyword principal es MCP Registry. La intención es técnica y práctica: un maintainer quiere publicar un servidor reproducible, y un equipo quiere descubrirlo sin transformar una búsqueda de herramientas en una puerta de entrada a paquetes y credenciales no revisados.

Mi postura: usa el registro público como inventario y canal de distribución de metadata, no como una lista de confianza. La unidad de confianza sigue siendo una versión concreta de un artefacto, su código, sus tools, su identidad de ejecución y los permisos que le concedes.

Qué es MCP Registry y qué problema resuelve

MCP Registry es la especificación y el ecosistema de registros para servidores Model Context Protocol. El Official MCP Registry, en registry.modelcontextprotocol.io, es un catálogo público de metadata y una API REST sobre la que pueden construirse marketplaces o sub-registros. Su valor es que un cliente no tenga que adivinar cómo encontrar, instalar o actualizar cada integración.

La frase importante es metadata. Un server.json puede apuntar a un paquete npm, PyPI, una imagen OCI o un endpoint remoto, junto a los transportes y la configuración de arranque. El registro no ejecuta ese servidor por ti ni inspecciona exhaustivamente lo que hará cuando tenga acceso a tu filesystem, red, OAuth o secretos.

Eso separa tres cosas que se confunden con facilidad: descubrimiento (encontrar una ficha), procedencia (saber quién puede publicar un namespace) y confianza operativa (decidir si esta versión recibe permisos en tu entorno). El registro ayuda mucho con las dos primeras; la tercera es una política tuya.

Un registro público resuelve discovery; la allowlist y los controles de ejecución resuelven el riesgo de introducir una nueva dependencia con capacidades de agente.

El modelo mental correcto: catálogo, no sello de seguridad

Que un servidor aparezca en un registro oficial no significa que sus dependencias sean benignas, que el maintainer siga controlando el paquete, que sus tool descriptions no hayan cambiado o que encaje con tus datos. La propia documentación lo presenta como un repositorio de información autodeclarada y, mientras siga en preview, avisa de posibles cambios incompatibles o resets de datos.

Trátalo como tratarías npm: una ficha reduce fricción de discovery y aporta campos comparables; no sustituye revisión de código, lockfile, análisis de dependencias, firma, sandbox o permisos mínimos. En MCP el impacto puede ser mayor que en una librería de UI porque el proceso puede recibir secretos y ejecutar operaciones en nombre de un usuario.

Una política sana empieza con esta pregunta: ¿qué puede leer, escribir, ejecutar o enviar este servidor después de instalarse? Si no puedes responderla para una versión fijada, no está listo para la allowlist, aunque tenga un nombre bonito, muchos installs o una referencia en un marketplace.

server.json: el contrato que publicas

server.json es la ficha versionada del servidor. Como mínimo declara un nombre único, descripción, versión, repositorio y una o más formas de distribución: packages para artefactos instalables o remotes para endpoints. Para un paquete también declara su registryType, identificador, versión y transporte; para un remoto, URL y transporte compatible.

No copies un ejemplo antiguo sin comprobar el schema que genera tu versión de mcp-publisher. El formato evoluciona durante preview. La forma menos frágil de empezar es mcp-publisher init, revisar el JSON resultante y validarlo en CI contra el schema actual antes de publicar. El contrato de registry no es el archivo de configuración con secretos que ejecuta el host.

Un ejemplo deliberadamente mínimo para un paquete npm por STDIO sería este. Sustituye los nombres, controla la versión desde tu release y no incluyas valores de secretos: la ficha solo puede describir variables requeridas, no contenerlas.

server.json

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.acme/release-notes",
  "description": "MCP server for approved release-note data.",
  "version": "1.4.0",
  "repository": {"url": "https://github.com/acme/release-notes-mcp", "source": "github"},
  "packages": [{
    "registryType": "npm",
    "identifier": "@acme/release-notes-mcp",
    "version": "1.4.0",
    "transport": {"type": "stdio"}
  }]
}

Mantén la descripción factual y breve. También es entrada para hosts y modelos: una descripción ambigua, promocional o con instrucciones operativas largas aumenta el riesgo de que un agente elija una capability que no debería tener.

Namespace y procedencia: quién puede afirmar ese nombre

El registro oficial asocia la publicación a un namespace. Para io.github.* usa identidad de GitHub; para dominios propios puede verificar DNS o HTTP. Esa verificación evita que cualquiera publique bajo com.tuempresa.*, pero no demuestra que todo el código de un repositorio o paquete sea seguro.

Lo que conviene comprobar

Elige un namespace que sobreviva a cambios de equipo. Si tu servidor es producto de una organización, un namespace de dominio verificado suele expresar mejor la propiedad que una cuenta personal. Documenta qué repositorio, pipeline y equipo pueden publicar y elimina permisos cuando alguien deja el proyecto.

En CI, separa el token que publica el artefacto del mecanismo que publica la metadata. El quickstart del registro ofrece autenticación GitHub/OIDC; úsala para que el pipeline pueda probar origen sin guardar una sesión humana de larga duración. Protege la rama y exige revisión del cambio de server.json, igual que harías con un workflow de release.

¿Te está sirviendo? Hay una dosis cada semana

Te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Versionado inmutable: publica un release, no una corrección silenciosa

Cada publicación de un servidor necesita una versión única. Una vez publicada, la metadata de esa versión es inmutable; si debes corregir descripción, repositorio, paquete o endpoint, publica otra versión. El registro intenta ordenar SemVer y marca la versión apropiada como latest, por lo que usar 1.4.0 de forma consistente simplifica a clientes y humanos.

No uses latest como versión de paquete en una allowlist. Fija la versión del artefacto y conserva su integridad en un lockfile, digest OCI o checksum cuando aplique. latest del registry es una conveniencia de discovery, no una orden para actualizar procesos de desarrollo sin revisar qué cambió.

Cuando solo ajustes metadata, una prerelease de registry puede ser preferible a fingir que el binario cambió. Pero no ocultes una modificación real de tools o permisos detrás de un parche menor: para el consumidor, añadir delete_repository es un cambio de riesgo aunque tu API siga siendo compatible.

Publicar paso a paso desde CI

El orden seguro es: compilar, probar y publicar el artefacto; verificar que es recuperable por su identificador y versión; generar o actualizar server.json; validar schema y coherencia; autenticar el publisher con identidad de CI; publicar la metadata; y consultar la API para confirmar que la versión concreta aparece. Si publicas la ficha antes que el paquete, invitas a instalaciones rotas.

Para npm, el registro pide que el paquete se vincule a su nombre MCP mediante mcpName. Esa comprobación reduce la distancia entre metadata y paquete. Añade además tests que arranquen el paquete exactamente como lo describe el server.json: comando, transporte, variables declaradas y un initialize de prueba sin tocar datos reales.

Un esqueleto de workflow puede ser tan simple como el siguiente. No es una receta para copiar secretos: el token OIDC y los permisos exactos dependen de tu proveedor y del namespace. La parte importante es que publicación sea una consecuencia de artefacto probado, no un comando manual desde un portátil.

release.sh (esquema)

npm ci
npm run build && npm test
npm publish --access public

node scripts/assert-server-json.mjs server.json
mcp-publisher login github-oidc
mcp-publisher publish server.json

curl --fail --silent   "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.acme/release-notes"

Haz que assert-server-json compare name, versión, repositorio y paquete contra package.json y la etiqueta Git. Es una comprobación pequeña que evita el fallo más tonto del ecosistema: publicar metadata de 1.4.0 que instala sin querer 1.3.2.

Consumir la API sin mezclar discovery y ejecución

La API v0.1 expone una lista de servidores y el detalle de una versión. Permite filtrar por search, pedir solo latest o sincronizar incrementalmente con updated_since. Esto es suficiente para construir una vista de catálogo o un job que detecte cambios; no lo conviertas en un instalador automático para cada resultado nuevo.

El patrón adecuado es ingestión → normalización → evaluación de política → aprobación → distribución. Tu job puede traer nuevas fichas a una base interna y marcar qué cambió, pero un servidor no pasa a ser ejecutable por un developer hasta que una persona o una regla verificable aprueba su versión, identidad, permisos y distribución.

Guarda la versión y la respuesta original que revisaste. Si el upstream se actualiza, compara el nombre del paquete, transporte, comando, URL, variables, tools observadas y permisos. Un cambio en cualquiera de ellos requiere reevaluación; no basta con que version=latest avance.

Sub-registro privado: la capa que una empresa realmente necesita

El registro oficial es para servidores públicamente accesibles; para un servicio interno o una dependencia aprobada solo para tu organización, crea un sub-registro privado o un catálogo compatible. GitHub documenta que una implementación v0.1 necesita endpoints de listado y detalle, además de CORS si un cliente lo consume desde navegador o IDE.

El sub-registro no tiene que duplicar toda la funcionalidad del público. Empieza con una allowlist inmutable y explícita: ID interno, server name upstream, versión exacta, fuente, owner, clasificación de datos, scopes permitidos, transporte, fecha de revisión y fecha de caducidad. Si falta owner o fecha, el ítem caduca en vez de quedarse como excepción eterna.

Puedes sincronizar fichas públicas como candidatos, pero no copies automáticamente todas. La ganancia real es cambiar la experiencia por defecto: el developer descubre únicamente servidores aprobados, y el host impide conexiones fuera de política cuando la plataforma lo permita.

Supply chain MCP: controles antes de dar una tool al modelo

Antes de instalar un paquete local, verifica el publisher, repositorio y artefacto; fija versión y lockfile; analiza dependencias; ejecuta el proceso con filesystem, red y variables mínimas; y revisa el comando que el host va a lanzar completo. La recomendación de OWASP es clara: un servidor MCP local puede convertirse en una vía de sandbox escape, exfiltración o ejecución arbitraria si recibe acceso total por comodidad.

Después de instalar, inspecciona también las tools: nombre, descripción, argumentos, outputs y destino. Las descripciones y schemas son superficie de prompt injection. Conserva un hash de la definición de tools que aprobaste y alerta si cambia; un servidor que hoy solo lee puede sufrir un rug pull mañana sin que cambie el nombre del paquete.

Para servidores remotos, añade otra capa: validación TLS, URL exacta, OAuth con audiencia y scopes estrechos, egress controlado y rate limits. Una ficha de registry puede hacer visible un endpoint; no concede a ese endpoint derecho a recibir tokens de tu usuario. Para el flujo OAuth completo, consulta nuestra guía de OAuth 2.1 para MCP.

De la ficha al host: consentimiento y aislamiento

El host debe enseñar qué se instala o conecta, qué comando se ejecutará en local, qué variables necesita y qué acciones expone. La aprobación del usuario no puede ser una tarjeta truncada con un botón «Conectar». Si el host no revela el comando completo, los permisos o la procedencia, el equipo pierde la evidencia necesaria para aprobarlo.

Aísla servidores como dominios de seguridad independientes. Un servidor de documentación no necesita el token de un servidor de deploy ni acceso a todos los archivos del repositorio. Da una credencial por servidor y entorno, monta solo los directorios imprescindibles y bloquea red saliente salvo destinos que puedas justificar.

Las mutaciones de impacto —escribir código, emitir una orden, cambiar un permiso, enviar datos fuera— deben seguir requiriendo aprobación con parámetros completos. Un registro resuelve cómo encontrar una tool; no decide cuándo un agente puede ejecutar una acción con consecuencias.

Observabilidad y renovación de confianza

Registra server name, versión, digest o lockfile, host, usuario o service account, tool, argumentos redactados, resultado, latencia y decisión de aprobación. Sin esa relación no podrás responder qué servidor consultó un dato o cambió un recurso cuando una alerta llegue semanas después.

Lo que conviene comprobar

Configura dos bucles de revisión. El primero es de cambios: nueva versión, nuevo paquete, endpoint, comando, tool o scope reabre la evaluación. El segundo es temporal: cada entrada aprobada expira en 90 o 180 días y necesita un owner que confirme que sigue mantenida y con el mismo riesgo aceptable.

Mide también fricción útil: solicitudes de alta, tiempo hasta revisión, instalaciones rechazadas, permisos denegados, tools poco usadas y cambios detectados. Si tu catálogo tarda semanas para un servidor de lectura de bajo riesgo, acabará apareciendo un bypass; si aprueba todo en cinco minutos, solo has creado una lista decorativa.

Checklist de publicación y consumo

El nombre MCP pertenece a un namespace que controlas y la identidad de CI puede probarlo.
Paquete o endpoint existen antes que la ficha y su versión coincide exactamente con server.json.
El schema se valida en CI y el proceso se arranca en una prueba de integración sin secretos reales.
Cada publicación usa una versión única; una corrección se publica como release nuevo, no se reescribe.
La ficha no incluye secretos ni se confunde con el archivo de configuración runtime del host.
El registro público entra en el flujo como fuente de discovery, nunca como allowlist automática.
La allowlist interna fija versión, fuente, owner, datos, scopes, transporte, fecha de revisión y expiración.
Los paquetes locales se fijan, escanean y ejecutan con sandbox, red, filesystem y credenciales mínimos.
Las definiciones de tools se inspeccionan y se vuelven a aprobar si cambian.
Las acciones sensibles muestran parámetros completos y requieren consentimiento o aprobación humana.

Conclusión

MCP Registry es una pieza necesaria para que el ecosistema deje de repartir fragmentos de configuración por README y capturas. Estandariza discovery y metadata, y permite que clientes y empresas hablen el mismo idioma de catálogo. Eso es valioso, pero no es una auditoría de seguridad.

Publica como maintainer con releases reproducibles, versiones inmutables y CI; consume como equipo con una allowlist, artefactos fijados, sandbox y reevaluación por cambios. Si conviertes un registry en «instalar lo que aparezca», acabas de automatizar la parte peligrosa de tu supply chain. Si lo usas para hacer explícitas procedencia y políticas, reduces fricción sin regalar privilegios.

Preguntas frecuentes

¿Qué es MCP Registry?

Es un estándar y catálogo de metadata para descubrir servidores Model Context Protocol. El Official MCP Registry ofrece una API pública para que clientes y sub-registros consulten fichas de servidores.

¿El MCP Registry oficial certifica que un servidor sea seguro?

No. Ayuda a descubrir metadata y comprobar propiedad de namespaces, pero no sustituye revisión de código, integridad del artefacto, permisos mínimos, sandbox ni controles de ejecución.

¿Qué contiene server.json?

Describe el nombre, versión, repositorio y cómo obtener o conectar el servidor, por ejemplo un paquete con transporte STDIO o un endpoint remoto. No debe almacenar secretos runtime.

¿Puedo cambiar un servidor ya publicado?

No se reescribe esa versión. Publica una versión nueva de server.json; las versiones publicadas son inmutables y deben ser únicas.

¿Necesito un registro privado para mi empresa?

Si quieres publicar servicios internos o aplicar una allowlist de servidores aprobados, sí. Puedes usar una implementación compatible v0.1 o un catálogo interno que fije versiones, owners, permisos y caducidad.

¿Debo instalar automáticamente los resultados del registry?

No. Úsalo para discovery y somete cada versión a política: publisher, paquete o endpoint, dependencias, tools, scopes, sandbox y aprobación antes de habilitarla.

Cómo publicar y gobernar un servidor con MCP Registry

Definir el límite. Enumera tools, datos, efectos y permisos; elimina capacidades que no pertenecen al primer release.
Publicar el artefacto. Compila, prueba y publica el paquete o endpoint antes de crear la ficha de registry.
Vincular la procedencia. Elige namespace, configura verificación GitHub, DNS o HTTP y limita quién puede publicar desde CI.
Generar server.json. Usa mcp-publisher init, declara versión exacta, repositorio y transporte sin incluir secretos runtime.
Validar en CI. Comprueba schema, coherencia con package metadata y un arranque real que complete initialize en sandbox.
Publicar una versión. Autentica el publisher con identidad de CI y registra la versión única; no reescribas releases publicados.
Verificar discovery. Consulta el detalle de esa versión en la API y guarda la respuesta revisada como evidencia de release.
Crear allowlist. Fija versión, fuente, owner, clasificación de datos, scopes, transporte, revisión y fecha de expiración.
Aislar ejecución. Usa credenciales por servidor, filesystem y red mínimos, y aprobación humana para acciones sensibles.
Reevaluar cambios. Altera paquete, endpoint, tool, schema o scope y obliga una revisión antes de avanzar a la nueva versión.

Fuentes y referencias

También te puede interesar

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis