AI Friendly Architecture Design

Overview

AI Friendly architecture enables traditional systems to handle AI's inherent uncertainty through three paradigm shifts: deterministic→probabilistic, structured→semantic, and static→dynamic. This skill guides agents to apply these principles correctly and avoid common anti-patterns.

Core principle: Use appropriate architecture for the problem—don't over-engineer with AI when traditional solutions suffice.

When to Use

Use when:

• Designing systems that incorporate LLM/AI capabilities
• Evaluating whether to use AI Friendly architecture vs traditional architecture
• Designing Agent-based systems (ReAct, Plan, Multi-Agent)
• Creating APIs that will be consumed by AI Agents
• Building context engineering pipelines for AI applications

Do NOT use when:

• Building simple CRUD applications with no AI requirements
• Creating AI Workflow applications that only call pre-built Agents as APIs
• The system only needs deterministic, rule-based logic

The Three Paradigm Shifts

1. Deterministic → Probabilistic

Traditional: Output follows y=f(x) mapping—binary success/failure.

AI Friendly: Output emerges from model + prompt + context + environment. Design goal: converge probabilistic output to an acceptable "safe interval" through RAG, prompt engineering, and evaluation mechanisms.

Design implication: Don't expect exact schema compliance from AI outputs. Build validation and fallback mechanisms.

2. Structured → Semantic

Traditional: Input must match predefined Schema exactly (JSON field types). System boundary is a rigid wall.

AI Friendly: System understands natural language and unstructured data. Responds based on intent, not format. System boundary becomes an elastic membrane.

Design implication: Design interfaces that accept flexible inputs and translate intent to actions.

3. Static → Dynamic

Traditional: Execution paths defined by hardcoded if-else logic or rules. Behavior is enumerable and verifiable.

AI Friendly: System makes decisions based on models, can reason about current state, decompose tasks, and respond to unknown changes without human intervention.

Design implication: Shift from "rules" to "planning"—grant systems autonomy for intelligent task orchestration.

Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                    Quality & Stability Layer                 │
│         (AI Observability, Evaluation, Security)            │
├─────────────────────────────────────────────────────────────┤
│                      Application Layer                       │
│    ┌──────────┐  ┌──────────┐  ┌──────────────────────┐    │
│    │  Agent   │  │  Intent  │  │      Session         │    │
│    │  Layer   │  │  Layer   │  │      Layer           │    │
│    └──────────┘  └──────────┘  └──────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│                    Capability Layer                          │
│         (MCP, RAG, Function Calling)                        │
├─────────────────────────────────────────────────────────────┤
│                   Foundation Layer                           │
│    ┌──────────┐  ┌──────────┐  ┌──────────────────────┐    │
│    │  Model   │  │ Knowledge│  │   Tool Management    │    │
│    │Management│  │Management│  │                      │    │
│    └──────────┘  └──────────┘  └──────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Foundation Layer

• Model Management: Unified API (OpenAI protocol) for multiple LLM providers
• Knowledge Management: Vector storage and retrieval for different knowledge sources
• Tool Management: MCP protocol for tool integration, Computer Use skills

Agent Layer

Three Agent types for different scenarios:

ReAct + Plan Combination:

• Plan produces global strategy (use templates for quality)
• ReAct executes domain-specific reasoning
• Together they handle both strategic and tactical problems

Intent Layer

Required only for multi-intent scenarios. Handles:

• Parallel intents: Multiple independent intents in one query
• Sequential intents: Intent B depends on Intent A result
• Logical intents: Intents with logical relationships

Also performs query rewriting and expansion for intent optimization.

Session Layer

Focus on Context Engineering—more important than model selection:

• Long-term memory: User history, preferences, past interactions
• Short-term memory: Current session context
• Historical case libraries: Past successful cases for reference
• Hybrid decision-making: Multi-model voting with confidence scores

Multi-Agent Patterns

Three coordination patterns:

MOE (Mixture of Experts) Pattern:

• Each domain has specialized Agent (product, order, inventory, etc.)
• Central Agent performs intent recognition and task distribution
• Domain Agents execute with ReAct + Plan capabilities

AI Friendly API Design

Tool Atomicity

Split interfaces into atomic tools matching Agent reasoning patterns:

❌ getProductWithInventoryAndPricing(id)
✅ getProduct(id)
✅ getInventory(productId)
✅ getPricing(productId)

Parameter Design

Human-readable names, flat KV structure, core parameters only:

// ❌ Bad: Nested, complex
{"product": {"identifiers": {"sku_id": "123"}, "filters": {"status": "active"}}}

// ✅ Good: Flat, clear
{"sku_id": "123", "status": "active"}

Error Handling

• Expected errors: Short descriptions for Agent reasoning
• Unexpected errors: Stack traces for error diagnosis

Context Engineering

Beyond Prompt Engineering

Context Engineering is about selecting, organizing, and compressing information optimally within context windows:

1. Historical Case Library: Store past successful cases, retrieve similar cases via vector search (8% accuracy improvement)
2. Hybrid Decision-Making: Multiple models vote with confidence scores (10%+ accuracy improvement)
3. Memory Management: Long/short-term memory with summarization

Advanced RAG Techniques

• Knowledge graphs (GraphRAG)
• Dynamic context pruning

Quick Reference: Decision Framework

Is the task deterministic?
├─ Yes → Use traditional architecture (MVC/DDD)
└─ No → Does it need language understanding?
    ├─ No → Use rules or traditional ML
    └─ Yes → Does it need dynamic tool selection?
        ├─ No → Single LLM call or AI Workflow
        └─ Yes → Does it need multi-step reasoning?
            ├─ No → ReActAgent
            └─ Yes → PlanAgent + ReActAgent
                └─ Multiple domains? → Multi-Agent (MOE pattern)

Common Mistakes

Rationalization Table

Red Flags - STOP and Reconsider

• Adding AI without clear problem definition
• Using Agents where simple LLM calls suffice
• Complex nested APIs for Agent consumption
• Skipping evaluation and observability
• Ignoring the "when NOT to use" guidelines

Real-World Impact

From production systems:

• AI Review: 95.7% accuracy, 99.1% recall, 80%+ efficiency improvement
• AI Q&A (CogentAI): 98%+ problem-solving accuracy, 80%+ efficiency improvement
• Key success factors: Proper architecture selection, Context Engineering, continuous evaluation