Scalable Design of Agent

Functional Requirements

1. Understand the intent from the user's conversation.
2. Break the intent into a series of steps needed to achieve it.
3. Build an execution path for those steps, including ordering and dependencies.
4. Enforce authentication and authorisation before any agent logic runs. Every request must pass identity verification (JWT / OAuth2), role-based access control (RBAC), and session binding so the authenticated identity carries across all downstream calls. Unauthenticated requests are rejected at this layer.
5. Human in the loop (HITL) before execution. The user must be able to review the plan, request changes, or reject it before the agent acts.
6. Confirm the task operation flow via chain-of-thought reasoning. Once the plan is approved, break it into tasks and validate the sequence with the user. (TODO: Research reasoning models — distinguish the model's internal CoT from the agent's explicit task graph, and how to surface steps for HITL review.)
7. Extract entity models and data from the conversation. Outputs must conform to canonical schemas (Pydantic or Zod) so extraction is consistent across turns and execution plans are reliable.
8. Execute the confirmed task plan and report completion to the user.

Non-Functional Requirements

1. Async IO for all LLM calls, with exponential backoff on transient failures.
2. HITL looping. Support iterative review cycles, including the ability to reject a plan and return to the planning stage. (TODO: paste Claude diagram reference.)
3. Parallel and series task detection. The task router identifies independent tasks (fan out in parallel) and dependent tasks (run in sequence).
4. Active context window management. If the conversation risks hitting the context limit (TODO: confirm — 128k or higher depending on model), use subagents. Before evicting content, summarise the evicted portion and inject it as a system message so no history or entity state is lost.
5. Sliding window as an alternative. Use a sliding window when task state is small and linear; use subagents when tasks are independent and parallelisable. Evaluate both before committing.
6. Fan-out and pub/sub for scale. The async executor fans out to parallel tasks and uses pub/sub for event-driven coordination.
7. Explicit failure handling. Exhausted retries go to a dead-letter queue (DLQ). Timeout policies are defined per task type. Repeated failures escalate to HITL rather than dropping silently.
8. Prompt injection protection. The security layer must cover:
9. Input sanitisation: escape user content before injecting into prompts.
10. Privilege separation: user input never reaches the system prompt directly.
11. Output validation: all LLM outputs are untrusted until validated, including tool-call responses.
12. Guard model classifier: a fast pre-check on inputs before the main agent runs.
13. Prompt versioning and promotion. Use a three-stage model: dev → staging → prod. Each stage has its own eval suite. Promotion requires passing evals at the current stage, giving a clear rollback path for any regression.
14. Observability from day one. Every LLM call emits structured traces (OpenTelemetry or equivalent) covering input, output, latency, model, and token count. Retrofitting tracing later breaks the eval feedback loop.
15. Multi-turn session identity. Conversation history, entity state, and the task graph are tied to a persistent user identity so the agent can resume interrupted intents across sessions.

Scope: Stretch

How to detect when the agent has underperformed in production, and feed that back into development:

1. Eval suite per environment. Dev, staging, and prod each have an eval suite. Prod traces are continuously scored to catch regressions early.
2. Failure detection. The guard model classifier and output validator flag suspect interactions for human review.
3. Prod → dev feedback loop. Flagged interactions become new eval cases in dev. Prompt fixes are iterated in dev, pass staging evals, and are promoted via the versioned prompt registry.
4. Reasoning model research. Investigate how reasoning models handle internal chain-of-thought versus the agent's explicit task graph, and how to surface steps for HITL review.
5. Entity schema layer. Canonical Pydantic / Zod models for all entities extracted from conversation.
6. Context summarisation. Before evicting window content, summarise the block and re-inject as a compressed system message to preserve intent fidelity over long conversations.