K9-AIF — K9 Agentic Integration Framework

K9-AIF is an architecture-first framework for designing governed, enterprise-scale multi-agent AI systems.

Unlike agent runtimes that focus mainly on execution, K9-AIF defines the architectural structure, interaction boundaries, governance model, and runtime execution control needed to build scalable agentic AI systems.

The framework separates Architecture Building Blocks (ABB) from Solution Building Blocks (SBB), enabling extensible and composable agentic applications.

K9-AIF layered architecture — click the image to view full resolution.

K9-AIF provides architectural patterns for constructing agentic workflows where multiple AI agents collaborate to perform reasoning, analysis, and decision-support tasks while maintaining clear governance, orchestration, and integration boundaries.

The framework draws inspiration from established architectural disciplines, including:

• Object-Oriented Analysis & Design (OOA/OOD)
• Enterprise Architecture (TOGAF)
• Service-Oriented Architecture (SOA)
• Modern multi-agent AI systems

The goal is to enable composable, scalable, and governed agentic AI applications.

---

Table of Contents

• A Simple Way to Think About It
• Understanding K9-AIF
• Core Architectural Concepts
  • Architecture Building Blocks (ABB)
  • Solution Building Blocks (SBB)
  • Architectural Layers
  • Agent Squads
  • Zero Trust Execution Layer
  • Human-in-the-Loop (HIL)
• Prototype Implementations
• Design Goals
• Architectural Patterns
• Intelligent Model Routing
• Multi-Provider LLM Support
• Using Claude Code with K9-AIF
• Scaffold Generation
• K9-AIF Developer Journey
• Framework Implementation
• Developer Guide
• Quick Start
• Project Status
• License
• Contributions
• Architectural Foundations
• Architecture Notes & Blog
• Author's Recommendation
• Author

---

A Simple Way to Think About It

• Frameworks like CrewAI define how agents collaborate.
• Cloud platforms like Azure or AWS provide infrastructure.
• Runtimes execute workflows.
• K9-AIF defines how the full AI system should be architected.

---

Understanding K9-AIF

Start here for a structured explanation of K9-AIF:

• The Path of K9-AIF
• What K9-AIF Is
• K9-AIF for Stakeholders
• K9-AIF vs Agent Frameworks
• Where Agent Systems Fail
• FAQ

---

Core Architectural Concepts

K9-AIF separates architecture into abstract ABB contracts and concrete SBB implementations.

Architecture Building Blocks (ABB)

Architecture Building Blocks define abstract architectural capabilities and contracts within the K9-AIF framework. ABBs specify responsibilities, interfaces, and interaction patterns without prescribing concrete implementations or technologies.

An ABB typically defines:

• Interfaces and interaction contracts
• Responsibilities and functional boundaries
• Lifecycle expectations
• Governance and observability hooks

Examples include:

• Agent interface contracts
• Orchestrator contracts
• Tool connector interfaces
• Inference adapters
• Storage or persistence adapters

---

Solution Building Blocks (SBB)

Solution Building Blocks provide concrete implementations of ABB contracts. SBBs introduce domain-specific behavior, technology choices, and runtime integrations while conforming to the architectural constraints defined by the ABB layer.

This separation allows architectural stability while enabling domain-specific extensions without modifying the core framework.

Examples:

• Document Analysis Agent
• Retrieval Agent
• CrewAI Agent
• LangChain Tool Adapter
• OpenAI LLM Connector

---

Architectural Layers

A typical K9-AIF system is organized into a set of architectural layers that separate interface concerns, orchestration, external integration, inference, and persistence.

1. Presentation Layer Handles incoming user or system interactions through web interfaces, conversational channels, or APIs.
2. Application Layer Coordinates orchestration flows, routing, and workflow execution across agents and services.
3. Integration Layer Provides governed access to external systems, APIs, tools, messaging platforms, and storage services.
4. Inference Layer Supports model invocation, retrieval-augmented generation (RAG), and context-aware reasoning.
5. Data Layer Provides persistence, object storage, and messaging infrastructure used by the framework.
6. Cross-Cutting Concerns Security, governance, and observability apply across all layers to enforce policy, auditability, monitoring, and operational control. This includes the Zero Trust Execution Layer, which verifies, risk-evaluates, and enforces policy on all actions before execution across routers, orchestrators, agents, and integrations.

