¶Conceptos centrales

Ciel organiza la ejecución de agentes en torno a unas pocas piezas. Este diagrama muestra el flujo básico:

            ┌─────────────┐
 usuario --> │   Prompt   │
            └──────┬──────┘
                   │
            ┌──────▼──────┐
            │   Runtime   │  DefaultAgentRuntime
            │ (agent loop)│
            └──────┬──────┘
        ┌──────────┼───────────┐
        │          │           │
  ┌─────▼────┐ ┌──▼─────┐ ┌───▼──────┐
  │ Provider │ │ Tools  │ │  Graph/  │
  │ (LLM)    │ │(toolset)│ │  Flow    │
  └──────────┘ └────────┘ └──────────┘
        │          │
        └──────┬───┘
               │
         ┌─────▼─────┐
         │  Gateway  │  FastAPI + adapters (Teams/Discord/WebUI)
         └───────────┘

¶Capa de alto nivel (recomendada)

Para el caso común usas cuatro piezas de la API pública (import ciel):

ciel.Agent — entrada de alto nivel. Encapsula provider + registro de tools + dispatcher + runtime. Métodos run() (sync) y arun() (async).
@ciel.tool — convierte una función Python en tool, infiriendo el esquema desde type hints + docstring. Ver Tools.
ciel.Context — objeto de inyección de dependencias (tenant/session/user) disponible dentro de las tools que lo declaren.
ciel.AgentResponse — resultado ergonómico: .text, .tool_results, .tool_calls, .messages, .raw.

import ciel

@ciel.tool
def add(a: int, b: int) -> int:
    "Suma dos enteros."
    return a + b

agent = ciel.Agent(provider=mi_provider, tools=[add])
resp = agent.run("Suma 2 + 3", tenant_id="acme")
print(resp.text)

Por debajo, esta capa se apoya en las primitivas siguientes, que puedes usar directamente cuando necesites control fino.

¶Runtime

DefaultAgentRuntime (en ciel.runtime) orquesta el ciclo: envía el ChatRequest al provider, si el provider devuelve tool_calls los ejecuta vía el dispatcher y vuelve a llamar al provider con los resultados, hasta finish_reason == "stop". Es durable cuando se combina con CheckpointedAgentRuntime.

¶Tool / Toolset

ToolSpec: nombre, descripción, esquema de parámetros (JSON-schema-like).
Tool: ToolSpec + callable_.
ToolRegistry / ToolsetSchema: agrupan tools en toolsets (conjuntos activables por tenant o por agente).
DefaultToolDispatcher: ejecuta tool_calls del provider contra el registry.

¶Provider

Interfaz ChatProvider (ABC) con complete, stream, models. Ciel trae OpenAICompatibleProvider, AnthropicProvider y GeminiProvider como builtins. Puedes crear el tuyo subclassando ChatProvider. Ver Providers.

¶Tenant (multitenancy)

Casi todas las operaciones aceptan tenant_id. Aísla memoria, checkpoints, auditoría, cuotas de costo y rate-limit por inquilino. Es nativo, no un añadido: pasas tenant_id= en el runtime y en los tools.

¶Session / Memory / Checkpoint

Session: conversación aislada (estado en runtime/orchestration).
EpisodicStore: memoria episódica nativa por (tenant_id, session_id) (SQLite), inyectada en el agente vía Agent(memory=...). Aislada por tenant, offline-safe.
CheckpointStore + CheckpointedAgentRuntime: punto de reanudación durable.

¶Auto-aprendizaje (Autonomía II, v0.13)

Tres primitivas aditivas y offline-safe (sin red ni API keys) que convierten al agente en capaz de aprender de sus fallos y volverse explicable:

