Agent Model

Part of Project Kaze Architecture

What is an Agent?

An agent is the primary unit of computation in Kaze. Unlike traditional services that passively handle requests, an agent is an autonomous, intelligent entity that reasons about tasks, uses tools, learns from experience, and operates under governance.

┌─────────────────────────────────────────────────┐
│  AGENT                                          │
│                                                 │
│  Identity     role, tenant, vertical            │
│  Skills       composable capabilities           │
│  Knowledge    what the agent knows/remembers     │
│  Tools        external services it can call      │
│  Autonomy     supervised → sampling → autonomous │
│  State        idle → executing → waiting         │
│                                                 │
│  ┌───────────────────────────────────────────┐  │
│  │ LLM (reasoning engine)                    │  │
│  │ "Given my role, knowledge, and tools,     │  │
│  │  how should I approach this task?"         │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

An agent is not a stateless function, a chatbot wrapper, or a cron job. It is a persistent entity with:

• Identity — bound to a tenant and a role ("SEO strategist for Client A")
• Memory — reads from and writes to the knowledge system
• Reasoning — uses an LLM to think through tasks, not just pattern-match
• Tools — calls external APIs and services to take real actions
• Judgment — decides how to decompose work, when to escalate, when to ask for help
• Trust level — earns autonomy over time through demonstrated performance

Agent Definition

Agents are defined declaratively in YAML. The runtime loads these definitions and instantiates agent instances.

