Architecture

What k9x Origin is

k9x Origin is a framework component, and MCP is one of the ways to reach it, the same way k9x Shield is a component, not a service.

So "MCP service" describes how agents call it, not what it is. OriginMCPServer is the thin MCP wrapper that carries the calls; all the logic is in K9Origin.

How it is deployed

• In K9X Streams: Origin runs inside the Streams app, and the same process serves it at /mcp. Agents connect with the framework's MCP client.
• In your own solution: the same (Origin inside your app, with its own /mcp), or added onto an MCP server you already run with register_on(mcp), so agents use one endpoint for knowing and doing.
• At scale: several Origin MCP servers behind a load balancer, all reading shared live state in Redis. Origin keeps no state of its own.

Origin is built into K9-AIF; agents talk to it over MCP; orchestrators call it directly.

Architecture

For solution architects: where k9x Origin sits, how it is filled, and its classes in the framework; then the K9X Streams application on top.

An agent's three paths: knowledge (retriever), current truth (k9x Origin), actions (systems of record), each screened by k9x Shield.

How data reaches k9x Origin: pushed by streams through the Shield gate, pulled from systems of record on demand.

One get_current call, step by step: scope, request screening, live state or read-through, verify, flags, answer screening.

k9x Origin classes in the framework (k9_origin), with the state backends, adapters and the rules agent.

The K9X Streams application

Classes: four projections, one orchestrator and one agent extend K9-AIF; everything else is the framework.

Deployment view: producers, topics, the K9X Streams service and a K9-AIF solution.

The reference model

K9X Streams is how to build an agentic application that must act on the latest information. Copy the model, not the code: your sources and your projections change; the fabric, the governance and the way agents read live context stay the same.

Sources keep their own format: an envelope mapper per topic turns each message into an event (debezium for database change records, log_line for application logs, or your own via register_mapper); a webhook receiver can skip Kafka with ContextIngest.ingest_raw(). The five steps below build on it.

Five steps

k9x Origin is built into the K9-AIF framework (1.18), like k9x Shield. K9X Streams adds only its Accounts Payable projections, a generator, one orchestrator and one agent. A solution in any domain follows the same five steps.

origin:
  enabled: true
  config: config/origin.yaml
  state: {provider: redis}        # in_memory | redis (shared, LRU-bounded)
streams:
  enabled: true                   # off: Origin answers from systems of record only
  provider: kafka
security:
  shield: {enabled: true}

entities:
  claim:
    key: claim_id
    system_of_record: claims_api     # read-through on a miss, verify before acting
    owned_fields: [status, amount]
    conflicts: {status: {transitions: ["approved -> disapproved"]}}
sources:
  claims_api: {type: mcp, server: "${CLAIMS_MCP_URL}", tool: get_claim}
squads:
  payout: {live_context: ["claim:{claim_id}"], verify_before: [PayoutAgent]}
agents:
  PayoutAgent: {allowed_entities: [claim, policy]}

class ClaimProjection(BaseContextProjection):
    entity, id_field = "claim", "claim_id"
    def accepts(self, env): return env.event_type.startswith("claim.")
    def project(self, env): return {"status": env.payload["status"],
                                    "amount": env.payload["amount"]}

origin = OriginFactory.create(config, projections=[ClaimProjection()])
ContextIngest(StreamsFactory.create_fabric(config), origin.state,
              gate=StreamsFactory.create_gate(config)).attach(["claim.updated"])
orch = PayoutOrchestrator(config, governance=shield, origin=origin)
app.mount("/", OriginMCPServer(origin).http_app())      # MCP at /mcp

rules_agent:
  adapter: k9_rules                  # or rest_rules (a decision service)
  hil_queue: claims-review
  rules:
    - {name: large claim,   when: "claim.amount > 5000",           then: hil}
    - {name: data conflict, when: "live_context.*.flags.conflict", then: hil}

Full recipe: Developer Guide 15.8 ↗ · design: k9x Origin design ↗

Your organization's Kafka or Confluent

K9X Streams speaks the Kafka protocol, so it connects to the broker you already run. Set it in .env; no code changes.

Events are JSON today; Avro with Schema Registry is next. The adapter for a broker stays a configuration choice, never a dependency: the framework stays vendor-neutral.

Security controls

Stream data and agent requests are untrusted. Each line of defence is a K9-AIF building block you configure, and each is shown working in the demo's threat simulator.

Read model, not system of record

Live state is a derived, read-only view of what is true now, rebuilt from Kafka at any time. Agents read it; they act through the systems of record, which emit events that flow back into it.

The agent's re-check shrinks the window for a duplicate action from hours to seconds; the final guarantee belongs in the system of record (an idempotency key or a unique constraint such as one payment per invoice).

Deploying at scale

K9-AIF scales by tier: router cluster, Kafka cluster, orchestrator clusters. K9X Streams adds three tiers that scale the same way.

This demo runs every tier in one process with in-memory state. Shared live state in Redis (RedisContextState, LRU-bounded, quarantine never evicted) is in K9-AIF 1.18; consumer groups with committed offsets and lag-based freshness are next.