Kailash Kaizen - AI Agent Framework
Kaizen is a production-ready AI agent framework built on Kailash Core SDK that provides signature-based programming and multi-agent coordination.
Features
Kaizen enables building sophisticated AI agents with:
- Signature-Based Programming: Type-safe agent interfaces with automatic validation and optimization
- BaseAgent Architecture: Production-ready agent foundation with error handling, audit trails, and cost tracking
- Multi-Agent Coordination: Supervisor-worker, agent-to-agent protocols, hierarchical structures
- Orchestration Patterns: 9 composable patterns (Ensemble, Blackboard, Router, Parallel, Sequential, Supervisor-Worker, Handoff, Consensus, Debate)
- Multimodal Processing: Vision, audio, and text processing capabilities
- Autonomy Infrastructure: 6 integrated subsystems (Hooks, Checkpoint, Interrupt, Memory, Planning, Meta-Controller)
- Distributed Coordination: AgentRegistry for 100+ agent systems with O(1) capability discovery
- Enterprise Features: Cost tracking, streaming responses, automatic optimization
- Memory System: 3-tier hierarchical storage (Hot/Warm/Cold) with DataFlow backend
- Security: RBAC, process isolation, compliance controls (SOC2, GDPR, HIPAA, PCI-DSS)
- Enterprise Agent Trust Protocol (v0.8.0): Cryptographic trust chains, TrustedAgent, secure messaging, credential rotation
- Performance Optimization (v1.0): 7 caches with 10-100x speedup (SchemaCache, EmbeddingCache, PromptCache, etc.)
- Specialist System (v1.0): Claude Code-style specialists and skills with
.kaizen/ directory
- GPT-5 Support (v1.0): Automatic temperature=1.0 enforcement, 8000 max_tokens for reasoning
Quick Start
Basic Agent
from kaizen.core.base_agent import BaseAgent
from kaizen.signatures import Signature, InputField, OutputField
from dataclasses import dataclass
# Define agent signature (type-safe interface)
class SummarizeSignature(Signature):
text: str = InputField(description="Text to summarize")
summary: str = OutputField(description="Generated summary")
# Define configuration
@dataclass
class SummaryConfig:
llm_provider: str = os.environ.get("LLM_PROVIDER", "openai")
model: str = os.environ["LLM_MODEL"]
temperature: float = 0.7
# Create agent with signature
class SummaryAgent(BaseAgent):
def __init__(self, config: SummaryConfig):
super().__init__(
config=config,
signature=SummarizeSignature()
)
# Execute
agent = SummaryAgent(SummaryConfig())
result = agent.run(text="Long text here...")
print(result['summary'])
Pipeline Patterns (Orchestration)
from kaizen_agents.patterns.pipeline import Pipeline
# Ensemble: Multi-perspective collaboration
pipeline = Pipeline.ensemble(
agents=[code_expert, data_expert, writing_expert, research_expert],
synthesizer=synthesis_agent,
discovery_mode="a2a", # A2A semantic matching
top_k=3 # Select top 3 agents
)
# Execute - automatically selects best agents for task
result = pipeline.run(task="Analyze codebase", input="repo_path")
# Router: Intelligent task delegation
router = Pipeline.router(
agents=[code_agent, data_agent, writing_agent],
routing_strategy="semantic" # A2A-based routing
)
# Blackboard: Iterative problem-solving
blackboard = Pipeline.blackboard(
agents=[solver, analyzer, optimizer],
controller=controller,
max_iterations=10,
discovery_mode="a2a"
)
Skill Files
Quick Start
Agent Patterns
Multi-Agent Systems & Orchestration
Pipeline Patterns (9 Composable Patterns):
- Ensemble: Multi-perspective collaboration with A2A discovery + synthesis
- Blackboard: Controller-driven iterative problem-solving
- Router (Meta-Controller): Intelligent task routing via A2A matching
- Parallel: Concurrent execution with aggregation
- Sequential: Linear agent chain
- Supervisor-Worker: Hierarchical coordination
- Handoff: Agent handoff with context transfer
- Consensus: Voting-based decision making
- Debate: Adversarial deliberation
Multimodal Processing
Advanced Features
Observability & Monitoring
Enterprise Agent Trust Protocol (v0.8.0)
- kaizen-trust-eatp - Complete trust infrastructure for AI agents
- Trust lineage chains with cryptographic verification
- TrustedAgent and TrustedSupervisorAgent with built-in trust
- Secure messaging with HMAC authentication and replay protection
- Trust-aware orchestration with policy enforcement
- Enterprise System Agent (ESA) for legacy system integration
- A2A HTTP service for cross-organization trust operations
- Credential rotation, rate limiting, and security audit logging
Agent Manifest & Deploy (v1.3)
- kaizen-agent-manifest - TOML-based agent declaration, governance metadata, and deployment
AgentManifest with [agent] and [governance] TOML sectionsGovernanceManifest with risk_level, suggested_posture, budgetintrospect_agent() for runtime metadata extraction (Python API only, NOT MCP)deploy() / deploy_local() for local FileRegistry or remote CARE PlatformFileRegistry with atomic writes and path traversal prevention
Composition Validation (v1.3)
- kaizen-composition - DAG validation, schema compatibility, cost estimation
validate_dag() with iterative DFS cycle detection (max_agents=1000)check_schema_compatibility() with JSON Schema structural subtyping and type wideningestimate_cost() with historical data projection and confidence levels
MCP Catalog Server (v1.3)
- kaizen-catalog-server - Standalone MCP server for agent catalog operations
CatalogMCPServer with 11 tools: Discovery (4), Deployment (3), Application (2), Governance (2)- Separate from KaizenMCPServer (which handles BaseAgent tools)
- Pre-seeds 14 built-in agents on startup
- Entry point:
python -m kaizen.mcp.catalog_server
Budget Tracking & Posture Integration (v1.3)
- kaizen-budget-tracking - Atomic budget accounting and posture-budget governance
BudgetTracker with two-phase reserve/record, threshold callbacks, on_record() APIPostureBudgetIntegration links budget to posture state machine- Configurable thresholds: warning (80%), downgrade to SUPERVISED (95%), emergency to PSEUDO_AGENT (100%)
L3 Autonomy Primitives
- kaizen-l3-overview - L3 primitives overview (5 subsystems)
- EnvelopeTracker/Splitter/Enforcer for continuous budget tracking
- ScopedContext for hierarchical context with access control
- MessageRouter/Channel for typed inter-agent messaging
- AgentFactory/Registry for runtime agent spawning
- PlanValidator/Executor for DAG task graph execution
- kaizen-l3-envelope - Budget tracking, splitting, and non-bypassable enforcement
EnvelopeTracker with atomic recording, child allocation, reclamationEnvelopeSplitter for stateless ratio-based budget divisionEnvelopeEnforcer middleware with gradient zones (AutoApproved/Flagged/Held/Blocked)
- kaizen-l3-context - Hierarchical scoped context with projection-based access control
ContextScope tree with parent traversal and child mergeScopeProjection glob patterns (allow/deny with deny precedence)DataClassification 5-level clearance filtering
- kaizen-l3-messaging - Typed inter-agent communication
MessageRouter with 8-step validation- 6 typed payloads: Delegation, Status, Clarification, Completion, Escalation, System
DeadLetterStore bounded ring buffer for undeliverable messages
- kaizen-l3-factory - Runtime agent spawning with lifecycle tracking
AgentFactory with 8-check spawn preconditions- 6-state lifecycle machine (Pending/Running/Waiting/Completed/Failed/Terminated)
- Cascade termination (leaves-first)
- kaizen-l3-plan-dag - Dynamic task graph execution
PlanValidator structural + envelope validationPlanExecutor with gradient rules (G1-G8)- 7 typed modifications with batch-atomic application
Testing & Quality
Key Concepts
Signature-Based Programming
Signatures define type-safe interfaces for agents:
- Input: Define expected inputs with descriptions
- Output: Specify output format and structure
- Validation: Automatic type checking and validation
- Optimization: Framework can optimize prompts automatically
BaseAgent Architecture
Foundation for all Kaizen agents:
- Error Handling: Built-in retry logic and error recovery
- Audit Trails: Automatic logging of agent actions
- Cost Tracking: Monitor API usage and costs
- Streaming: Support for streaming responses
- Memory: State management across invocations
- Hooks System: Zero-code-change observability and lifecycle management
Autonomy Infrastructure (6 Subsystems)
1. Hooks System - Event-driven observability framework
- Zero-code-change monitoring via lifecycle events (PRE/POST hooks)
- 6 builtin hooks: Logging, Metrics, Cost, Performance, Audit, Tracing
- Production security: RBAC, Ed25519 signatures, process isolation, rate limiting
- Performance: <0.01ms overhead (625x better than 10ms target)
2. Checkpoint System - Persistent state management
- Save/load/fork agent state for failure recovery
- 4 storage backends: Filesystem, Redis, PostgreSQL, S3
- Automatic compression and incremental checkpoints
- State manager with deduplication and versioning
3. Interrupt Mechanism - Graceful shutdown and execution control
- 3 interrupt sources: USER (Ctrl+C), SYSTEM (timeout/budget), PROGRAMMATIC (API)
- 2 shutdown modes: GRACEFUL (finish cycle + checkpoint) vs IMMEDIATE (stop now)
- Signal propagation across multi-agent hierarchies
4. Memory System - 3-tier hierarchical storage
- Hot tier: In-memory buffer (<1ms retrieval, last 100 messages)
- Warm tier: Database (10-50ms, agent-specific history with JSONL compression)
- Cold tier: Object storage (100ms+, long-term archival with S3/MinIO)
- DataFlow-backed with auto-persist and cross-session continuity
5. Planning Agents - Structured workflow orchestration
- PlanningAgent: Plan before you act (pre-execution validation)
- PEVAgent: Plan, Execute, Verify, Refine (iterative refinement)
- Tree-of-Thoughts: Explore multiple reasoning paths
- Multi-step decomposition, validation, and replanning
6. Meta-Controller Routing - Intelligent task delegation
- A2A-based semantic capability matching (no hardcoded if/else)
- Automatic agent discovery, ranking, and selection
- Fallback strategies and load balancing
- Integrated with Router, Ensemble, and Supervisor-Worker patterns
AgentRegistry - Distributed Coordination
For 100+ agent distributed systems:
- O(1) capability-based discovery with semantic matching
- Event broadcasting (6 event types for cross-runtime coordination)
- Health monitoring with automatic deregistration
- Status management (ACTIVE, UNHEALTHY, DEGRADED, OFFLINE)
- Multi-runtime coordination across processes/machines
When to Use This Skill
Use Kaizen when you need to:
- Build AI agents with type-safe interfaces
- Implement multi-agent systems with orchestration patterns
- Process multimodal inputs (vision, audio, text)
- Create RAG (Retrieval-Augmented Generation) systems
- Implement chain-of-thought reasoning
- Build supervisor-worker or ensemble architectures
- Track costs and performance of AI agents
- Add zero-code-change observability to agents
- Monitor, trace, and audit agent behavior in production
- Secure agent observability with RBAC and compliance controls
- Create production-ready agentic applications
- Enterprise trust and accountability (v0.8.0):
- Cryptographic trust chains for AI agents
- Cross-organization agent coordination
- Regulatory compliance with audit trails
- Secure inter-agent communication
- Agent manifest, deploy, and composition (v1.3):
- Declare agents with TOML manifests and governance metadata
- Deploy agents to local FileRegistry or remote CARE Platform
- Validate composite agent DAGs for cycles
- Check schema compatibility between connected agents
- Estimate pipeline costs from historical data
- Discover/deploy agents via MCP Catalog Server
- Link budget thresholds to automatic posture transitions
- L3 Autonomy Primitives:
- Agent spawning with PACT-governed lifecycle tracking
- Continuous budget tracking with gradient zones and non-bypassable enforcement
- Hierarchical scoped context with projection-based access control
- Typed inter-agent messaging with 8-step routing validation
- Dynamic task graph execution with gradient-driven failure handling
Use Pipeline Patterns When:
- Ensemble: Need diverse perspectives synthesized (code review, research)
- Blackboard: Iterative problem-solving (optimization, debugging)
- Router: Intelligent task delegation to specialists
- Parallel: Bulk processing or voting-based consensus
- Sequential: Linear workflows with dependency chains
Integration Patterns
With DataFlow (Data-Driven Agents)
from kaizen.core.base_agent import BaseAgent
from dataflow import DataFlow
class DataAgent(BaseAgent):
def __init__(self, config, db: DataFlow):
self.db = db
super().__init__(config=config, signature=MySignature())
With Nexus (Multi-Channel Agents)
from kaizen.core.base_agent import BaseAgent
from nexus import Nexus
# Deploy agents via API/CLI/MCP
agent_workflow = create_agent_workflow()
app = Nexus()
app.register("agent", agent_workflow.build())
app.start() # Agents available via all channels
With Core SDK (Custom Workflows)
from kaizen.core.base_agent import BaseAgent
from kailash.workflow.builder import WorkflowBuilder
# Embed agents in workflows
workflow = WorkflowBuilder()
workflow.add_node("KaizenAgent", "agent1", {
"agent": my_agent,
"input": "..."
})
Provider Configuration (v2.5.0 — Explicit over Implicit)
As of v2.5.0, provider configuration follows an explicit over implicit model. Structured output config is separated from provider-specific settings.
BaseAgentConfig Fields
| Field |
Purpose |
Example |
response_format |
Structured output config (json_schema, json_object) |
{"type": "json_schema", "json_schema": {}} |
provider_config |
Provider-specific operational settings only |
{"api_version": "2024-10-21"} |
structured_output_mode |
Controls auto-generation: "auto" (deprecated), "explicit", "off" |
"explicit" |
Quick Pattern
from kaizen.core.config import BaseAgentConfig
from kaizen.core.structured_output import create_structured_output_config
# Explicit mode (recommended)
config = BaseAgentConfig(
llm_provider="openai",
model=os.environ["LLM_MODEL"],
response_format=create_structured_output_config(MySignature(), strict=True),
structured_output_mode="explicit",
)
# Azure with provider-specific settings (separate from response_format)
config = BaseAgentConfig(
llm_provider="azure",
model=os.environ["LLM_MODEL"],
response_format={"type": "json_object"},
provider_config={"api_version": "2024-10-21"},
structured_output_mode="explicit",
)
Azure Env Vars (Canonical Names)
| Canonical |
Legacy (deprecated) |
AZURE_ENDPOINT |
AZURE_OPENAI_ENDPOINT, AZURE_AI_INFERENCE_ENDPOINT |
AZURE_API_KEY |
AZURE_OPENAI_API_KEY, AZURE_AI_INFERENCE_API_KEY |
AZURE_API_VERSION |
AZURE_OPENAI_API_VERSION |
Legacy vars emit DeprecationWarning. Use resolve_azure_env() from kaizen.nodes.ai.azure_detection for canonical-first resolution.
Anti-Patterns
- Never put structured output config in
provider_config — use response_format
- Never rely on auto-generated structured output without understanding it — set
structured_output_mode="explicit"
- Never use multiple env var names for the same Azure setting without deprecation
- Never use error-based backend switching — detect the backend upfront or set
AZURE_BACKEND explicitly
Prompt Utilities
kaizen.core.prompt_utils is the single source of truth for signature-based prompt generation:
generate_prompt_from_signature(signature) — builds system prompt from signature fieldsjson_prompt_suffix(output_fields) — returns JSON format instructions for Azure json_object compatibility
For detailed configuration patterns, see:
Critical Rules
- ✅ Define signatures before implementing agents
- ✅ Extend BaseAgent for production agents
- ✅ Use type hints in signatures for validation
- ✅ Track costs in production environments
- ✅ Test agents with real infrastructure (real infrastructure recommended)
- ✅ Enable hooks for observability
- ✅ Use AgentRegistry for distributed coordination
- ✅ Use
response_format for structured output (not provider_config)
- ✅ Set
structured_output_mode="explicit" for new agents
- ❌ NEVER skip signature definitions
- ❌ NEVER ignore cost tracking in production
- ❌ NEVER put structured output keys in
provider_config
- ❌ Avoid mocking LLM calls in integration tests (real infrastructure recommended)
Kaizen-Agents Governance (v0.1.0)
- kaizen-agents-governance — GovernedSupervisor, progressive disclosure (Layer 1/2/3), 7 governance modules
GovernedSupervisor with 3-layer progressive API (2-param simple → 8-param configured → 9 governance subsystems)AccountabilityTracker — D/T/R addressing, policy source chainBudgetTracker — reclamation, predictive warnings, reallocationCascadeManager — monotonic envelope tightening, BFS terminationClearanceEnforcer + ClassificationAssigner — data classification (C0-C4), regex pre-filterDerelictionDetector — insufficient tightening detectionBypassManager — time-limited emergency overrides with anti-stackingVacancyManager — orphan detection, grandparent auto-designationAuditTrail — EATP hash chain with hmac.compare_digest()- SDK integration:
EnvelopeAllocator → EnvelopeSplitter, ScopeBridge → ScopedContext
L3 Integration & Event System
kaizen-l3-overview -- L3 autonomy primitives, L3Runtime integration, EATP event system
L3Runtime convenience class wiring all 5 subsystems (Factory->Enforcer, Factory->Router, Factory->Context, Enforcer->Plan)L3EventBus pub/sub for 15 governance event types across all primitivesEatpTranslator converts L3 events into EATP audit records with severity classification
kaizen-agents-security — Security patterns for governance
- Anti-self-modification via
_ReadOnlyView proxies
- Pervasive NaN/Inf defense (
math.isfinite() on all numeric paths)
- Bounded collections, monotonic invariants, thread safety
- Delegate tool security (mandatory BashTool gate, ExecPolicy, session sanitization)
Related Skills
Support
For Kaizen-specific questions, invoke:
kaizen-specialist - Kaizen framework implementationtesting-specialist - Agent testing strategies- ``decide-framework
skill - When to use Kaizen vs other frameworks