agent: seo-strategist
  description: "Senior SEO strategist that researches keywords, analyzes competitors, and optimizes content"

  role: |
    You are a senior SEO strategist for {client_name}.
    Your goal is to improve organic search rankings and drive qualified traffic.
    You have deep expertise in keyword research, competitor analysis, and content optimization.
    Always ground recommendations in data from your tools and knowledge base.

  skills:
    - keyword-research
    - competitor-analysis
    - content-optimization
    - reporting

  knowledge:
    - seo/*                              # All SEO vertical knowledge
    - client/{client_id}/business-context # This client's context
    - client/{client_id}/seo-history      # Past SEO work for this client

  tools:
    - semrush_api
    - google_search_console
    - google_analytics
    - llm

  autonomy_level: supervised             # Starting level — earns more over time

  supervision:
    escalate_to: seo-lead                # Escalate unclear decisions to this agent
    approval_channel: slack              # Where to send approval requests
    sampling_rate: 0.2                   # When in sampling mode, review 20% of outputs

What Each Field Means

Field	Purpose
role	System prompt that defines the agent's persona, expertise, and behavioral guidelines
skills	List of composable capabilities the agent can execute
knowledge	Knowledge graph paths the agent can read from (and contribute to)
tools	External APIs and services the agent is authorized to call
autonomy_level	Current trust level: supervised, sampling, or autonomous
supervision	Escalation path, approval routing, and review sampling configuration

Skills — The Composable Unit

A skill is the atomic reusable unit of agent capability. Skills are the building blocks from which agents are composed.

skill: keyword-research
  description: "Research and evaluate keyword opportunities for a business"

  inputs:
    - business_context     # What the client does
    - current_rankings     # Optional: existing search positions
    - competitors          # Optional: known competitors

  tools_required:
    - semrush_api
    - google_search_console
    - llm                  # Analysis & reasoning

  outputs:
    - keyword_opportunities  # Structured list
    - priority_ranking       # Scored and ordered
    - reasoning              # Why these keywords

  knowledge_dependencies:
    - seo/domain-concepts
    - seo/best-practices

  quality_criteria:
    - relevance_score > 0.8
    - business_alignment check
    - search_volume validation

Skills are vertical-portable — when expanding from SEO to content marketing, skills like keyword-research and competitor-analysis carry over. New vertical-specific skills are built alongside existing ones.

Skill vs. Agent

	Skill	Agent
What	A single capability	A composition of skills + role + context
State	Stateless — runs and returns	Stateful — persists across tasks
Identity	Generic	Bound to a tenant and role
Memory	None	Reads/writes knowledge graph
Autonomy	Inherits from agent	Has its own supervision level

Agent Lifecycle

                    ┌──────────┐
                    │  Define  │  YAML definition loaded
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │  Spawn   │  Bind to tenant, resolve skills,
                    │          │  connect to gateway + knowledge + tools
                    └────┬─────┘
                         │
                    ┌────▼─────┐
              ┌────▶│  Ready   │◀────┐
              │     └────┬─────┘     │
              │          │ task      │ done
              │     ┌────▼─────┐     │
              │     │Executing │─────┘
              │     └────┬─────┘
              │          │ needs approval
              │     ┌────▼─────┐
              │     │ Waiting  │  (supervised/sampling mode)
              │     └────┬─────┘
              │          │ approved / rejected
              └──────────┘
                         │ idle timeout or shutdown signal
                    ┌────▼─────┐
                    │ Shutdown │  Flush state, release resources
                    └──────────┘

Spawn: Load agent YAML → resolve skill definitions → load TypeScript handlers (if any) → connect to LLM Gateway, Knowledge System, Tool Framework → set state = ready.

Task Execution: Receive task → check supervision level for this skill → execute → route output based on autonomy level → log everything to Observation Logger.

Supervision Modes:

Mode	Behavior
Supervised	Execute → queue output for human review → wait for approval before delivery
Sampling	Execute → randomly sample X% for review → deliver rest immediately
Autonomous	Execute → deliver directly → log for async quality monitoring

Supervision Ramp

Agents don't start autonomous. They earn trust through demonstrated performance.

supervised ──────▶ sampling ──────▶ autonomous
   │                  │                  │
   │ 50 runs at       │ 100 runs at     │ Continuous
   │ 95%+ approval    │ 98%+ quality    │ quality monitoring
   │                  │                  │
   └── demotion ◀─────┴── demotion ◀────┘
       if quality drops    if quality drops

Per-skill, not per-agent. An SEO strategist agent might be autonomous for keyword research (high confidence, lots of data) but still supervised for content strategy (newer skill, less validation data).

Promotion criteria:

• Minimum run count threshold met
• Approval/success rate above threshold
• No safety violations in evaluation window
• Quality monitor agent concurs

Demotion triggers:

• Quality score drops below threshold
• Human explicitly rejects output
• Safety boundary violated
• Cost anomaly detected

Agent Types

Kaze has three tiers of agents, corresponding to system layers:

Layer 1: Worker Agents (Execution)

Perform actual work using skills. Most agents are workers.

• Examples: SEO strategist, content writer, lead scorer, report generator
• Composed from: Skills + role + client context
• First to earn autonomy — most constrained, most validated

Layer 2: Orchestrator Agents

Plan, decompose, and coordinate work across worker agents.

• Examples: Campaign planner, workflow coordinator, intent router
• Key difference from workers: They don't execute tasks — they decide what tasks to execute and who should do them
• Dynamic planning: Unlike static DAG workflows, orchestrators reason about the best approach and can re-plan at runtime if steps fail

Layer 3: Governance Agents

Monitor, evaluate, and improve the system. Last to become autonomous.

• Supervisor agents — Watch fleet health, detect failures, take corrective action
• Quality monitor agents — Evaluate outputs, catch hallucinations, score task completion
• Improvement agents — Analyze patterns, propose prompt refinements, skill updates

Agent Communication

Agents communicate via messages, not direct function calls. This enables loose coupling and async coordination.

┌──────────┐   message    ┌──────────┐
│ Agent A  │─────────────▶│ Agent B  │
│ (worker) │              │ (worker) │
└──────────┘              └──────────┘
      │                         │
      │ event                   │ event
      ▼                         ▼
┌──────────────────────────────────────┐
│  Message Transport                    │
│  MVP: DirectCallTransport (in-proc)  │
│  Phase 2: NATS (distributed)         │
└──────────────────────────────────────┘

MVP: DirectCallTransport — agents call each other in-process. Simple, fast, good enough for single-node.

Phase 2: NatsTransport — agents communicate via NATS message bus. Enables distributed deployment, cross-cell communication, and event sourcing.

LLM Gateway

No agent ever holds a raw API key or calls an LLM provider directly. All LLM access goes through the gateway.

┌─────────┐     ┌──────────────────┐     ┌──────────────┐
│  Agent   │────▶│   LLM Gateway    │────▶│  Anthropic   │
│          │     │                  │────▶│  OpenAI      │
│          │     │  - Key routing   │────▶│  Google      │
│          │     │  - Budget mgmt   │────▶│  Local/Ollama│
│          │     │  - Usage tracking│     └──────────────┘
│          │     │  - Rate limiting │
│          │     │  - Fallback      │
└─────────┘     └──────────────────┘

Responsibilities:

• Key Routing — Resolves which API key to use per request based on tenant, agent, and provider configuration (see Security for dual-key model)
• Provider Abstraction — Agents call a unified interface (complete(messages, tools, model_hint)). The gateway resolves to a specific provider/model
• Budget Management — Per-key, per-tenant, per-agent token tracking with configurable budget caps and hard stops
• Rate Limiting — Respects provider rate limits, queues requests, distributes load
• Fallback — If a provider is down or rate-limited, automatically falls back to alternatives
• Model Selection — Routes to the cheapest model that meets the quality bar for a given task type

Putting It Together — Example Flow

A client sends a message on Slack: "Research keyword opportunities for our new product launch"

1. Slack adapter receives message
2. Conversation Manager identifies intent → routes to SEO vertical
3. Router agent picks: seo-strategist agent for Client A
4. Agent runtime checks: keyword-research skill is in "sampling" mode

5. seo-strategist agent:
   a. Reads client context from knowledge system
   b. Calls semrush_api (via Tool Framework) for keyword data
   c. Calls google_search_console for current rankings
   d. Reasons about opportunities using LLM (via Gateway)
   e. Writes findings to knowledge system
   f. Produces structured output

6. Supervision check: sampling mode → 20% chance of review
   - If sampled: queue for human review, deliver after approval
   - If not sampled: deliver immediately

7. Output delivered back through Slack
8. Observation Logger records: task, duration, tokens, tools used, outcome
9. Quality monitor agent evaluates output quality asynchronously

Architecture Comparison

vs. Traditional Patterns

Dimension	Microservices	Actor Model	Kaze Agent
Primary unit	Service	Actor	Agent (intelligent actor)
Communication	API / events	Messages	Messages + shared knowledge
State	Own DB per svc	Private per actor	Private + shared knowledge graph
Intelligence	None	None	Core design property
Self-modification	No	No	Yes (governed)
Supervision	Health checks	Supervisor trees	Intelligent supervision hierarchy

Key Architectural Tensions

Agent Autonomy vs. System Coherence: Agents are independent in how they work (runtime isolation, own state) but connected through the knowledge graph and event bus for what they know and why they act.

Static Infrastructure vs. Dynamic Agent Topology: Layer 0 (platform) is static infrastructure deployed via IaC. Layers 1-3 (agents) are dynamic — the agent runtime hosts whatever agents the system needs at any given moment.

Cell Isolation vs. Knowledge Sharing: Vertical knowledge syncs across cells (opt-in, anonymized, managed centrally). Client knowledge never leaves the cell.