Guia del Bucle de Razonamiento¶

Otros idiomas¶

Tabla de contenidos¶

Descripcion General¶

El bucle de razonamiento es el motor de ejecucion principal para agentes autonomos en Symbiont. Impulsa una conversacion de multiples turnos entre un LLM, una puerta de politicas y herramientas externas a traves de un ciclo estructurado:

1. Observar — Recopilar resultados de ejecuciones anteriores de herramientas
2. Razonar — El LLM produce acciones propuestas (llamadas a herramientas o respuestas de texto)
3. Evaluar — El motor de politicas evalua cada accion propuesta
4. Actuar — Las acciones aprobadas se despachan a los ejecutores de herramientas

El bucle continua hasta que el LLM produce una respuesta de texto final, alcanza los limites de iteraciones/tokens, o expira por tiempo.

Principios de Diseno¶

• Seguridad en tiempo de compilacion: Las transiciones de fase invalidas se detectan en tiempo de compilacion mediante el sistema de tipos de Rust
• Complejidad opcional: El bucle funciona solo con un proveedor y una puerta de politicas; el puente de conocimiento, las politicas Cedar y human-in-the-loop son todos opcionales
• Retrocompatible: Agregar nuevas funcionalidades (como el puente de conocimiento) nunca rompe el codigo existente
• Observable: Cada fase emite eventos de diario y tramos de trazado

Inicio Rapido¶

Ejemplo Minimo¶

use std::sync::Arc;
use symbi_runtime::reasoning::circuit_breaker::CircuitBreakerRegistry;
use symbi_runtime::reasoning::context_manager::DefaultContextManager;
use symbi_runtime::reasoning::conversation::{Conversation, ConversationMessage};
use symbi_runtime::reasoning::executor::DefaultActionExecutor;
use symbi_runtime::reasoning::loop_types::{BufferedJournal, LoopConfig};
use symbi_runtime::reasoning::policy_bridge::DefaultPolicyGate;
use symbi_runtime::reasoning::reasoning_loop::ReasoningLoopRunner;
use symbi_runtime::types::AgentId;

// Set up the runner with default components
let runner = ReasoningLoopRunner {
    provider: Arc::new(my_inference_provider),
    policy_gate: Arc::new(DefaultPolicyGate::permissive()),
    executor: Arc::new(DefaultActionExecutor::default()),
    context_manager: Arc::new(DefaultContextManager::default()),
    circuit_breakers: Arc::new(CircuitBreakerRegistry::default()),
    journal: Arc::new(BufferedJournal::new(1000)),
    knowledge_bridge: None,
};

// Build a conversation
let mut conv = Conversation::with_system("You are a helpful assistant.");
conv.push(ConversationMessage::user("What is 6 * 7?"));

// Run the loop
let result = runner.run(AgentId::new(), conv, LoopConfig::default()).await;

println!("Output: {}", result.output);
println!("Iterations: {}", result.iterations);
println!("Tokens used: {}", result.total_usage.total_tokens);

Con Definiciones de Herramientas¶

use symbi_runtime::reasoning::inference::ToolDefinition;

let config = LoopConfig {
    max_iterations: 10,
    tool_definitions: vec![
        ToolDefinition {
            name: "web_search".into(),
            description: "Search the web for information".into(),
            parameters: serde_json::json!({
                "type": "object",
                "properties": {
                    "query": { "type": "string" }
                },
                "required": ["query"]
            }),
        },
    ],
    ..Default::default()
};

let result = runner.run(agent_id, conv, config).await;

Sistema de Fases¶

Patron Typestate¶

El bucle utiliza el sistema de tipos de Rust para imponer transiciones de fase validas en tiempo de compilacion. Cada fase es un marcador de tipo de tamano cero:

pub struct Reasoning;      // LLM produces proposed actions
pub struct PolicyCheck;    // Each action evaluated by the gate
pub struct ToolDispatching; // Approved actions executed
pub struct Observing;      // Results collected for next iteration

La estructura AgentLoop<Phase> lleva el estado del bucle y solo puede llamar metodos apropiados para su fase actual. Por ejemplo, AgentLoop<Reasoning> solo expone produce_output(), que consume self y devuelve AgentLoop<PolicyCheck>.

Esto significa que los siguientes errores son errores de compilacion, no bugs en tiempo de ejecucion: - Saltar la verificacion de politicas - Despachar herramientas sin razonar primero - Observar resultados sin despachar

Flujo de Fases¶