---

Agent Squads

K9-AIF introduces the concept of Agent Squads.

A Squad represents a coordinated group of agents working together to perform a specific capability within an orchestration workflow.

Rather than orchestrators invoking individual agents directly, K9-AIF introduces a structured collaboration layer between orchestrators and agents.

Execution hierarchy:

Event → K9EventRouter (single entry point)
    ├── event_type known  ──────────────────► domain topic
    └── event_type unknown ──► intent.in
                                    │
                        IntentOrchestrator
                            → IntentSquad → K9IntentAgent
                                ├── intent resolved ──► domain topic
                                └── intent unclear  ──► responses.out

domain topic → Orchestrator → Squads → Agents → LLM

Squads allow enterprise workflows to be modeled as capability-based teams of agents. All squad-level execution remains subject to K9-AIF’s governance and Zero Trust execution controls, ensuring that agent actions are verified and policy-enforced at runtime.

Examples include:

• Claims Processing Squad
• Medical Review Squad
• Architecture Analysis Squad
• Threat Assessment Squad

Squads are defined declaratively using configuration and loaded dynamically at runtime using the SquadLoader component.

Core squad framework components include:

• BaseSquad
• SquadLoader
• SquadContext
• DefaultSquadMonitor

---

Zero Trust Execution Layer

Once you understand the execution hierarchy (Router → Orchestrator → Squads → Agents), Zero Trust is the cross-cutting layer that governs every step of it.

Traditional Zero Trust focuses on access — who can reach a system.K9-AIF applies Zero Trust to execution — every action is verified before it runs.

• Every action is verified before execution
• Contextual risk is evaluated (identity, data sensitivity, destination)
• Policies are enforced at runtime (allow, conditional, deny)

This is not a checkpoint at the edge — it is enforced at every layer:

• Router — pre-routing enforcement
• Orchestrator — pre-execution enforcement before the Squad runs

Zero Trust is not a checkpoint — it is a layer applied across the system.

---

Human-in-the-Loop (HIL)

An Agent or Squad can trigger a human decision mid-flow — a fraud score below an auto-approve threshold, a low-confidence classification, a policy that always requires sign-off — by raising RequiresHIL, a first-class exception rather than a return-value flag your Squad author has to remember to check.

Two rules govern how this crosses the framework's existing layers, both deliberate, documented carve-outs rather than accidents:

• Agents and Squads never touch Kafka, even for HIL. RequiresHIL propagates by exception through the normal Agent → Squad → Orchestrator call chain; only the catching Orchestrator actually publishes. Publishing below the layer that controls whether execution continues can't stop the rest of the flow from completing normally — exactly the inconsistency this design avoids.
• The Orchestrator delegates to a real, separate BaseHILOrchestrator — a second, conscious exception to "Orchestrators don't call other Orchestrators" — so every part of the framework that can trigger HIL shares one place that knows how to publish, persist, and resume, instead of each SBB orchestrator hand-rolling it.

The Orchestrator never blocks waiting for a decision — a human review can take hours or days. It returns {"status": "pending_hil", ...} immediately; K9EventRouter picks the decision back up later by subscribing across every hil.replies.* topic (one consumer, pattern- subscribed — never one Kafka topic per job) and resolving by correlation_id against a persisted hil_pending row, then re-routing the resumed payload through its own route() — resuming a workflow is just re-routing it with new information now available, not a second mechanism.

---

Prototype Implementations

Prototype systems based on K9-AIF demonstrate how the framework can support governed multi-agent architectures across multiple domains.

Featured Example

K9X Enterprise Insurance Operations Center (EOC) → examples/K9X_Enterprise_Insurance_OperationsCenter

The EOC is the canonical reference implementation of K9-AIF — the most complete, production-aligned example in the framework. It demonstrates every architectural concept end-to-end:

