Goals and State

Los goals definen el éxito; el state registra el progreso. Juntos hacen que el trabajo del agent sea retomable, inspeccionable y más fácil de evaluar.

Fuente y descargas

Repository source

Download code bundle

Intent

El patrón Goals and State separa lo que el agent intenta lograr del state mutable que acumula mientras trabaja. Los goals definen el éxito. El state registra el progreso, restricciones, evidencia, trabajo pendiente, aprobaciones, presupuesto y razones de detención.

Este es el núcleo práctico de la working memory. La working memory no es memoria a largo plazo. Es state operacional con alcance de ejecución. Debe ser compacta, tipada, inspeccionable y desechable, a menos que otra policy promueva explícitamente parte de ella a durable memory.

Usa este pattern para state local de task. La durable memory se maneja con Memory-Augmented Agent. El ensamblaje de context se maneja con Context Engineering.

El model puede proponer un siguiente paso, una actualización de state o una razón de detención. El runtime es dueño de la transición de state. Ese límite evita que el agent reescriba silenciosamente lo que ha sucedido, lo que falta o por qué se le permite continuar.

Usa cuando

Una task abarca múltiples turnos, tools, agents, reintentos, aprobaciones o pasos de workflow.
Necesitas ejecución retomable después de una falla, interrupción, timeout o aprobación humana.
El agent debe explicar el progreso respecto a un objetivo explícito.
Necesitas un conjunto de trabajo compacto en vez de solo el historial de chat.
La evaluación depende de la trayectoria, no solo de la respuesta final.

Evita cuando

La task no tiene state y puede responderse en una sola llamada.
El goal no puede expresarse como criterios de éxito observables.
El state contendría datos sensibles que no puedes almacenar de forma segura.
El sistema usaría el state como un scratchpad no estructurado y sin dueño.
El runtime no puede reproducir ni inspeccionar las transiciones de state.

Arquitectura

Usa este diagrama para leer Goals and State como un límite de sistema, no solo como una forma de código. La pregunta clave de propiedad es: el llamador o un pequeño servicio de aplicación es dueño del state de la task hasta que se introduce un patrón de runtime.

Goals, state, and working memory architecture

Forma del sistema

Límite del pattern: el límite de state es dueño del goal, working state, event log, reglas de transición, razón de detención y replay record.
Dueño del state: el runtime, workflow engine o application service es dueño del state; el model solo es dueño de las actualizaciones propuestas.
Rol del model: el model puede resumir el progreso, identificar brechas y proponer actualizaciones, pero no debe ser la fuente de verdad para el state.
Límite de policy: los cambios de state que afectan permisos, aprobaciones, promoción de memory o efectos secundarios pasan por validaciones del runtime.
Promesa operacional: el sistema puede explicar qué está haciendo, qué cambió, qué evidencia causó el cambio y por qué se detuvo o continuó.

Protocolo central

Crea un goal record con criterios de éxito, restricciones, dueño, clase de riesgo y condiciones de detención.
Inicializa la working memory con el state mínimo necesario para empezar.
Ejecuta un paso acotado mediante un planner, llamada al model, tool, worker, evaluator o puerta de aprobación.
Convierte observaciones en eventos de state tipados.
Aplica transiciones de state de forma idempotente.
Recalcula preguntas abiertas, trabajo pendiente, state de presupuesto, state de aprobación y razón de detención.
Continúa, reintenta, solicita aprobación, escala o detén según reglas explícitas.
Persiste suficiente state e historial de eventos para reproducir o auditar la ejecución.

Notas de implementación

El state debe ser más pequeño que la transcripción y más estructurado que un resumen. Es el modelo operativo para la ejecución actual.

Goal Record

type AgentGoal = {
  goalId: string;
  runId: string;
  owner: string;
  description: string;
  successCriteria: string[];
  constraints: string[];
  riskClass: "low" | "medium" | "high" | "critical";
  status: "active" | "blocked" | "waiting_for_approval" | "completed" | "cancelled" | "failed";
  createdAt: string;
  updatedAt: string;
};

Working Memory State

type WorkingMemoryState = {
  runId: string;
  goalId: string;
  currentStep?: string;
  completedSteps: string[];
  pendingSteps: string[];
  openQuestions: string[];
  constraints: string[];
  evidenceRefs: string[];
  toolResultRefs: string[];
  approvalRefs: string[];
  budgetState: {
    iterationCount: number;
    tokenEstimate: number;
    costCents: number;
    deadlineAt?: string;
  };
  stopReason?: "success" | "blocked" | "approval_required" | "budget_exhausted" | "cancelled" | "failed";
  version: number;
};

State Events

El state debe cambiar a través de eventos, no por mutación oculta.

type StateEvent =
  | { type: "goal_created"; goal: AgentGoal }
  | { type: "step_started"; stepId: string; description: string }
  | { type: "tool_result_recorded"; toolCallId: string; evidenceRef: string }
  | { type: "approval_recorded"; approvalId: string; decision: "approved" | "denied" | "expired" }
  | { type: "question_opened"; question: string }
  | { type: "question_answered"; question: string; evidenceRef: string }
  | { type: "blocked"; reason: string }
  | { type: "completed"; resultRef: string }
  | { type: "cancelled"; reason: string };

