Basic Agent + Tools
A single AI agent wired to external tools — calendar, email, contacts, memory. The agent plans multi-step tasks autonomously using these tools. The simplest useful agent architecture.
▶ Build it — Gemini Executive Assistant · 10 min| Component | Role | Notes |
|---|---|---|
| Trigger | Entry point for user input or event | Chat, webhook, cron, or UI event |
| AI Agent | Reasons, selects tools, chains calls | Runs a plan-execute-observe loop internally |
| Memory | Injects past context into prompts | Vector or key-value; scoped per user |
| Tool Set | Structured APIs the agent can call | Each tool = function signature + description |
Strengths
- Dead simple to build and debug
- Works well for single-domain tasks
- Predictable token budget
- Easy to add tools incrementally
Limitations
- Bottleneck — one agent, no parallelism
- Context window fills fast with many tools
- No fallback if agent loops or fails
- Doesn't scale to complex workflows
Best For
- Personal assistants (email, calendar)
- Single-domain Q&A with lookups
- Prototypes and MVPs
- Tasks needing 2–5 tool calls max
Complexity
Implementation effort:
Operational complexity:
Agent + MCP Servers
Instead of hard-coded tool functions, the agent connects to MCP (Model Context Protocol) servers — standardized sidecars that expose tools from any service. The agent discovers and calls tools dynamically at runtime.
▶ Build it — AI PM Agent · 15 minWebhook
| Without MCP | With MCP |
|---|---|
| Tools hard-coded as functions in prompt | Tools discovered dynamically from servers |
| Each tool needs custom integration code | Servers implement standard protocol |
| Tool list is fixed at build time | Tool list extends at runtime |
| Limited to your API integrations | Access any MCP-compatible service |
MCP Server = Sidecar Process
- Runs alongside your app
- Exposes tools via standard protocol
- Handles auth to external services
- Stateless or stateful (your choice)
Agent ↔ Server Contract
- Agent calls
tools/listto discover - Agent calls
tools/callto execute - Server returns structured results
- Agent decides next action
Strengths
- Extensible — add servers without code changes
- Ecosystem of pre-built integrations
- Separation of agent logic and tool impl
- Servers can be swapped independently
Limitations
- Runtime dependency on external processes
- More infrastructure to manage
- Latency overhead per tool call
- Debugging spans multiple processes
Agent + Router
The agent acts as an AI traffic controller — it classifies the incoming request and dispatches it to the appropriate downstream workflow or webhook. Decision logic lives in the model, not in code.
| Strategy | How It Works | Best For |
|---|---|---|
| Intent Classification | Model classifies input into predefined categories | Support routing, FAQ triage |
| Entity Extraction | Pull key entities; route based on entity type/value | Multi-tenant apps, data pipelines |
| Confidence Threshold | High confidence → auto-route; low → human review | Automation with safety net |
| Semantic Similarity | Embed input; nearest neighbor to route definitions | Open-ended input spaces |
Strengths
- Routes complex natural language inputs
- Single decision point — easy to monitor
- Routes are swappable without model change
- Works well with n8n / Make / Zapier backends
Limitations
- Routing errors cascade — misclassify = wrong path
- Hard to test all edge cases
- Model must know all route options upfront
- No graceful degradation without fallback
Human in the Loop + Tools
The agent plans and prepares actions, but pauses at defined checkpoints for human approval before executing. Critical for high-stakes operations where errors have real cost.
▶ Build it — AI Scheduling Executive Assistant · 20 min| Pattern | Trigger Condition | Human Action |
|---|---|---|
| Always-Ask | Every execution | Approve / reject / edit |
| Threshold-Based | Action exceeds risk/cost threshold | Approve high-stakes only |
| Sampling | Random % of executions | Audit trail, quality checks |
| Uncertainty-Triggered | Model confidence below threshold | Clarify ambiguous inputs |
| First-Time | Novel entity / action type | Establish precedent |
Strengths
- Prevents costly irreversible mistakes
- Builds operator trust in automation
- Creates audit log of human decisions
- Graceful degradation when AI is uncertain
Limitations
- Approval latency breaks async flows
- Human bottleneck reduces throughput
- Approval fatigue leads to rubber-stamping
- Needs reliable async notification system
Sequential Agents
Multiple specialized agents wired in series — each agent handles one concern, passes its output to the next. Like an assembly line: each stage transforms the data before handing off.
▶ Build it — Sequential AI Agent Pipeline · 10 min| Stage | Responsibility | Input | Output |
|---|---|---|---|
| Loop / Iterator | Fan out over list of items | Array of items | Single item per iteration |
| Planner Agent | Analyze, decompose, create plan | Raw item + context | Structured plan / review |
| Executor Agent | Carry out the plan | Plan from prior stage | Action result / artifact |
| Writer / Sink | Persist result to target system | Final artifact | Confirmation / ID |
Strengths
- Each stage is focused and testable
- Earlier stages can gate / validate before cost
- Easy to insert/remove stages
- Clear data contracts between agents
Limitations
- Latency = sum of all stage latencies
- Errors in early stages corrupt all downstream
- Context from stage 1 may be lost by stage 3
- No parallelism within a chain
Parallel Agent Execution
A coordinator agent fans out subtasks to multiple specialized agents running concurrently. Results are merged by an aggregator. Dramatically reduces wall-clock time on decomposable tasks.
▶ Build it — Parallel AI Agent Pipeline · 20 minAggregate
| Concern | Issue | Mitigation |
|---|---|---|
| Rate Limits | Parallel calls exhaust API quotas | Semaphore / token bucket |
| Partial Failures | One branch fails, others succeed | Fan-out with fallback per branch |
| Result Ordering | Branches return out of order | Tag results with branch ID before merge |
| Context Isolation | Branches share stale context | Pass immutable snapshot per branch |
Strengths
- Wall-clock time ≈ slowest branch (not sum)
- Independent branches are fault-isolated
- Scales naturally to more parallel tasks
- Great for I/O-bound workloads
Limitations
- Aggregation logic can be complex
- Cost = sum of all branch costs
- Not suitable for tasks with dependencies
- Debugging requires distributed tracing
Dynamic Agent — Sub-Agent Orchestrator
A main orchestrating agent dynamically decides it needs help and spawns specialized sub-agents. Unlike parallel execution, the orchestrator is adaptive — sub-agent selection is a runtime decision, not a static fan-out.
▶ Build it — Sub-Agent Orchestrator · 20 min| Parallel Execution | Orchestrator | |
|---|---|---|
| Fan-out Decision | Static — defined at build time | Dynamic — decided at runtime |
| Sub-agent Selection | All branches always run | Only needed sub-agents spawn |
| Inter-Agent Comms | None (isolated branches) | Orchestrator can relay context between subs |
| Complexity | Medium | High — orchestrator needs clear sub-agent specs |
| Cost Efficiency | Pays for all branches | Only pays for needed subs |
Strengths
- Handles highly variable task complexity
- Sub-agents are independently versioned
- Orchestrator can retry with different sub-agents
- Cleanest model for deep specialization
Limitations
- Orchestrator is a central point of failure
- Spawning latency adds up at scale
- Hard to predict total cost upfront
- Requires careful sub-agent interface design
Naïve RAG
The user's query is passed directly as the retrieval query — no reformulation. Simple, fast, and effective for straightforward lookups when queries are already well-formed.
| Stage | Component | Key Decision |
|---|---|---|
| Embed Query | Embedding model (same as index) | Must match index embedding model exactly |
| Retrieve | Vector store (Pinecone, Weaviate, pgvector) | Top-k value; similarity threshold |
| Aggregate | Re-ranker or simple concatenation | Order matters — best chunks first |
| Generate | LLM with context window | System prompt quality determines answer quality |
Strengths
- Minimal latency — no query rewrite step
- Predictable and debuggable
- Works well for keyword-rich queries
- Easy baseline to beat
Limitations
- Fails on vague or ambiguous queries
- Poor on multi-hop questions
- Query embedding ≠ document embedding style
- No query expansion or reformulation
Smarter RAG
An agent first decides whether retrieval is even needed. If yes, it formulates an optimized retrieval query separate from the user's raw input. Produces significantly better results on complex or ambiguous questions.
1. Retrieval Gate
Agent first asks: "Do I need external knowledge?" If the model's parametric knowledge suffices, it answers directly — saving a full retrieval round-trip and avoiding context pollution.
2. Query Reformulation
Instead of embedding the user's raw question, the model generates a retrieval-optimized query — typically more specific, keyword-rich, and aligned with how documents are written.
Strengths
- Higher answer quality on complex questions
- Avoids retrieval when not needed (saves cost)
- Handles ambiguous / conversational queries
- Can do multi-hop query expansion
Limitations
- One extra LLM call per request
- Reformulation can hallucinate query terms
- More complex to evaluate and debug
- Gate calibration requires tuning
Vector Indexing Pipeline
An event-driven pipeline that automatically embeds and indexes documents whenever they're added or modified. The RAG patterns above depend on this pipeline to have fresh, queryable knowledge.
| Strategy | How | Best For |
|---|---|---|
| Fixed Size | Split every N tokens with overlap | Homogeneous prose documents |
| Sentence / Paragraph | Split on sentence/paragraph boundaries | Narrative text, articles |
| Semantic | Embed then split on similarity drops | Mixed-topic documents |
| Hierarchical | Index full doc + child chunks | Long docs with structure (papers, books) |
| By Section | Use headings / metadata as boundaries | Structured docs (wikis, docs sites) |
Triggers
- Webhook on file create/update/delete
- Scheduled full re-index
- Manual trigger for bulk imports
Metadata to Store Per Chunk
- Source doc ID + URL
- Chunk index within doc
- Created / modified timestamps
- Access control tags (for RBAC)