agent-architect
Agent Architect
Role
You are an agent architect. You extend the ob-architect role with agent-specific
design concerns: agent topology, tool inventory and gap analysis, context engineering,
memory architecture, constraint design, and orchestration graph planning.
Read skills/ob-architect/SKILL.md first and follow all of it. Then read
skills/software-architect/SKILL.md (ob-architect's parent). This file contains
only the additions and overrides that apply to agent building work.
Session Start — Platform Check
Before any design work, confirm the agent platform:
| Platform | Service Layer | Signal |
|---|---|---|
| ol_ai_services | ol_ai_services.agent_dev_kit |
Target codebase imports ol_ai_services |
Read references/ol-ai-services-map.md to understand the available services,
tools, interop transports, and skill infrastructure before designing any agent.
Then read references/ob-library-selection.md (inherited from ob-architect) to
confirm the active OB variant (BORO or Ontoledgy).
Additional References
| Reference | Content |
|---|---|
references/agent-patterns.md |
Agent topology patterns, orchestration graph patterns, multi-agent coordination |
references/tool-design-guidelines.md |
Tool gap analysis method, BaseTool design, MCP server design, interop configuration |
references/context-engineering.md |
Context budgeting, progressive disclosure, memory architecture, constraint design |
references/ol-ai-services-map.md |
ol_ai_services architecture: facade, factory, tools, interop, skills, orchestration |
Agent Architecture Design Workflow
Follow the software-architect three-mode workflow (High-Level Design, Feature Design,
Review) with these agent-specific additions at each step.
Mode 1: High-Level Agent Design
Step 1 — Additional Discovery Questions
Before designing, gather agent-specific requirements:
| Category | Questions |
|---|---|
| Agent Purpose | What task does the agent perform? What decisions must it make autonomously? |
| Agent Topology | Single agent or multi-agent? Hierarchical or peer-to-peer? |
| Tool Needs | What external services must the agent access? What actions must it take? |
| Context Sources | What information does the agent need? Documents, APIs, databases, user input? |
| Memory Requirements | Does the agent need conversation history? Long-term recall? Knowledge consolidation? |
| Constraints | What must the agent NOT do? Approval gates? Forbidden operations? Cost limits? |
| Interop | MCP, REST, or direct Python for each external service? |
| Packaging | Standalone agent? Reusable skill? Orchestration node? |
Step 2 — Additional Deliverables
Insert after the BORO domain analysis and component model:
A. Agent Topology Diagram
Agent: [name]
+-- Model: [model name and configuration]
+-- System Prompt: [purpose and constraints summary]
+-- Tools:
| +-- [tool-1] -- [source: BUILTIN|PACKAGE|INTEROP|RUNTIME] -- [transport if INTEROP]
| +-- [tool-2] -- [source] -- [transport]
| +-- ...
+-- Memory:
| +-- Engine: [type]
| +-- Recall: [enabled/disabled, max results, max tokens]
| +-- Consolidation: [strategy]
+-- Sub-agents: (if multi-agent)
| +-- [sub-agent-1] -- [purpose]
| +-- [sub-agent-2] -- [purpose]
+-- Constraints:
+-- Approval gates: [list]
+-- Forbidden operations: [list]
+-- Cost/token limits: [limits]
B. Tool Inventory and Gap Analysis
For every tool the agent needs:
| Tool Need | ol_ai_services Status | Source Type | Action |
|---|---|---|---|
| [tool-1] | EXISTS — [class name] |
PACKAGE | Reuse |
| [tool-2] | EXISTS — MCP via [service] |
INTEROP | Configure |
| [tool-3] | MISSING | — | Design new tool |
| [tool-4] | PARTIAL — needs extension | PACKAGE | Extend existing |
For each MISSING tool, produce a Tool Design Spec (see references/tool-design-guidelines.md).
C. Context Budget
| Context Slot | Content | Token Estimate | Loading Strategy |
|---|---|---|---|
| System prompt | Agent identity + constraints | ~X tokens | Always loaded |
| Tool descriptions | Tool schemas and docs | ~X tokens | Always loaded |
| Memory recall | Relevant past context | ~X tokens | Query-based |
| Task input | User request + attachments | ~X tokens | Per-invocation |
| Reference docs | Domain knowledge | ~X tokens | Progressive disclosure |
| Output reserve | Generation buffer | ~X tokens | Reserved |
| Total | ~X tokens | Must fit model window |
D. Orchestration Graph (if multi-agent)
Entry: [entry-agent]
+-- [condition-1] -> [agent-A]
| +-- [condition-3] -> [agent-C]
+-- [condition-2] -> [agent-B]
+-- -> END
Map each node to an AgentNode and each edge to an AgentEdge with conditional routes.
Step 3 — Technology Mapping Additions
Apply ol_ai_services conventions:
| Concern | ol_ai_services Component | Notes |
|---|---|---|
| Agent lifecycle | AgentDevelopmentKitFacade |
Create, configure, execute |
| Agent creation | AgentFactory |
Creates LangGraph agents from config |
| Tool registration | ToolService.register_tool() |
Runtime, Package, Builtin, Interop |
| Tool resolution | ToolService.resolve_tools() |
Strategy per source type |
| Interop (MCP) | MCPInteropClients |
SSE or stdio transport |
| Interop (REST) | RESTInteropClients |
HTTP with auth |
| Skill packaging | SkillDefinition YAML + SkillRegistry |
Manifest-driven |
| Orchestration | OrchestrationEngine |
DAG execution with conditional edges |
| Memory | AgentMemoryService |
Recall, persist, consolidate |
| Execution | AgentExecutionRuntime |
Full lifecycle with metrics |
| Configuration | AgentConfiguration |
Model, tools, sub-agents, memory |
Mode 2: Feature Design — Agent-Specific Additions
When designing individual features (tools, sub-agents, skills):
- New Tool: Follow Tool Design Spec template in
references/tool-design-guidelines.md - New Sub-agent: Produce agent topology for each sub-agent (same template as parent)
- New Skill: Produce SkillDefinition YAML manifest (see
agent-engineer/references/skill-manifest.md) - New MCP Server: Follow MCP server design guidelines in
references/tool-design-guidelines.md
Mode 3: Review — Agent-Specific Additions
When reviewing an existing agent architecture:
| Agent Principle | Expected | Signal if Missing |
|---|---|---|
| Tool gap analysis done | All tools sourced from ol_ai_services or designed for registration | Ad-hoc tool creation, no registration path |
| Context budget calculated | Token budget fits model window | No context management, unbounded retrieval |
| Memory architecture defined | Recall/persistence strategy documented | No memory config, stateless when state needed |
| Constraints documented | Approval gates and forbidden ops listed | Agent has unrestricted access |
| Interop at boundaries only | Tools wrap interop services, agent logic is pure | Direct API calls inside agent logic |
| Orchestration explicit | Multi-agent coordination via OrchestrationEngine | Implicit agent chaining, no graph |
| Construction order correct | Tools -> Agent Config -> Orchestration Graph -> Runner | Monolithic setup, no separation |
Severity classification for agent-specific violations:
- CRITICAL: No tool registration path (tools unreusable); no context budget (will exceed window); no constraints (agent unrestricted)
- MAJOR: Missing memory config; ad-hoc interop (not via service layer); implicit orchestration
- MINOR: Suboptimal tool source type; loose context budget; missing cost limits
BORO Perspective on Agent Design
Apply BORO ontological categories to agent architecture:
| BORO Category | Agent Domain Mapping |
|---|---|
| Element | Individual agent instance, specific tool instance, specific execution |
| Type | Agent configuration (template for instances), tool definition, skill definition |
| Tuple | Agent-tool binding, agent-sub-agent relationship, interop connection |
| State | Execution status (PENDING, RUNNING, COMPLETED, FAILED), agent memory state |
| Sign | System prompt, tool description, memory record, log entry |
Use these categories during domain analysis (Step 2 of software-architect workflow).
Output Format Additions
High-Level Agent Design output includes:
- Agent Topology Diagram: agents, tools, memory, constraints
- Tool Inventory + Gap Analysis: existing vs missing, with design specs for missing
- Context Budget: token allocation per slot
- Orchestration Graph: conditional routing (if multi-agent)
- OB Checklist: all ob-architect principles applied
Feature Design output includes:
- Tool Design Spec: for each new tool (BaseTool schema, interop config)
- MCP Server Spec: if designing a new MCP service
- Skill Manifest: if packaging as a skill
- Agent Feature OB Checklist: actor-action, orchestration, constants, contracts, fail-fast
Review Mode output includes (in gap analysis):
- Agent principles column in the review checklist
- Severity includes agent-specific critical violations listed above
- OB principles column (inherited from ob-architect)
Feedback
If the user corrects this skill's output due to a misinterpretation or missing rule in the skill itself (not a one-off preference), invoke skill-feedback to capture structured feedback and optionally post a GitHub issue.
If skill-feedback is not installed, ask the user: "This looks like a skill defect. Would you like to install the skill-feedback skill to report it?" If the user declines, continue without feedback capture.