graph TD
    R["AgentLoop<Reasoning>\nproduce_output()"]
    P["AgentLoop<PolicyCheck>\ncheck_policy()"]
    T["AgentLoop<ToolDispatching>\ndispatch_tools()"]
    O["AgentLoop<Observing>\nobserve_results()"]
    LR["LoopResult"]

    R --> P
    P --> T
    T --> O
    O -->|Continue| R
    O -->|Complete| LR

Proveedores de Inferencia¶

El trait InferenceProvider abstrae sobre backends de LLM:

#[async_trait]
pub trait InferenceProvider: Send + Sync {
    async fn complete(
        &self,
        conversation: &Conversation,
        options: &InferenceOptions,
    ) -> Result<InferenceResponse, InferenceError>;

    fn provider_name(&self) -> &str;
    fn default_model(&self) -> &str;
    fn supports_native_tools(&self) -> bool;
    fn supports_structured_output(&self) -> bool;
}

Proveedor en la Nube (OpenRouter)¶

El CloudInferenceProvider se conecta a OpenRouter (o cualquier endpoint compatible con OpenAI):

export OPENROUTER_API_KEY="sk-or-..."
export OPENROUTER_MODEL="google/gemini-2.0-flash-001"  # optional

use symbi_runtime::reasoning::providers::cloud::CloudInferenceProvider;

let provider = CloudInferenceProvider::from_env()
    .expect("OPENROUTER_API_KEY must be set");

Puerta de Politicas¶

Cada accion propuesta pasa por la puerta de politicas antes de su ejecucion:

#[async_trait]
pub trait ReasoningPolicyGate: Send + Sync {
    async fn evaluate_action(
        &self,
        agent_id: &AgentId,
        action: &ProposedAction,
        state: &LoopState,
    ) -> LoopDecision;
}

pub enum LoopDecision {
    Allow,
    Deny { reason: String },
    Modify { modified_action: Box<ProposedAction>, reason: String },
}

Puertas Integradas¶

• DefaultPolicyGate::permissive() — Permite todas las acciones (desarrollo/pruebas)
• DefaultPolicyGate::new() — Reglas de politica predeterminadas
• OpaPolicyGateBridge — Puente al motor de politicas basado en OPA
• CedarGate — Integracion con el lenguaje de politicas Cedar

Retroalimentacion de Denegacion de Politicas¶

Cuando una accion es denegada, el motivo de la denegacion se retroalimenta al LLM como una observacion de retroalimentacion de politicas, permitiendole ajustar su enfoque en la siguiente iteracion.

Ejecucion de Acciones¶

Trait ActionExecutor¶

#[async_trait]
pub trait ActionExecutor: Send + Sync {
    async fn execute_actions(
        &self,
        actions: &[ProposedAction],
        config: &LoopConfig,
        circuit_breakers: &CircuitBreakerRegistry,
    ) -> Vec<Observation>;
}

Ejecutores Integrados¶

Circuit Breakers¶

Cada herramienta tiene un circuit breaker asociado que rastrea fallos:

• Cerrado (normal): Las llamadas a herramientas proceden normalmente
• Abierto (disparado): Demasiados fallos consecutivos; las llamadas se rechazan inmediatamente
• Semi-abierto (sondeo): Se permiten llamadas limitadas para probar la recuperacion

let circuit_breakers = CircuitBreakerRegistry::new(CircuitBreakerConfig {
    failure_threshold: 3,
    recovery_timeout: Duration::from_secs(60),
    half_open_max_calls: 1,
});

Puente Conocimiento-Razonamiento¶

El KnowledgeBridge conecta el almacen de conocimiento del agente (memoria jerarquica, base de conocimiento, busqueda vectorial) con el bucle de razonamiento.

Configuracion¶

use symbi_runtime::reasoning::knowledge_bridge::{KnowledgeBridge, KnowledgeConfig};

let bridge = Arc::new(KnowledgeBridge::new(
    context_manager.clone(),  // Arc<dyn context::ContextManager>
    KnowledgeConfig {
        max_context_items: 5,
        relevance_threshold: 0.3,
        auto_persist: true,
    },
));

let runner = ReasoningLoopRunner {
    // ... other fields ...
    knowledge_bridge: Some(bridge),
};

Como Funciona¶

Antes de cada paso de razonamiento: 1. Se extraen terminos de busqueda de mensajes recientes de usuario/herramientas 2. query_context() y search_knowledge() recuperan elementos relevantes 3. Los resultados se formatean e inyectan como un mensaje de sistema (reemplazando la inyeccion anterior)

Durante el despacho de herramientas: El KnowledgeAwareExecutor intercepta dos herramientas especiales:

