Agent Utilities

agent-utilities — Master Skill Reference

CONCEPT:AU-ECO.toolkit.self-documenting-plugin-bundle — Self-Documenting Skill-Graph

agent-utilities is a self-evolving AI framework built on 5 pillars. This skill-graph provides agents (Antigravity, Claude Code, Windsurf, OpenCode) with complete context for using, developing, and extending the framework.

🏗️ Architecture — The 5 Pillars

📍 Quick Navigation

🧬 Concept ID System

Every feature in agent-utilities has a CONCEPT:X.Y tag providing 1:1:1 traceability:

CONCEPT:AU-ORCH.adapter.hot-cache-invalidation  →  code: graph/routing.py
                  →  test: tests/unit/graph/test_routing.py
                  →  docs: docs/pillars/1_graph_orchestration/ORCH-1.2.md

40 canonical concepts across 5 pillars. All new features require DSTDD design phase. See docs/concept_map.md for the complete registry.

🔧 Core Dependencies

• Pydantic AI: Agent framework with structured output
• NetworkX: Graph engine for KG operations
• RDFLib/OWLReady2: OWL ontology reasoning
• LM Studio: Default local LLM backend (vllm.example)

🤖 Agent Usage Guide

• When developing FOR agent-utilities, consult development/SKILL.md
• When USING agent-utilities tools, consult tools/SKILL.md
• Every code module has a CONCEPT:X.Y tag in its docstring — use this for traceability
• All prompts live in agent_utilities/prompts/*.json — reference by agent name
• OWL ontologies are in knowledge_graph/ontology_*.ttl
• The KG MCP server (graph-os) exposes graph_query, graph_search, graph_write, graph_analyze, graph_ingest, and graph_orchestrate (full reference: tools/SKILL.md) — condensed by default (MCP_TOOL_MODE=condensed, ~95 tools); a small/cheap-LLM deployment can instead set MCP_TOOL_MODE=intent (CONCEPT:AU-ECO.mcp.intent-surface-condensed-collapse, Seam 8) to collapse them behind six ask/find/write/act/manage/why verbs — see docs/architecture/intent-surface.md

📦 Package Structure

agent_utilities/
├── core/              # OS-5.x: Config, paths, model factory, scheduler
├── graph/             # AU-ORCH.planning.orchestration-overview: Planner, executor, routing, HSM, lifecycle
├── knowledge_graph/   # AU-KG.compute.kg-x: Engine, memory, ontologies, KB, retrieval
├── harness/           # AU-AHE.optimization.telemetry-optimization: Evaluation engine, evolution engine
├── mcp/               # ECO-4.x: Server factory, KG server
├── tools/             # ECO-4.x: X search, tool filtering
├── security/          # OS-5.x: Guardrails, tool guard
├── observability/     # OS-5.x: Token tracker, audit logger
├── models/            # Pydantic models: graph, knowledge_graph, company
├── prompts/           # Agent prompt JSON definitions
├── workflows/         # Workflow compiler, skill compiler, distillation
└── docs/              # Pillar docs, concept map, guides