Skip to content

Knowledge Base

Agent Architecture

cl24s/knowledge-base

Agent Architecture¶

Agent Architecture covers how LLMs, skills, loops, tools, state, memory, retrieval, policy and deterministic application code are assembled into maintainable production software.

The central rule is:

An agentic application is still a software system. AI components should fit inside explicit module, dependency, security and runtime boundaries rather than replace them.

Roadmap¶

1. Agent Architecture Mental Model ¶

Model vs agent vs runtime, probabilistic core inside a deterministic shell, control plane vs execution plane, canonical state and main trust/failure boundaries.

Status: first detailed draft complete.

2. Application Structure in the AI Era ¶

Modular monolith vs microservices, Hexagonal/Ports & Adapters, Clean Architecture, DDD/bounded contexts, AI provider isolation, sync/async boundaries and service-extraction criteria.

Status: first detailed draft complete.

3. Core Agent Runtime and Orchestrator ¶

Run lifecycle, execution IDs, state-machine orchestration, model gateway, capability registry, policy coordination, checkpoint/resume, cancellation, timeout and concurrency.

Status: first detailed draft complete.

4. Context Architecture ¶

Context as a temporary projection of canonical sources, context-purpose-specific assembly, token budgets, freshness, provenance, trust levels, compaction and retrieval/tool/memory integration.

Status: first detailed draft complete.

5. Tool and Capability Architecture ¶

Capability vs tool vs port vs adapter, typed registries, effect/risk classification, MCP/connectors, authorization, normalized results, side-effect safety and idempotency.

Status: first detailed draft complete.

6. Skill Architecture ¶

Skill ownership, registries, contracts, capability dependencies, provider-independent execution, versioning, rollout and explicit composition boundaries.

Status: first detailed draft complete.

7. State and Memory Architecture ¶

Domain state vs execution state vs session vs long-term memory vs context, durable checkpoints, concurrency, memory read/write policy, provenance and retention.

Status: first detailed draft complete.

8. Knowledge and Retrieval Architecture ¶

RAG subsystem boundaries, ingestion vs serving, source adapters, chunking/search/reranking, provenance, freshness, ACLs and operational-tool-vs-retrieval decisions.

Status: first detailed draft complete.

9. Single Agent, Workflow and Multi-Agent Patterns ¶

Deterministic workflows, agentic islands, single-agent, plan/execute, planner/executor, supervisor/worker, specialist handoffs, fan-out/fan-in and multi-agent trade-offs.

Status: first detailed draft complete.

10. Security and Trust Architecture ¶

Authentication/authorization, confused deputy, scoped capabilities/credentials, prompt injection containment, approvals, sandboxing, egress, tenant isolation and audit.

Status: first detailed draft complete.

11. Reliability, Scaling and Production Runtime ¶

Async runs, queues, disposable workers with durable state, leases, retry/idempotency, rate limits, backpressure, fallbacks, bulkheads, scaling and version pinning.

Status: first detailed draft complete.

12. Evaluation, Observability and Architecture Patterns ¶

End-to-end traces, layered evals, regression gates, replay/failure injection, production metrics, reusable architecture patterns and anti-patterns.

Status: first detailed draft complete.

Complete architecture model¶

User / API / Event / Scheduler
            ↓
Application Use Case
            ↓
Durable Agent Runtime
  ├── canonical run state
  ├── context builder
  ├── policy / authorization
  ├── budgets / recovery
  ├── skill registry
  ├── capability registry
  └── observability
            ↓
Validated Capability / Skill / Workflow
            ↓
Application Port
            ↓
Infrastructure Adapter
  ├── LLM provider
  ├── retrieval/vector/search
  ├── MCP/connectors
  ├── database
  ├── queue
  ├── sandbox
  └── external API

The model receives a selected context projection and proposes semantic decisions. The runtime/application retain ownership of canonical state, lifecycle, authorization, side-effect guarantees, budgets, retry/idempotency and hard completion rules.

Software architecture stance¶

For many AI applications, a well-modularized monolith is a strong default. AI does not invalidate Hexagonal Architecture, Clean Architecture, dependency inversion or bounded-context thinking; it makes those boundaries more valuable because model providers, vector stores and agent frameworks are volatile dependencies.

A recurring dependency direction is:

Business / Domain Core
        ↑ ports
Application Use Cases
        ↑
Agent Runtime / Capability Contracts
        ↑
Infrastructure Adapters

Organize modules around business capabilities rather than vendors such as openai/, qdrant/ or mcp/ at the architectural center.

Split services for concrete reasons:

independent scaling
security / sandbox isolation
availability boundary
separate ownership
different deployment lifecycle
special runtime dependency

not because "AI requires microservices".

Topology stance¶

Prefer the simplest control topology that solves the problem:

Deterministic code
      ↓ if semantic reasoning needed
Workflow + agentic island
      ↓ if iterative autonomy needed
Single modular agent
      ↓ only with real separation need
Multi-agent

Multi-agent should be justified by responsibility, permission, trust, scaling or ownership boundaries and evaluated against a simpler baseline.

State/context/memory stance¶

Domain/operational truth
        ↓
Canonical execution state
        ↓
Session + intentionally persisted memory
        ↓
Purpose-specific context projection
        ↓
Model

Chat history or model context should not become hidden canonical state.

Retrieval stance¶

RAG is an evidence subsystem:

sources → ingest/index → retrieve/rerank → Evidence[] → context

Use retrieval for reference knowledge and live tools/application services for current operational state. Preserve provenance, freshness and authorization before evidence reaches the model.

Security stance¶

model proposes
      ↓
deterministic validate / authorize / approve
      ↓
scoped execution
      ↓
observe / audit

Prompt instructions are not security boundaries. Credentials, tenant isolation, approvals, sandboxing and high-risk side effects remain deterministic application/infrastructure responsibilities.

Production stance¶

Workers are disposable; run state is durable. Long-running runs should checkpoint, wait without consuming workers, resume from events, tolerate queue redelivery and reconcile uncertain side effects.

Run Service → Queue → Worker → Runtime → State Store / Capabilities

Reliability, evaluation and observability are architecture concerns from the beginning, not post-launch additions.

Learning order¶

Completion state¶

The Agent Architecture workstream is complete at first-draft depth. Together with Agent Skills and Agentic Loops, the Agentic Engineering area now has a complete first-pass mental model from reusable capability contracts through runtime loops to production software architecture.

Future updates should refine these chapters from implementation experience, architecture reviews and production/evaluation lessons rather than add more linear roadmap topics.

Next step¶

Review and question the completed Agentic Engineering material. The next separate AI workstream can then be chosen deliberately from areas such as RAG, MCP or Memory, depending on which implementation direction is most useful next.