• recall_knowledge — Busca en la base de conocimiento y devuelve resultados formateados

  { "query": "capital of France", "limit": 5 }
  

• store_knowledge — Almacena un nuevo hecho como una tripleta sujeto-predicado-objeto

  { "subject": "Earth", "predicate": "has", "object": "one moon", "confidence": 0.95 }
  

Todas las demas llamadas a herramientas se delegan al ejecutor interno sin cambios.

Despues de completar el bucle: Si auto_persist esta habilitado, el puente extrae las respuestas del asistente y las almacena como memoria de trabajo para futuras conversaciones.

Retrocompatibilidad¶

Establecer knowledge_bridge: None hace que el runner se comporte de forma identica a antes — sin inyeccion de contexto, sin herramientas de conocimiento, sin persistencia.

Gestion de Conversaciones¶

Tipo Conversation¶

Conversation gestiona una secuencia ordenada de mensajes con serializacion a los formatos de API de OpenAI y Anthropic:

let mut conv = Conversation::with_system("You are a helpful assistant.");
conv.push(ConversationMessage::user("Hello"));
conv.push(ConversationMessage::assistant("Hi there!"));

// Serialize for API calls
let openai_msgs = conv.to_openai_messages();
let (system, anthropic_msgs) = conv.to_anthropic_messages();

Control de Presupuesto de Tokens¶

El ContextManager dentro del bucle (no confundir con el ContextManager de conocimiento) gestiona el presupuesto de tokens de la conversacion:

• Ventana Deslizante: Eliminar los mensajes mas antiguos primero
• Enmascaramiento de Observaciones: Ocultar resultados verbosos de herramientas
• Resumen Anclado: Mantener el mensaje de sistema + N mensajes recientes

Diario Durable¶

Cada transicion de fase emite una JournalEntry al JournalWriter configurado:

pub struct JournalEntry {
    pub sequence: u64,
    pub timestamp: DateTime<Utc>,
    pub agent_id: AgentId,
    pub iteration: u32,
    pub event: LoopEvent,
}

pub enum LoopEvent {
    Started { agent_id, config },
    ReasoningComplete { iteration, actions, usage },
    PolicyEvaluated { iteration, action_count, denied_count },
    ToolsDispatched { iteration, tool_count, duration },
    ObservationsCollected { iteration, observation_count },
    Terminated { reason, iterations, total_usage, duration },
    RecoveryTriggered { iteration, tool_name, strategy, error },
}

El BufferedJournal predeterminado almacena entradas en memoria. Los despliegues en produccion pueden implementar JournalWriter para almacenamiento persistente.

Configuracion¶

LoopConfig¶

pub struct LoopConfig {
    pub max_iterations: u32,        // Default: 25
    pub max_total_tokens: u32,      // Default: 100,000
    pub timeout: Duration,          // Default: 5 minutes
    pub default_recovery: RecoveryStrategy,
    pub tool_timeout: Duration,     // Default: 30 seconds
    pub max_concurrent_tools: usize, // Default: 5
    pub context_token_budget: usize, // Default: 32,000
    pub tool_definitions: Vec<ToolDefinition>,
}

Estrategias de Recuperacion¶

Cuando la ejecucion de una herramienta falla, el bucle puede aplicar diferentes estrategias de recuperacion:

Pruebas¶

Pruebas Unitarias (Sin Clave de API Requerida)¶

cargo test -j2 -p symbi-runtime --lib -- reasoning::knowledge

Pruebas de Integracion con Proveedor Mock¶

cargo test -j2 -p symbi-runtime --test knowledge_reasoning_tests

Pruebas en Vivo con LLM Real¶

OPENROUTER_API_KEY="sk-or-..." OPENROUTER_MODEL="google/gemini-2.0-flash-001" \
  cargo test -j2 -p symbi-runtime --features http-input --test reasoning_live_tests -- --nocapture

Fases de Implementacion¶

El bucle de razonamiento se construyo en cinco fases, cada una agregando capacidades:

Primitivas Avanzadas (orga-adaptive)¶

El feature gate orga-adaptive agrega cuatro capacidades avanzadas. Consulte la guia completa para mas detalles.

let config = LoopConfig {
    tool_profile: Some(ToolProfile::include_only(&["search_*", "file_*"])),
    pre_hydration: Some(PreHydrationConfig::default()),
    ..Default::default()
};

Proximos Pasos¶

• Arquitectura del Runtime — Vision general completa de la arquitectura del sistema
• Modelo de Seguridad — Aplicacion de politicas y pistas de auditoria
• Guia DSL — Lenguaje de definicion de agentes
• Referencia de API — Documentacion completa de la API