Caso de uso

Decisions API para la siguiente acción del agente

Un bucle de agente es una serie de decisiones finitas: llamar una tool, preguntar al usuario, terminar. Una llamada de decisión elige la siguiente acción y devuelve una probabilidad por opción — sin texto libre que parsear ni esquema de tool que validar.

Actualizado

El bucle del agente como pregunta choice

Cada iteración entrega al modelo el estado actual y hace una pregunta finita: qué debe pasar ahora. La respuesta es una de tus acciones nombradas más una confianza — exactamente el contrato que necesita el ejecutor del bucle.

Como las opciones están declaradas, el modelo nunca puede devolver una acción que tu bucle no implementa. La salida inválida es imposible por construcción, no por disciplina de prompt.

Decisión de siguiente acción

// Agent loop: decisions-1 picks the next action each step.
type Action = "search_docs" | "call_tool" | "ask_user" | "finish";

async function decideNext(state: unknown): Promise<{ action: Action; confidence: number }> {
  const res = await fetch("https://decisions-api.net/api/v1/decisions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.DECISIONS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "decisions-1",
      state, // string, JSON object, or array of text
      questions: {
        next: {
          type: "choice",
          instructions: "What should the agent do next?",
          criteria: {
            search_docs: "Look up documentation before acting.",
            call_tool: "Run the next planned tool call.",
            ask_user: "Stop and ask the user for clarification.",
            finish: "The task is complete; produce the final answer.",
          },
        },
        done: { type: "noul", instructions: "Is the user's task fully complete?" },
      },
    }),
  });
  const { answers } = await res.json();
  return { action: answers.next.choice, confidence: answers.next.confidence };
}

const MAX_STEPS = 8;

async function runAgent(agentState: unknown) {
  for (let step = 0; step < MAX_STEPS; step++) {
    const { action, confidence } = await decideNext(agentState);
    // Illustrative response: { action: "call_tool", confidence: 0.83 }
    if (confidence < 0.8) { await askUser(agentState); continue; }
    switch (action) {
      case "finish": return;
      case "search_docs": await searchDocs(agentState); break;
      case "call_tool": await runTool(agentState); break;
      case "ask_user": await askUser(agentState); break;
    }
  }
  // MAX_STEPS reached: hand off to a human instead of looping forever.
}

Dale al agente una salida honesta

Incluye siempre una acción de escape — ask_user o finish — en los criteria. Un agente sin forma de parar inventará trabajo; una salida honesta convierte 'terminé' o 'estoy atascado' en respuestas de primera clase.

También puedes hacer una pregunta noul independiente en la misma llamada — '¿está la tarea completamente terminada?' — como verificación cruzada del choice.

Limita la autonomía según la confianza

La confianza convierte la respuesta en política: deja que los pasos con alta confianza — digamos 0.8 o más — corran solos, y manda los pasos dudosos a ask_user o a revisión humana. La probabilidad de la segunda opción te dice cuán reñido estuvo el paso.

Registra la distribución, no solo el ganador: un paso que pasó tu umbral 0.51 contra 0.49 merece una segunda mirada.

Cuánto cuesta un paso

Una llamada exitosa cuesta 1 crédito, lleve 1 o 6 preguntas — así que un choice de siguiente acción más un chequeo de finalización sigue costando un crédito por paso del bucle.

FAQ

¿En qué se diferencia del tool calling?

El tool calling elige una función y genera sus argumentos — la forma es abierta. Una llamada de decisión elige una de tus acciones nombradas con probabilidad por opción y sin argumentos libres, así que la salida está restringida por construcción.

¿Qué va en el state?

Todo lo que el modelo necesita para decidir: un resumen compacto del progreso, el último resultado de tool, los pasos restantes y las restricciones. state acepta un string, un objeto JSON o un array de texto.

¿Puede una llamada comprobar más que la siguiente acción?

Sí — una llamada admite hasta 6 preguntas. Combina el choice de siguiente acción con un noul '¿tarea completada?' o un score del riesgo del paso pendiente.

¿Y si la confianza siempre es baja?

Normalmente significa que la lista de acciones es demasiado fina o que el state carece de señal. Fusiona acciones casi duplicadas, enriquece el state y conserva ask_user como el fallback que el modelo puede elegir honestamente.

Impulsa un paso del agente

Una decisión de prueba gratis para visitantes nuevos — pega el estado de tu bucle en el playground y mira la distribución de la siguiente acción.