EPIC: Agentic API Layer — Self-Documenting Control Plane for AI Agents #282
Description
The Problem
AI agents calling the AgentField control plane frequently hit wrong endpoints and get back {"error": "endpoint not found"} with zero guidance. The control plane has 80+ endpoints but no self-documenting mechanism for programmatic consumers.
Beyond API discovery, agents building on AgentField have no programmatic way to access SDK patterns, architectural best practices, or operational knowledge. They read markdown files from disk and hope READMEs are current.
The Insight
Agents interacting with AgentField fall into three distinct personas at different lifecycle stages — each with fundamentally different needs:
| Persona | Stage | Needs |
|---|---|---|
| Builder | Development | SDK patterns, architecture guidance, API reference, examples |
| Operator | Runtime | Submit/track jobs, debug failures, manage lifecycle, batch operations |
| Autonomous | Execution | Discover capabilities, execute workflows, observe results, self-correct |
The foundation (smart 404s, API discovery, catalog) serves all three. The query/batch layer serves operators and autonomous agents. The knowledge base serves builders primarily.
What We Built
Transformed the control plane from a pure orchestration server into a knowledge-serving platform purpose-built for AI agent consumption.
Feature Branch: feat/agentic-api
Pull Request: #283
Phase 1: API Catalog + Smart 404 (Foundation) ✅
In-memory registry of all 80+ endpoints with metadata, fuzzy matching (Levenshtein + segment overlap), and auth-aware filtering. Replaces the useless {"error": "endpoint not found"} with intelligent suggestions pointing agents to the right endpoint.
Issue: #275 (closed)
Phase 2: Operator + Autonomous Endpoints ✅
- Discover (feat: Agentic Discover endpoint — API search for agents #276 closed) — Search endpoints by keyword/group/method
- Unified Query (feat: Unified query endpoint for operator/autonomous agents #277 closed) — Single call for runs/executions/agents/workflows/sessions
- Run Overview + Agent Summary (feat: Run overview + Agent summary endpoints #278 closed) — Everything about a run or agent in one call
- Batch + Status (feat: Batch operations + System status endpoints #279 closed) — Up to 20 concurrent operations; system health overview
Phase 3: Knowledge Base API (Builder) ✅
40 articles across 6 topics (building, patterns, observability, identity, sdk, examples) compiled into the binary. Goal-oriented guide endpoint turns "I want to build X" into a curated reading path. Public access, no auth required.
Issue: #280 (closed)
Phase 4: CLI Agent Mode 🔜
af --agent global flag switches all output to agent-optimized JSON. No colors, no tables, no interactive prompts.
Issue: #281 (open — follow-up work)
Route Structure
/api/v1/agentic/
├── GET /discover # API endpoint search
├── POST /query # Unified resource query
├── GET /run/:run_id # Run overview
├── GET /agent/:agent_id/summary # Agent summary
├── POST /batch # Batch operations
├── GET /status # System status
├── GET /kb/topics # Knowledge topics (public)
├── GET /kb/articles # Search articles (public)
├── GET /kb/articles/:id # Full article (public)
└── GET /kb/guide # Goal-oriented guide (public)
Plus: Smart 404 on all non-UI paths
Security Model
| Caller | Smart 404 | Discover | Query/Batch/Status | KB |
|---|---|---|---|---|
| No auth | Public endpoints only | 401 | 401 | Allowed |
| API key | Non-admin endpoints | Full | Full | Full |
| Admin | All endpoints | Full | Full | Full |
Issues
- feat: API Catalog Registry + Smart 404 Handler #275 — API Catalog + Smart 404
- feat: Agentic Discover endpoint — API search for agents #276 — Discover endpoint
- feat: Unified query endpoint for operator/autonomous agents #277 — Unified query
- feat: Run overview + Agent summary endpoints #278 — Run overview + Agent summary
- feat: Batch operations + System status endpoints #279 — Batch + Status
- feat: Knowledge Base API for builder agents #280 — Knowledge Base API
- feat: CLI --agent mode for agent-optimized output #281 — CLI --agent mode (follow-up)