• Full Kafka-based event pipeline (Router → domain topics → Orchestrator → eoc-results)
• Seven domain orchestrators, each owning a Squad and its agents
• Agent pipeline with sequential flow, conditional steps (when:), and accumulated context
• Zero Trust enforcement at the Orchestrator layer
• Governance pre/post processing across all agents
• Neo4j graph sync, PostgreSQL persistence, Docling OCR via MCP
• FastAPI backend + Web UI with real-time SSE event streaming
• Containerised deployment (Podman pod, three containers)

Use the EOC as your reference when building any new K9-AIF solution.

Additional Examples

• ACME Health Insurance Claims Assistant — Multi-agent insurance workflow demo including eligibility checks, provider lookup, and claims support. → examples/acme_health_insurance
• K9Chat — Reference chat application demonstrating BaseAgent, llm_invoke, multi-provider model routing, governance, and retrieval grounding. A single-agent app, not a multi-agent Squad/Orchestrator example — see the EOC example above for that. → github.com/k9aif/examples (moved out of this repo 2026-09-21)
• WeatherAssist Decision Support System
• Department of War (DoW) Systems Engineering Pipeline — Demonstrates how K9-AIF architectural patterns can automate multi-stage systems engineering workflows aligned with the DoDAF 2.0 architecture framework, exploring agent orchestration across multiple architectural stages using K9-AIF patterns together with the CrewAI orchestration framework.

---

Design Goals

K9-AIF is designed to support the development of governed, modular agentic AI systems aligned with enterprise architecture practices.

Key architectural goals include:

• Modular architecture supporting independently deployable AI capabilities
• Reusable architectural building blocks for consistent system composition
• Governed AI workflows with policy, control, and observability integration
• Clear orchestration boundaries between agents, tools, squads, and services
• Scalable integration with enterprise systems and external platforms
• Architecture-driven routing of inference requests across multiple models and providers
• Runtime execution control using a Zero Trust model, ensuring that all agentic actions are verified, risk-evaluated, and policy-enforced before execution

The framework bridges traditional enterprise architecture principles with emerging agentic AI system design.

---

Architectural Patterns

Many of the architectural ideas used within the K9-AIF framework are documented separately as reusable architecture patterns.

These patterns describe the core design principles behind the framework while remaining independent of any specific runtime implementation.

The pattern catalog includes topics such as:

• Factory-based governed component instantiation
• Inference layer abstraction for model providers
• Connector-based integration with external systems
• Configuration-driven runtime loading of agents and orchestration components

The full set of patterns is available in the K9-AIF Architecture Patterns repository:

➡️ https://github.com/k9aif/k9aif-patterns

Validation Loop Pattern

An in-framework pattern for iterative hypothesis-validate-reason workflows — applicable across security, fraud, claims, compliance, and document extraction domains.

Implemented as BaseValidationLoopAgent in k9_aif_abb/k9_agents/validation/. K9ValidationLoopAgent is the OOB LLM-driven implementation for confidence-convergence loops. K9PlanningLoopAgent (k9_aif_abb/k9_agents/planning/) is the dynamic-planning sibling — the agent builds and revises its own step plan each iteration, finalizing when the plan is complete. See Skill 10 in SKILLS.md for usage and the SA decision guide.

Prompt Evaluation Pattern

A development-time pipeline for grading authored prompts — system prompts, agent instructions, and guided-flow templates — before they reach a workflow.

BasePromptEvaluator defines the ABB contract: evaluate(), compare(), and run_suite(). K9PromptEvaluator is the OOB SBB — LLM-as-judge, five weighted dimensions (correctness 35%, completeness 25%, format compliance 15%, clarity 15%, relevance 10%), grade scale A–F, configurable PASS threshold. EvaluationFactory.create(config) provisions the right implementation.

This is a design-time and measurement-time tool, not a runtime gate. Runtime quality enforcement is K9ValidationLoopAgent's responsibility. The K9Chat reference application ships with an evaluation toggle that grades every response in real time during development.