function applyStateEvent(state: WorkingMemoryState, event: StateEvent): WorkingMemoryState {
  switch (event.type) {
    case "step_started":
      return { ...state, currentStep: event.stepId, version: state.version + 1 };
    case "tool_result_recorded":
      return {
        ...state,
        evidenceRefs: [...state.evidenceRefs, event.evidenceRef],
        toolResultRefs: [...state.toolResultRefs, event.toolCallId],
        version: state.version + 1,
      };
    case "approval_recorded":
      return {
        ...state,
        approvalRefs: [...state.approvalRefs, event.approvalId],
        stopReason: event.decision === "approved" ? undefined : "blocked",
        version: state.version + 1,
      };
    case "completed":
      return { ...state, stopReason: "success", version: state.version + 1 };
    case "cancelled":
      return { ...state, stopReason: "cancelled", version: state.version + 1 };
    default:
      return { ...state, version: state.version + 1 };
  }
}

Esto es intencionalmente simple. Lo importante es la regla: las transiciones de state son explícitas, tipadas, reproducibles y ligadas a observaciones.

Caso en ejecución: Refund Goal And State

Un asistente de reembolsos necesita más que una transcripción de chat porque los operadores deben saber qué evidencia usó el sistema antes de mover dinero. El goal record debe nombrar el resultado y el riesgo; el working state debe mostrar la evidencia, preguntas abiertas, state de aprobación y razón de detención.

goal:
  description: "Resolve refund eligibility for order O-104."
  success_criteria:
    - "current refund policy is referenced"
    - "order and delivery evidence are attached"
    - "recommendation is validated by policy gate"
    - "high-value refund waits for approval"
  risk_class: "high"
state:
  completed_steps:
    - "order_loaded"
    - "delivery_status_loaded"
  open_questions:
    - "policy exception evidence is missing"
  evidence_refs:
    - "order:O-104"
    - "delivery:D-88"
    - "policy:refunds:v2026-06"
  approval_refs: []
  stop_reason: "approval_required"

Este state le dice al runtime qué sucedió y qué falta. También le da a los evals algo concreto para inspeccionar: la falta de policy debe bloquear la recomendación, una aprobación denegada debe bloquear el pago y una ejecución reanudada debe preservar las mismas referencias de evidencia.

Reglas de promoción

La working memory no debe convertirse automáticamente en durable memory. Un paso completado, resultado de tool o corrección de usuario puede ser candidato para memoria a largo plazo, pero la promoción requiere una decisión de policy aparte.

Antes de promover la working memory, pregunta:

¿Esto es útil más allá de la ejecución actual?
¿La fuente es confiable y está referenciada?
¿El usuario o tenant permite que se almacene?
¿Hay datos sensibles que requieren redacción o expiración?
¿Es esto un evento, un hecho, una preferencia o una referencia de policy?
¿Existe un camino de corrección y eliminación?

Si la respuesta no es clara, mantenlo en el run trace y no lo promociones.

Modos de falla

El state se convierte en un volcado de transcripción.
El model reescribe silenciosamente el state sin un evento.
El goal describe actividad, no éxito.
Los subgoals se alejan del goal principal.
Los resultados de tool se resumen sin referencias de evidencia.
El state de aprobación, cancelación o presupuesto se pierde tras un reintento.
El sistema no puede reanudar porque el state solo vivía en el context del model.
El state obsoleto sobrescribe resultados frescos de tool.
El state sensible se persiste sin reglas de retención o redacción.
La working memory se promueve automáticamente a memoria a largo plazo.

Estrategia de Evaluación

Los evals de working memory deben inspeccionar la trayectoria, no solo la respuesta final.

Prueba que una task de varios pasos crea un goal con criterios de éxito observables.
Prueba que cada resultado de tool se convierte en un evento de state con una referencia de evidence.
Prueba reintentos y verifica transiciones de state idempotentes.
Prueba reanudar después de una interrupción.
Prueba cancelación y verifica que la ejecución no continúe.
Prueba esperas de aprobación y verifica que el approval state sobreviva al reanudar.
Prueba agotamiento de presupuesto y verifica que la razón de detención quede registrada.
Prueba resultados de tool obsoletos y verifica que la evidence más reciente prevalezca.
Prueba ejecuciones bloqueadas y verifica que las preguntas abiertas se conserven.
Prueba que la working memory no se promueva a durable memory sin policy.

Mide la completitud del state, validez de transiciones, éxito de replay, éxito de resume, tasa de state obsoleto, tasa de approval perdido, precisión de stop reason y precisión de promotion-policy.

Lista de Verificación para Producción

Define goal schema, state schema, event schema y stop reasons.
Mantén la working memory compacta y tipada.
Almacena el state separado del historial de chat.
Haz que las actualizaciones de state sean basadas en eventos, idempotentes y reproducibles.
Adjunta referencias de evidence a resultados de tools, decisiones, aprobaciones y respuestas finales.
Persiste approval, cancelación, presupuesto, reintentos y state bloqueado.
Trata la promoción de state a durable memory como una decisión de policy separada.
Redacta o evita datos sensibles en la working memory cuando sea posible.
Traza lecturas, escrituras, transiciones, reintentos, reanudaciones y razones de detención del state.
Convierte incidentes de lost-state y wrong-stop en regression evals.

Recorrido del Código

Lee el extracto como la expresión ejecutable más pequeña del pattern. El capítulo circundante explica las restricciones de diseño; el código muestra dónde esas restricciones se convierten en interfaces concretas, state, validación o control de flujo.

Código Fuente

Este pattern actualmente no tiene un extracto de código dedicado. Usa los enlaces de source y descarga a continuación para acceder a la carpeta completa del pattern.

Descarga

El paquete de descarga contiene la carpeta goals-and-state-pattern/ actual de este repositorio.