# AX-SYS-44: Expón endpoints de retroalimentación para que los agentes informen sobre la calidad del contexto y los resultados de tareas

> Observability and governance · intermediate · AX-SYS-44

Dale a los agentes un canal para informar sobre lo que funcionó: relevancia del contexto, tasa de éxito de tareas, tiempo hasta el contexto útil. Sin endpoints de retroalimentación, no tienes un mecanismo automatizado para saber si tu AX mejora o empeora.

## Por qué

El marco canónico de AX (agentexperience.ax) incluye "Proporcionar retroalimentación" como un principio de primer nivel orientado a los agentes: *"Los agentes envían retroalimentación a los servicios digitales para que estos puedan mejorar la calidad de su oferta y su AX. Sin esta información, los servicios digitales no tienen un mecanismo de retroalimentación automatizado que garantice que el servicio funciona de forma consistente."*

Esto genera una obligación del lado del servicio: solo puedes recibir retroalimentación si expones una forma de recibirla. Como los agentes son no deterministas (el mismo prompt puede producir resultados distintos), la retroalimentación cualitativa y cuantitativa de las sesiones de agentes es la única señal fiable para saber si tus archivos de contexto, descripciones de herramientas y respuestas de API realmente funcionan. Biilmann documenta que Netlify usa la retroalimentación del bucle de agentes para validar las guías de Dev Hub: si un agente de generación de código no puede resolver una función de una sola pasada a partir del markdown, la guía falla.

> **Nota:** Este estándar aún está emergiendo. El sitio canónico reconoce que aprovechará "nuevos protocolos y protocolos/patrones existentes (por ejemplo, Open Telemetry)." Trata este principio como una orientación direccional: implementa lo que puedas con OpenTelemetry hoy y adáptate a medida que los estándares maduren.

## Haz

Expón un endpoint de retroalimentación o acepta spans de OpenTelemetry desde los clientes de agentes. Recopila como mínimo: tasa de acierto/fallo del contexto, éxito/fallo de la tarea, tiempo hasta la primera respuesta útil y qué archivos de contexto o herramientas se usaron. Usa estos datos para mejorar llms.txt, las descripciones de herramientas y las respuestas de API.

## No hagas

Asumir que tu AX funciona porque las métricas orientadas a humanos se ven bien. No esperes a un estándar formal antes de recopilar cualquier retroalimentación: instrumenta lo que puedas ahora.

## Artefacto

Carga útil mínima de retroalimentación (atributos compatibles con OpenTelemetry):

```json
{
  "trace_id": "abc123",
  "agent": "claude-code/1.4",
  "session_id": "sess_xyz",
  "task": "deploy_site",
  "outcome": "success",
  "context_sources_used": ["llms.txt", "netlify-mcp"],
  "context_hit_rate": 0.87,
  "time_to_first_tool_call_ms": 1240,
  "tool_calls": 3,
  "tokens_consumed": 4200,
  "feedback": "llms.txt missing blob storage docs — agent fell back to web search"
}
```

Recíbela mediante:
- Endpoint OTLP de OpenTelemetry (`POST /v1/traces`)
- Una ruta de retroalimentación dedicada (`POST /api/ax-feedback`)
- Tu pipeline de analítica existente con eventos etiquetados por agente

## Fuentes

1. [agentexperience.ax — Principles of AX (agent-facing: Provide Feedback)](https://agentexperience.ax/concepts/principles-of-ax/) — Agents send feedback to digital services so digital services can improve the quality of their offering and their AX. Without this information, digital services have no automated feedback mechanism.
2. [Mathias Biilmann — AX in Practice](https://biilmann.blog/articles/ax-in-practice/) — Netlify measures guide quality by the degree to which a code gen agent can single-shot the feature using just the markdown and a prompt — feedback from the agent loop is essential to improving AX

---
Source: Agent Experience Principles (axprinciples.com)