Self-reflection + learning-from-failure (ciel.runtime.reflection_agent_integration): Agent(reflection=True) genera tras cada run una lección determinista cuando un tool falla (resumen estructurado de qué tool falló y por qué), y la persiste como memoria episódica role="lesson" (multitenant, reutiliza F17). El resumen está disponible en AgentResponse.reflection.
Prompt evolution versionado (ciel.runtime.prompt_versioning): PromptRegistry / PromptVersion versionan las instructions con semver + sha256 + linaje, persistido en SQLite/Postgres vía StateBackend (aislado por tenant_id). registry.update(name, text, bump="minor") crea una nueva versión trazable.
Introspección / estado cognitivo (ciel.runtime.cognitive_state): Agent(introspection=True) registra un CognitiveSnapshot post-run (versión de prompt activa, turnos de memoria, tool calls, fallo, confianza heurística) en cognitive_state_log e inyecta un bloque [Estado cognitivo] en el system prompt. agent.introspect() vuelca los últimos snapshots.

Todas se enganchan sin reescribir ciel.api: patron install_*_support (igual que memoria/skills). La CLI ciel reflect las opera desde línea de comandos.

¶Autonomía III (Fase 20, v0.14)

Cuatro piezas aditivas y offline-safe (sin red ni API keys):

Curriculum / autonomous goal setting (ciel.runtime.curriculum): decompose_goal(goal) descompone un objetivo en sub-tareas con una heurística determinista offline; con provider= (p. ej. MockProvider) le pide el plan al modelo y hace fallback a la heurística si la respuesta no sirve. CurriculumRegistry(backend).create(goal, plan, tenant_id=...) persiste el plan versionado (semver + sha256 + linaje) en el StateBackend; get, history y evolution_tree lo consultan. install_curriculum_support(Agent) añade Agent(curriculum=...) y Agent.run_curriculum(goal), que descompone, persiste y ejecuta las sub-tareas con el loop de orquestación. La CLI ciel curriculum run|history|show lo opera desde terminal.
Knowledge graph (ciel.runtime.knowledge_graph): KnowledgeGraph guarda nodos (KGNode) y aristas dirigidas (KGEdge) en SQLite (kg_nodes / kg_edges) con aislamiento por tenant_id. add_node / add_edge / neighbors para el grafo explícito y search(query) para búsqueda semántica sin red (embeddings deterministas + índice vectorial en memoria). Export opcional a networkx (to_networkx).
Transfer learning entre dominios (ciel.runtime.skill_recommender): SkillRecommender(library) indexa el contenido de la SkillLibrary con embeddings offline; recommend(context, tenant_id=..., top_k=3) devuelve skills relevantes al contexto, y con context_domain= filtra al modo cross-domain: solo skills de otros dominios.
Sandbox seguro (cierre del Hueco A): SandboxExecutor deja de degradar en silencio a inprocess cuando una capacidad peligrosa (shell, exec, file_write, ... — ver DANGEROUS_CAPABILITIES) no dispone del backend fuerte (light/docker/gvisor): lanza CielSecurityError salvo que se pase explícitamente allow_insecure_inprocess=True (también disponible en SandboxPolicy.allow_insecure_inprocess). El backend real usado y los límites aplicados quedan trazados en ToolResult.metadata["sandbox_backend"] y ["limits_applied"].

Todo se re-exporta en el paquete raíz: ciel.Curriculum, ciel.CurriculumRegistry, ciel.decompose_goal, ciel.install_curriculum_support, ciel.KnowledgeGraph, ciel.SkillRecommender.

¶Graph / Flow

ciel.orchestration.graph define grafos de nodos con estado. Un nodo puede marcarse require_approval=True para Human-in-the-Loop: el runner pausa y persiste paused=True hasta que un rol autorizado (RBAC approve:*) aprueba o rechaza. flows, chat, swarm, supervisor son orquestadores de multi-agente sobre estas primitivas.

¶Gateway

ciel.gateway expone el framework vía FastAPI (ciel serve), con routers para adapters de canal (Teams, Discord, WebUI) y auth por CIEL_API_KEY. Ver Deploy.