Implemented in k9_aif_abb/k9_agents/evaluation/. Config key: evaluation.provider: k9.

---

Intelligent Model Routing

K9-AIF includes an Intelligent Model Router that enables applications to dynamically select the most appropriate AI model at runtime.

Rather than binding agents to specific model providers, the router evaluates inference requests based on task type, metadata, and routing policies to determine the best model and provider.

This enables:

• provider-agnostic application logic
• centralized governance over inference usage
• cost and latency optimization
• future compatibility with new AI models

For detailed implementation documentation see:

See the full documentation for the inference layer in k9_aif_abb/k9_inference

---

Multi-Provider LLM Support

K9-AIF uses a Provider Adapter pattern to support multiple LLM backends without coupling any framework component to a specific provider.

LLMFactory remains provider-agnostic — it resolves the correct adapter from ProviderAdapterRegistry and asks it to construct the BaseLLM. Agents, squads, orchestrators, and the model router require no changes when switching providers.

Click to view full resolution.

Supported out of the box

Provider	backend config value	API key env var
Ollama (local)	ollama	—
OpenAI	openai	OPENAI_API_KEY
Anthropic Claude	claude	ANTHROPIC_API_KEY
Grok / xAI	openai-compatible	GROK_API_KEY
Any OpenAI-compatible endpoint	openai-compatible	your choice

Switching provider — config only, no code changes

Ollama (default):

inference:
  llm_factory:
    backend: ollama
    base_url: "http://localhost:11434"
    models:
      general:
        model: "llama3.2:1b"

OpenAI:

inference:
  llm_factory:
    backend: openai
    api_key_env: OPENAI_API_KEY    # resolved from environment — never hardcode
    models:
      general:
        model: "gpt-4o-mini"

Grok / xAI:

inference:
  llm_factory:
    backend: openai-compatible
    base_url: "https://api.x.ai/v1"
    api_key_env: GROK_API_KEY
    models:
      general:
        model: "grok-3-mini"

Adding a new provider — no framework changes required

Extend BaseProviderAdapter, implement two methods, register once:

from k9_aif_abb.k9_core.inference.base_provider_adapter import BaseProviderAdapter
from k9_aif_abb.k9_core.inference.provider_registry import ProviderAdapterRegistry

class WatsonxProviderAdapter(BaseProviderAdapter):

    @property
    def provider_name(self) -> str:
        return "watsonx"

    def create_llm(self, model_name, factory_cfg, extra_kwargs):
        return WatsonxLLM(api_key=..., model=model_name, **extra_kwargs)

ProviderAdapterRegistry.register("watsonx", WatsonxProviderAdapter)

Then set backend: watsonx in config.yaml. Nothing else changes.

API keys are always resolved from environment variables (api_key_env: MY_KEY) — never stored in config files.

---

Example Use Cases

K9-AIF can be applied to enterprise AI systems that require governed orchestration of multiple AI capabilities.

Examples include:

• Enterprise architecture and technology landscape analysis
• Document intelligence and large-scale document processing
• Insurance claims analysis and decision support
• Automated systems engineering workflows
• Knowledge synthesis and research assistance

---

Scaffold Generation

K9X Studio — Visual Builder

K9X Studio is a browser-based drag-and-drop architecture builder for K9-AIF systems.

Design your architecture visually → generate a production-ready scaffold → implement in VS Code + Claude Code.

• Drag Router → Orchestrator → Squad → Agents onto the canvas
• Configure each node in the inspector
• Click Generate Scaffold — a ready-to-run project lands in k9_projects/<your-project>/
• Supports Ollama, OpenAI, and Grok backends out of the box

➡️ https://studio.k9x.ai — source: k9aif/k9x-ecosystem

K9X Ecosystem

Products built on top of K9-AIF, beyond the framework itself:

Product	Purpose	URL
Designer Studio	Visual K9-AIF architecture builder (see above)	studio.k9x.ai
Enterprise Continuum	Governed SBB/ABB catalog — publish, promote, harvest workflow	continuum.k9x.ai
Enterprise Repository	TOGAF Architecture Repository — governed artifact/standards catalog	repo.k9x.ai
HIL (Human in the Loop)	Kafka-native case management for agent escalations	hil.k9x.ai
Security Analysis Tool (SATAN)	Adversarial red-team harness proving k9x_Shield containment	satan.k9x.ai

