AI Agent Architecture

日本語版 (Japanese)

MCP alone is not enough — this repo addresses how Agents discover and orchestrate Skills, Tools, Memory, and Identity.

A repository documenting design principles, architecture, and practical knowledge for AI agent configuration (MCP, Skills, Agent, Memory, and Agent ID integration).

📚 Sister Projects

A 3-phase learning path: "Know LLMs → Know Agent Design → Apply to Systems."

📖 Documentation

Full documentation is available at:

👉 https://shuji-bonji.github.io/ai-agent-architecture/

The documentation site provides:

• Concepts & Vision (8 chapters) — Why "stable reference sources" matter, the three-layer model, doctrine and intent, and the Memory layer / Knowledge Graph
• MCP (Model Context Protocol) — External integration layer with standardized protocols
• Skills (Domain Knowledge) — Static knowledge that complements MCP's real-time capabilities
• Agents — Agent taxonomy, sub-agents, quality gates, multi-agent / Agent Teams, A2A protocol, and Agent ID (the Agent ID era)
• FAQ (3-line answers) — Direct answers to common queries: MCP vs Skills, Agent vs Sub-agent vs Skill vs MCP
• Strategy & Composition Patterns — MCP × Skill × Agent composition design

Why This Matters Now (as of May 2026)

The AI agent ecosystem has moved from "specification consideration" into production operation phase.

• April 2026: Microsoft Entra Agent ID GA, Okta for AI Agents GA, A2A v1.0 GA — Linux Foundation A2A protocol surpasses 150 participating organizations
• December 2025: AGENTS.md donated to Linux Foundation by OpenAI and Anthropic — industry standardization
• October 2025: OpenID Foundation "Identity Management for Agentic AI" v1.1 — Agent ID systematization
• November 2024: Anthropic releases MCP

This site tracks these shifts and documents practical patterns for building production-ready agent systems.

Core Architecture (Four-Layer Model + Doctrine)

┌─────────────────────────────────────────────────────────┐
│                      User Request                       │
└─────────────────────────┬───────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Doctrine Layer       (Constraints, objectives, judgment)│
├─────────────────────────────────────────────────────────┤
│  Agent Layer          (Orchestration & decision)         │
├─────────────────────────────────────────────────────────┤
│  Skills Layer         (Domain knowledge & guidelines)    │
├─────────────────────────────────────────────────────────┤
│  Memory Layer         (Persisted memory & relationships) │
├─────────────────────────────────────────────────────────┤
│  MCP Layer            (External tools & APIs)            │
└─────────────────────────────────────────────────────────┘

Quick Decision Flow

Need a quick answer? See the FAQ section for 3-line decisions.

flowchart TD
    START[New capability needed] --> Q1{What do you need?}
    Q1 -->|Reach external systems| MCP[MCP]
    Q1 -->|Teach procedures / conventions| SKILL[Skill]
    Q1 -->|Specialist in isolated context| SUB[Sub-agent]
    Q1 -->|Persisted memory / relationships| MEM[Memory layer]
    Q1 -->|Coordination of multiple agents| TEAM[Agent Teams]

    MCP --> COMBINE{Combine?}
    SKILL --> COMBINE
    SUB --> COMBINE
    COMBINE -->|Yes| MIX[Skill + Sub-agent + MCP]
    COMBINE -->|No| SOLO[Standalone is fine]

For detailed decision guides, see:

• MCP vs Skills FAQ
• Agent / Sub-agent / Skill / MCP comparison FAQ
• Sub-agent vs Skills

Related Projects

MCP Servers

Skills / Plugins

Templates

References

• Reference Links — MCP, A2A, Agent ID, and related standards
• Skills Links — Vercel Skills & Agent Skills Specification

Note

This documentation reflects the author's practical insights gained through building and operating AI agent systems with Claude. It is not official documentation from Anthropic or any other organization. Contributions and discussions via GitHub Issues are welcome.

License

Released under the MIT License. Copyright © 2025-2026 shuji-bonji