AI Agent Backend Design (AQL‑Driven, Local Reasoning)

[yaredtsy]

Design the AI agent backend so agents do not consume the entire codebase or accumulate large context. Agents should query only what they need, work on one function at a time, and rely on structure and documentation instead of reading raw code by default.

This design should encourage local reasoning and step‑by‑step exploration, not one‑shot answers.

Core Principles:

• Agents should query, not read everything
• Agents should reason locally before globally
• Context should be loaded, used, and dropped
• Structure and documentation come before raw code

Requirements:

• Agents use AQL queries to fetch:
  • A single function or node
  • Its direct dependencies
  • Metadata (docs, tags, logs, ownership)
• Agents operate on one function at a time
• Agents start from a parent function and move downward through the call graph
• No “one‑shot” reasoning across many functions

Context Management:

• Context is not accumulated
• When an agent enters a function:
  • It loads only that function’s context
  • Uses documentation or description first
  • Reads code only if needed
• When the agent exits a function:
  • Context is dropped
  • Only conclusions or summaries are kept

Behavior Rules:

• Prefer docs, schemas, and contracts over raw code
• Avoid reading full implementations unless required
• Move step‑by‑step through the graph
• Explicitly state when new context is loaded or released

Acceptance Criteria:

• Agent queries are small, targeted, and traceable
• Agent never holds large global context
• Agent behavior is explainable and predictable
• System scales to large codebases without hitting context limits

Notes:
This backend design treats AI agents more like debuggers or inspectors, not omniscient solvers. Understanding should come from structure and movement, not from raw context accumulation.