In the pipeline: dashboard.k9x.ai (read-only ecosystem catalog + launch point), inspector.k9x.ai (architectural conformance scanner for any K9-AIF solution).

Source for all of the above: k9aif/k9x-ecosystem

---

K9-AIF Developer Journey

The diagram illustrates how applications are built using K9-AIF:

• Architects design the system visually in K9X Studio or define ABBs directly in code. • Application developers extend ABBs into Solution Building Blocks (SBB) and implement agent logic in VS Code + Claude Code. • Business analysts configure workflows and governance policies using YAML without modifying code.

Scaffolding a new solution goes through K9X Studio: drag-and-drop canvas → Generate Scaffold — runnable out of the box with Ollama.

---

Framework Implementation

The core implementation of the K9-AIF architecture is provided in the k9_aif_abb package, where ABB refers to Architecture Building Blocks.

This package contains the Architecture Building Blocks (ABB) and supporting framework components used to construct K9-AIF applications.

Location: k9_aif_abb

---

Developer Guide

A comprehensive developer guide for contributors and solution developers building on K9-AIF is available in the docs/developers/ folder.

Format	Location
Markdown	docs/developers/Developer-guide.md
PDF	docs/developers/Developer-guide.pdf

The guide covers all 21 chapters — from core architecture and ABB/SBB development model through agent, orchestrator, and router development; the Validation Loop and Critic-Actor iterative reasoning patterns; model routing, governance, testing standards, and developer workflow. It includes accurate class signatures, config examples, and code drawn directly from the k9_aif_abb source.

---

Using Claude Code with K9-AIF

K9-AIF is designed to work with Claude Code — Anthropic's AI coding assistant. The repository includes context files that give Claude Code an immediate, accurate understanding of the framework so you can build new applications without re-explaining the architecture every session.

Context files included

File	How it helps Claude Code
CLAUDE.md	Loaded automatically on repo open. Gives Claude Code the full framework picture — execution hierarchy, ABB/SBB contracts, inference pipeline, governance rules, config structure, and infrastructure endpoints — so it never has to re-derive them by reading source files
SKILLS.md	Tells Claude Code exactly how to build things: the precise pattern for adding an agent, the fullllm_invoke → ModelRouterFactory → K9ModelRouter → LLMFactory → OllamaLLM chain, how to wire squads, enforce governance, and write tests — so generated code follows framework conventions correctly every time
AGENTS.md	When extending the EOC, Claude Code knows every agent's model assignment, squad membership, governance coverage, and event contract without reading 8 YAML files — enabling accurate, consistent additions to the existing pipeline

Generating a new example with Claude Code

Open the repository in VS Code with Claude Code and run this prompt:

You are building a new application example on top of the K9-AIF framework located at k9_aif_abb/.

Project details:
- Application name: [e.g., K9X_Healthcare_ClaimsProcessor]
- Create all files under: examples/K9X_Healthcare_ClaimsProcessor/
- Spec doc location: examples/K9X_Healthcare_ClaimsProcessor/docs/your-spec.docx

Before writing any code, read CLAUDE.md and SKILLS.md, then read the canonical reference example:
  examples/K9X_Enterprise_Insurance_OperationsCenter/

Then implement the new example following the same structure and conventions. Rules:
- Every agent must extend BaseAgent and implement execute()
- Every squad must be defined in a squad YAML with a flow
- The router must route by event_type
- Governance must be explicit — do not use NoopGovernance in production code
- Folder structure, naming, and config patterns must match the reference example

The combination of CLAUDE.md, SKILLS.md, and the reference example gives Claude Code enough context to generate architecturally consistent, governed, runnable K9-AIF applications from a spec document alone.

Read more: Build a K9-AIF Example App in Minutes Using Claude Code

Automated hooks (.claude/settings.json)

