Design phase → build phase

PADDLE Design Methodology

AI Agent Use-Case Design Architecture

Complete P → A → D → D → L → E on paper, in sequence, before writing any code. Each section becomes one file in the codebase, so the design document maps directly onto what gets built. LangChain · LangGraph · MCP · FastAPI · Docker · AWS.

Fill PADDLE in the app Fillable template (DOCX)

Problem Definition

What must the agent accomplish?

Problem statement in 1–2 sentences
Affected users and roles
Why the current approach fails
Measurable success criterion
One-sentence agent goal, approved by the stakeholder

Output

Agent goal

one sentence · approved

Action Space

What can the agent do?

Tool inventory — one row per tool
Inputs, outputs and return types
READ vs WRITE classification
Human-in-the-loop approval for write actions
Minimum viable tool set first

Output

Tool inventory

tools.py · @tool functions

Data & Knowledge

What data does the agent access?

Structured: SQL tables via asyncpg / SQLAlchemy
Unstructured: RAG — loader → splitter → embeddings → vector store
Real-time: APIs
Privacy, PII masking and RBAC
Volume and size estimates

Output

Data map + RAG index

database.py · vector store

Decision Logic

How does the graph flow?

Nodes: LLM, tool, condition, end
Edges and conditional routing
START → agent → tools (loop) → validate → END
Max iterations and graceful fallback
Sketch the graph on paper first

Output

Agent graph

graph.py · StateGraph

Loop & State

What does the agent remember?

AgentState TypedDict fields with types and defaults
messages with add_messages reducer
Short-term vs long-term memory
Checkpointer: MemorySaver (dev) → PostgresSaver (prod)
thread_id per session; interrupt_before for writes

Output

AgentState schema

TypedDict · checkpointer

Evaluation Criteria

How do you measure success?

Accuracy, latency (P95), cost, reliability, satisfaction
Test set: 10–50 Q&A pairs with ground truth
Unit, integration, end-to-end and adversarial tests
LangSmith traces from day 1; CloudWatch alerts
User feedback mechanism

Output

Test set + metrics

tests/ · LangSmith traces

Annex A (v1.1)

Scalability, LLM cost & hosting

Your design is reviewed on whether the agent can actually be operated, not just demonstrated in a notebook. Show the assumption and the formula behind every number; take token counts from real LangSmith traces.

A1 — Expected load
A2 — LLM cost estimate: (input × price + output × price) ÷ 1,000,000
A3 — Hosting estimate, component by component
A4 — Scalability plan and the single biggest bottleneck
A5 — Deployment plan: Docker → CI → environments → secrets → rollback

Review

How your design is scored

Every section is scored 0–5. Progress = checklist items ticked ÷ 39. Quality = total section score ÷ 35. A section scores at most 2 if any hint text is left unreplaced.

1. Progress
Sections completed and checklists ticked (39 items).
2. Strong areas
What is well designed and should be kept.
3. Weak points
Vague, missing, inconsistent or unrealistic items.
4. Agent performance
Accuracy, latency, reliability targets, test set and safety limits (Section E).
5. Product scalability
Can the design go from 10 to 1,000 users without a rewrite (Annex A).
6. Cost
LLM cost per request and per month, plus hosting cost (Annex A).

Verdicts: Approved · Approved with changes · Revise and resubmit · Rework scope.

Build phase

Ready to build — first files, in order

Design reviewed and signed off by Designer/Developer, Technical Lead and Stakeholder — then open the IDE.

config.py

Settings & keys

database.py

D · Data & Knowledge

tools.py

A · Action Space

graph.py

D · Decision + L · State

main.py

FastAPI entry point

tests/

E · Evaluation

Templates & documents

File name for submissions: PADDLE_<YourName>_<AgentName>_v1.docx