The repository also ships .claude/settings.json, which wires five PostToolUse hooks — Python syntax check, YAML validation, ABB test run, governance check, and __init__.py docstring check (see Hooks in CLAUDE.md) — that run automatically whenever Claude Code writes or edits a file.

Each hook command uses an absolute path (e.g. /Users/<you>/k9-aif-framework/.claude/hooks/check-python.sh). After cloning, edit .claude/settings.json and replace the path prefix with the absolute path of your own clone, or the hooks will fail with "command not found".

---

Quick Start (Linux / Ubuntu)

Clone the framework and create a Python virtual environment:

git clone https://github.com/k9aif/k9-aif-framework.git
cd k9-aif-framework

python3.11 --version
python3.11 -m venv .venv
source .venv/bin/activate

python --version
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

once this is done: you can directly test out the demos: from the k9-aif-framework folder, run the commands:

./run_acme_support_center.sh

(k9chat moved to its own repo, k9-aif-examples — clone it as a sibling directory and see its k9chat/README.md for setup and run instructions.)

test programs from the tests folder can be run like below:

python -m k9_aif_abb.tests.<test program name>

---

Project Status

K9-AIF is an actively evolving framework. The repository contains reference architecture material, prototype implementations, and example applications used to explore practical approaches to building governed agentic AI systems.

---

License

This repository is released under the Apache License 2.0.

The framework concepts may be used, adapted, and extended for research and development of agentic AI systems.

---

Contributions

Contributions, discussions, and architectural ideas related to agentic AI systems and multi-agent orchestration are welcome.

---

Architectural Foundations

K9-AIF draws inspiration from established software architecture and enterprise architecture practices, including:

• Booch, G. Object-Oriented Analysis and Design with Applications
• Gamma, E., Helm, R., Johnson, R., Vlissides, J. Design Patterns: Elements of Reusable Object-Oriented Software
• The Open Group. TOGAF Standard

---

Architecture Notes & Blog

The K9-AIF blog contains architecture discussions, design evaluations, and evolving ideas related to building governed agentic AI systems.

➡️ https://blog.k9x.ai

---

Author's Recommendation

1. Know the Framework

Before building, understand the architecture. K9-AIF is built on a strict ABB/SBB separation — Architecture Building Blocks define the contracts, Solution Building Blocks implement the domain. Read CLAUDE.md for architecture and SKILLS.md for step-by-step recipes. These are the two documents that will make you productive fast.

2. Use Claude Code with VS Code — the Recommended Path

The most effective way to build with K9-AIF is Claude Code inside VS Code.

K9-AIF ships with CLAUDE.md and SKILLS.md — these are loaded automatically by Claude Code, giving it a deep understanding of the framework's architecture, conventions, and code generation rules. Claude Code will generate agents, squads, orchestrators, and config that comply with the framework out of the box, without you having to explain the patterns each time.

Download and install Claude Code from: https://claude.ai/code

It is available as a VS Code extension, a desktop app, and a CLI. Once installed, open your solution folder in VS Code and Claude Code is ready to use.

Claude Code understands:

• ABB contracts and how to extend them correctly
• Squad YAML format, agent registration, flow structure
• Kafka ownership (Router publishes, Orchestrator consumes)
• Governance enforcement patterns
• The full inference pipeline through llm_invoke

3. No Claude Code? Use K9X Studio

If you are not using Claude Code, use K9X Studio (drag-and-drop canvas → Generate Scaffold) to create a compliant solution stub — see the K9-AIF Developer Journey section above.

A dedicated architectural conformance inspector for validating any K9-AIF solution (k9x_inspector) is in active development in k9x-ecosystem — an earlier, naive per-file version of this check shipped inside the framework itself but produced false positives on legitimate code (it didn't resolve inheritance chains) and has been removed.

---

Happy Coding!

Building Architecture-First Agentic Applications — done right, that really works.

---

Author

Ravi Natarajan AI Systems Architect Agentic AI • Multi-Agent Systems • LLM Applications

Email: ravinatarajan@k9x.ai Website: https://k9x.ai

---