React
React Native
Node.js
Python
Rust
PostgreSQL
Solana
Claude
AI Agents
Go

AI Agents Guide

Sections

AI Agent Fundamentals & Concepts

What Actually Makes Software an "Agent"?AI Agents Fundamentals Basics Agents vs Chatbots vs Assistants vs Copilots: What's the Difference Autonomy Levels: From Single-Turn Tool Calls to Fully Autonomous Agents Why "Agentic" Became the Industry's Word for 2025-2026 Core Vocabulary Every Agent Builder Should Know What an Agent Can and Can't Do Reliably Today AI Agents Fundamentals Best Practices

Inside the Agent Loop: Perceive, Reason, Act, Observe Agent Loop Basics Reasoning Traces: How Agents "Think" Before Acting Stopping Conditions: How an Agent Knows When It's Done Single-Turn vs Multi-Turn vs Long-Running Agents Why Agents Loop Forever: Debugging Runaway Agent Behavior Planning vs Reacting: Two Philosophies for Agent Decision-Making How Context Shapes Every Decision an Agent Makes Agent Loop Best Practices

The Three Core Agent Architecture Patterns, Compared Agent Architectures Basics ReAct: Reasoning and Acting in an Interleaved Loop Plan-and-Execute: Separating Planning from Execution Multi-Agent Handoff: Specialist Agents Passing Work to Each Other When to Choose ReAct vs Plan-and-Execute vs Multi-Agent Hybrid Architectures: Combining Planning, Reaction, and Delegation Common Architecture Anti-Patterns in Early Agent Projects Agent Architectures Best Practices

How an LLM's Context Window Bounds What an Agent Can Do LLMs Behind Agents Basics Major LLM Providers for Agent Building: OpenAI, Anthropic, Google, xAI Local & Self-Hosted Models with Ollama for Agent Workloads Tokens, Pricing, and Why Agent Costs Add Up Fast Function Calling & Tool Use Support Across Providers Matching Model Tier to Agent Task Complexity Why Model Choice Is a Runtime Decision, Not a One-Time One LLMs Behind Agents Best Practices

Why Fundamentals Rules Prevent Early Agent Project Failures The Core Agent Fundamentals Rules: A Quick-Reference List Scope Rules: When a Problem Actually Needs an Agent Stopping-Condition Rules Every Agent Must Implement Context Discipline Rules for Predictable Agent Behavior Model-Swapping Rules for Cost and Capability Flexibility Common Fundamentals Mistakes New Agent Builders Make AI Agent Fundamentals Rules Best Practices

Use Cases for AI Agents

The Four Broad Categories of AI Agent Use Cases Use Cases for AI Agents Basics Task Shape Matters More Than Industry When Picking a Use Case A Decision Framework: Is This Problem a Good Fit for an Agent?Where Agents Outperform Traditional Automation (and Where They Don't)Signals a Use Case Is Premature for an Agent Today Surveying 2026's Most Common Production Agent Deployments Use Cases for AI Agents Best Practices

How Coding Agents Changed Day-to-Day Software Development Coding & Developer-Tooling Use Cases Basics Code Review Agents: Automated PR Feedback at Scale Autonomous Bug-Fixing Agents: From Issue to Verified Patch Test-Generation and Coverage Agents DevOps Agents: Deployment, Incident Triage, and Runbook Execution Documentation and Onboarding Agents for Codebases Coding & Developer-Tooling Use Cases Best Practices

How Knowledge-Work Agents Differ from Coding Agents Business & Research Use Cases Basics Research Agents: Multi-Source Investigation and Synthesis Data Analysis Agents: From Spreadsheet to Insight Market & Competitive Intelligence Agents Meeting and Communication Agents: Summaries, Follow-Ups, and Drafts Internal Knowledge-Base Agents with RAG Grounding Business & Research Use Cases Best Practices

What a Personal AI Agent Actually Does Day to Day Personal & Consumer Use Cases Basics Chat-Integrated Agents: Discord, Slack, Telegram, and WhatsApp Bots Email and Calendar Agents: Triage, Drafting, and Scheduling Shell-Access Personal Agents: Power and Risk Consumer-Facing Agent Products: Shopping, Travel, and Concierge Bots Why Self-Hosting a Personal Agent Appeals to Privacy-Conscious Users Personal & Consumer Use Cases Best Practices

Why Industry Context Changes an Agent's Risk Profile Industry-Specific Use Cases Basics Financial Services Agents: Fraud Triage, Reporting, and Trading Support Healthcare Agents: Clinical Documentation and Patient Triage Support Legal Agents: Contract Review and Discovery Support E-Commerce Agents: Product Search, Support, and Merchandising Regulated-Industry Agent Checklist: Compliance, Audit, and Human Sign-Off Industry-Specific Use Cases Best Practices

OpenRouter: The Unified LLM Gateway

What OpenRouter Actually Is: One API for 300+ Models OpenRouter Fundamentals Basics How OpenRouter's Unified API Normalizes Different Providers OpenRouter vs Calling Provider APIs Directly How OpenRouter's Credit and Billing Model Works Free Models on OpenRouter: What's Available and Their Limits Bring Your Own Key (BYOK): Using Your Own Provider Accounts via OpenRouter OpenRouter's Data Policies and Why They Matter for Enterprises OpenRouter Fundamentals Best Practices

How Model Routing Actually Works Under an OpenRouter Request OpenRouter Setup & Routing Basics Authenticating and Configuring the OpenRouter Base URL Calling OpenRouter from Python and TypeScript SDKs Model Slugs and Naming Conventions on OpenRouter Switching Models by Config, Not Code: A Routing Pattern Auto-Router: Letting OpenRouter Pick the Best Model for a Prompt Streaming Responses Through OpenRouter Troubleshooting Common OpenRouter Setup Errors OpenRouter Setup & Routing Best Practices

How OpenRouter's Provider Fallback Actually Protects Uptime Cost & Fallback Basics Setting Provider Order and Routing Preferences Cost-Based Routing: Sending Cheap Tasks to Cheap Models Setting Spend Limits and Usage Caps per API Key Comparing OpenRouter's Per-Model Pricing Against Direct Provider Rates Latency-Aware Routing: Picking Providers by Response Time Data Policy Filters: Excluding Providers That Retain Prompts Monitoring OpenRouter Spend and Usage in Real Time OpenRouter Cost & Fallback Best Practices

Architecting an Agent Around a Model-Agnostic Gateway Production OpenRouter Basics Tool Calling Through OpenRouter Across Different Providers Combining OpenRouter with LangChain, CrewAI, and LlamaIndex Building a Self-Hosted Fallback Layer: Ollama + OpenRouter A/B Testing Models in Production via OpenRouter OpenRouter Rate Limits, Retries, and Backoff Strategies Case Study: Migrating a Single-Provider Agent to OpenRouter OpenRouter in Production Best Practices

Agent Frameworks & Orchestration

What Actually Differs Between Agent Frameworks Choosing a Framework Basics Framework Comparison Matrix: LangGraph, CrewAI, Microsoft Agent Framework & More Framework-Free vs Framework-Based: When to Roll Your Own POC-to-Production Migration Paths Between Frameworks Framework Lock-In Risks and How to Avoid Them Matching Team Skill Set to Framework Choice Choosing a Framework Best Practices

The LangGraph Mental Model: Agents as State Graphs LangChain & LangGraph Basics Building Your First Stateful Agent Graph Branching and Conditional Edges for Multi-Path Agents Human-in-the-Loop Approval Nodes in LangGraph Persistence and Checkpoints: Resuming a LangGraph Agent Mid-Run LangGraph 1.0's Per-Node Timeouts and v2 Streaming Observability with LangSmith for LangGraph Agents LangChain & LangGraph Best Practices

The CrewAI Mental Model: Roles, Tasks, and Crews CrewAI Basics Defining Agent Roles, Goals, and Backstories Sequential vs Hierarchical Crew Processes CrewAI 1.14's Pluggable Memory, Knowledge, and RAG Backends Building a Custom Tool for a CrewAI Agent The CrewAI Chat API for Interactive Crew Sessions Debugging a Crew That Won't Converge on an Answer CrewAI Best Practices

From AutoGen and Semantic Kernel to Microsoft Agent Framework 1.0 Microsoft Agent Framework Basics Conversational Multi-Agent Patterns: Agent-to-Agent Chat Graph-Based Workflows in Microsoft Agent Framework Enterprise Plugins and Connectors from Semantic Kernel Migrating an Existing AutoGen Project to Microsoft Agent Framework Governance and Enterprise Controls in Microsoft Agent Framework Microsoft Agent Framework Best Practices

The LlamaIndex Mental Model: Documents, Indexes, and Query Engines LlamaIndex Basics Ingesting and Chunking Documents for an Agent's Knowledge Base Building a Query Engine Agent Over Your Own Data LlamaIndex.TS for RAG-First TypeScript Applications Combining Multiple Indexes with Router Query Engines Evaluating Retrieval Quality in a LlamaIndex Pipeline LlamaIndex Best Practices

Why Structured Output Matters More as Agents Get Autonomous Pydantic AI & Instructor Basics Defining Agent Output Schemas with Pydantic Models Pydantic AI's Native Vercel AI SDK Data Stream Support Using Instructor for Schema-Constrained Outputs Across Providers Handling Validation Failures and Retry Loops Gracefully Type-Safe Tool Definitions with Pydantic AI Pydantic AI & Instructor Best Practices

What Native Provider Agent Primitives Give You Over a Framework OpenAI Agents SDK Basics Handoffs and Guardrails in the OpenAI Agents SDK Native MCP Support in the OpenAI Agents SDK Anthropic's Tool Use Primitives for Building Agents Directly Comparing OpenAI Agents SDK to Google's Agent Development Kit (ADK)When Native SDK Primitives Are Enough (and When They Aren't)OpenAI Agents SDK & Native Primitives Best Practices

The Vercel AI SDK Mental Model: Streaming UI Meets Agent Loops Vercel AI SDK Basics Tool Calling and UI Generation with the AI SDK AI SDK 6's Tool-Approval States for Human-in-the-Loop Agents Chaining, Routing, and Evaluator-Optimizer Agent Patterns Deploying an AI SDK Agent to Vercel Edge Functions Integrating Pydantic AI or LangGraph Behind an AI SDK Frontend Vercel AI SDK Best Practices

When Visual Workflow Tools Beat Writing Custom Agent Code No/Low-Code Orchestration Basics Building an AI Agent Node Workflow in n8n Connecting OpenRouter as n8n's Model Backend Zapier's AI Agent Actions for Business Process Automation From No-Code Prototype to Custom Code: A Migration Path Limitations of Visual Builders for Complex Agent Logic No/Low-Code Orchestration Best Practices

Tools, Memory & Retrieval

How Function Calling Actually Works Under the Hood Tool Use & Function Calling Basics Writing Tool Descriptions the Model Will Actually Use Correctly JSON Schema for Tool Parameters: A Reference Guide Parallel Tool Calls: When and How Models Call Multiple Tools at Once Tool Search: Loading Tool Definitions On Demand Instead of Upfront Handling Tool Errors Gracefully Inside an Agent Loop Tool Use & Function Calling Best Practices

What Makes an Internal API a Good Agent Tool Custom Tools Basics Wrapping a REST API as an Agent Tool Web Search and Browsing Tools for Research Agents Code Execution Tools: Sandboxed Python and Shell Access Database Query Tools: Read-Only vs Read-Write Access Versioning and Deprecating Agent Tools Without Breaking Agents Custom Tools Best Practices

What MCP Standardizes and Why It Won the Tool-Connection Wars Model Context Protocol Basics MCP's Three Primitives: Tools, Resources, and Prompts stdio vs HTTP vs SSE: MCP's Transport Options MCP Governance Under the Linux Foundation The MCP Server Ecosystem: 10,000+ Servers in Production MCP Tunnels: Connecting to Private-Network MCP Servers Model Context Protocol Best Practices

Anatomy of an MCP Server: Handlers, Schemas, and Transport Building & Deploying MCP Basics Building Your First MCP Server in TypeScript or Python Exposing Resources and Prompts, Not Just Tools, from an MCP Server Testing an MCP Server Against a Real Agent Client Deploying an MCP Server as a Remote HTTP Service Auth and Access Control for Remote MCP Servers Handling Large Tool Outputs: Auto-Spill to Sandbox Files Building & Deploying MCP Best Practices

Short-Term Memory: What an Agent Actually Needs Within One Run Short-Term Memory Basics Managing Conversation History Within a Context Budget Redis for Fast Short-Term Agent State Scratchpad Patterns: Letting an Agent Track Its Own Progress Summarization Strategies for Long-Running Conversations Session Isolation: Keeping One User's Agent State Separate from Another's Short-Term Memory Best Practices

How Vector Search Gives Agents a Searchable Memory Vector Databases & RAG Basics Choosing a Vector Store: Pinecone, Chroma, and pgvector Compared Building a Retrieval Tool an Agent Can Call Chunking Strategies That Affect Retrieval Quality Hybrid Search: Combining Vector Similarity with Keyword Filters Re-Ranking Retrieved Results Before Passing Them to an Agent Vector Databases & RAG Best Practices

Long-Term Memory: What Should Survive Between Agent Sessions Long-Term Memory Basics File-Based and Database-Backed Long-Term Memory Stores Memory Extraction: Deciding What's Worth Remembering Memory Retrieval: Surfacing the Right Fact at the Right Time Memory Conflicts: Handling Contradictory or Stale Saved Facts Architecture Guide: A Tiered Memory System for Production Agents Long-Term Memory Best Practices

Multi-Agent Systems & Advanced Patterns

Why Split One Agent Into Many Specialized Agents Multi-Agent Architecture Basics Orchestrator-Worker Patterns for Coordinating Specialist Agents Peer-to-Peer Agent Collaboration Without a Central Orchestrator Context Handoff: Passing State Between Agents Cleanly Avoiding Context Loss and Duplication Across Agent Handoffs Architecture Guide: Designing a Multi-Agent System's Communication Contract Multi-Agent Architecture Best Practices

What A2A Solves That MCP Doesn't Agent-to-Agent Protocols Basics Agent Cards: How Agents Advertise Their Capabilities A2A's Transport Layer: HTTP, SSE, and JSON-RPC 2.0 Cross-Cloud Agent Interoperability: Azure, Bedrock, and Google Cloud When to Adopt A2A vs Build a Custom Handoff Protocol The Broader Protocol Stack: MCP, A2A, ACP, and WebMCP Agent-to-Agent Protocols Best Practices

Privilege Rings: Scoping What an Agent Can Do Without Asking Human-in-the-Loop Basics Building an Approval Gate Before Irreversible Actions Kill Switches: Stopping a Runaway Agent Mid-Execution Designing Escalation Paths When an Agent Gets Stuck Audit Trails: Logging Every Agent Action for Later Review Common Guardrail Mistakes That Undermine Human Oversight Human-in-the-Loop Best Practices

The Self-Hosted Personal Agent Mental Model Self-Hosted Personal Agents Basics Setting Up Clawdbot/OpenClaw on a VPS or Local Machine Connecting Discord, Slack, Telegram, and WhatsApp Integrations Granting and Scoping Shell Access Safely Persistent Memory Across Restarts for a Personal Agent Email and Calendar Tool Integration for a Personal Agent Backend Flexibility: Routing a Personal Agent Through OpenRouter Self-Hosted Personal Agents Best Practices

How Vision Models Extend an Agent Beyond Text Multi-Modal & Browser Agents Basics Building a Browser-Controlling Agent with Playwright Vision-Grounded Actions: Clicking What the Model Actually Sees Handling Dynamic Pages, Popups, and Login Flows in Browser Agents Managed Browser Agent Platforms vs Self-Hosted Playwright Combining Vision and Tool Use for Document-Processing Agents Multi-Modal & Browser Agents Best Practices

Why On-Chain Agents Need Different Guardrails Than Other Tools Blockchain & On-Chain Agents Basics Setting Up @solana/web3.js and @solana/spl-token for Agent Tools Building transferSOL and createTransaction Agent Tools Solana Pay: Verifying Payments via Webhook or Polling Idempotency and Double-Spend Protection for On-Chain Agent Actions Key Management for Agent-Controlled Wallets: Fireblocks and Alternatives Testing On-Chain Agent Flows on Devnet Before Mainnet Blockchain & On-Chain Agents Best Practices

Security, Reliability & Observability

The Principle of Least Privilege Applied to Agent Tools Agent Security Basics Containerized Sandboxes for Code-Executing Agent Tools Scoping API Keys and Credentials Passed to an Agent Never Grant Blanket Shell Access in Production: What to Do Instead Network Egress Controls for Agents That Call External Tools Security Checklist Before Shipping an Agent to Production Agent Security Best Practices

How Prompt Injection Attacks Actually Work Prompt Injection & Guardrails Basics Isolating Untrusted Content from Trusted Instructions Output Validation with Pydantic and Zod Against Malicious Content Guardrail Libraries and Content-Filtering Layers for Agents Red-Teaming Your Own Agent for Injection Vulnerabilities Detecting and Logging Suspected Injection Attempts Prompt Injection & Guardrails Best Practices

What Agent Observability Actually Needs to Capture Agent Observability Basics LangSmith for LangChain/LangGraph-Native Tracing Langfuse: OpenTelemetry-Based Tracing for Any Framework Arize Phoenix for Eval-Rigorous Agent Monitoring Building Custom Trace Logging Without a Third-Party Platform Pairing Agent Observability with Infrastructure Monitoring Agent Observability Best Practices

Why Agents Fail Differently Than Traditional Services Reliability Engineering Basics Circuit Breakers for Agent Tool Calls Fallback Chains: Degrading Gracefully When a Model or Tool Fails Setting SLOs for Agent Latency, Success Rate, and Cost Timeout Strategies for Long-Running Agent Steps Postmortems for Agent Incidents: A Template Reliability Engineering Best Practices

Why Testing an Agent Differs from Testing Deterministic Code Testing AI Agents Basics Unit Testing Individual Agent Tools Simulating Full Agent Loops in a Test Harness Building a Gold-Set Eval Suite for Agent Quality LLM-as-Judge: Scoring Agent Output Automatically Regression Testing an Agent After a Model or Prompt Change Testing AI Agents Best Practices

Deployment, Scaling & Production Operations

Choosing a Deployment Target for an Agent Workload Deploying Agents Basics Containerizing an Agent with Docker Deploying an Agent to Vercel or AWS Lambda Serverless Functions Long-Running Agents on a VPS: Process Management and Restarts Cold Starts and Long-Running Agent Loops: A Serverless Mismatch Environment and Secrets Management Across Deployment Targets Deploying Agents Best Practices

What Actually Bottlenecks an Agent System at Scale Scaling Agent Systems Basics Queueing Agent Jobs with Celery or a Message Broker Concurrency Limits and Backpressure for Agent Workers Cost-Aware Scaling: Routing Load to Cheaper Models Under Pressure Caching Agent Responses and Tool Results to Cut Redundant Calls Architecture Guide: A Horizontally Scalable Agent Worker Pool Scaling Agent Systems Best Practices

What "Continuous Deployment" Means for a Prompt-Driven System CI/CD & Agent Lifecycle Basics Versioning Prompts and Tool Schemas Alongside Code Running Eval Suites as a CI Gate Before Deploy Canary and Shadow Deployments for Agent Updates Feature-Flagging Agent Behavior Changes Rollback Strategies When a Deployed Agent Regresses CI/CD & Agent Lifecycle Best Practices

Why Some Teams Build a Custom Agent Runtime Instead of Adopting a Framework Custom Agent Runtimes Basics Designing a ReAct Loop from Scratch in FastAPI or Express Building an Eval Harness for a Custom Runtime Circuit Breakers and Observability Without a Third-Party Framework Plugin Architecture for Tools in a Custom Runtime When a Custom Runtime Stops Being Worth Maintaining Custom Agent Runtimes Best Practices

Tech-Lead Craft, Case Studies & Team Practices

Why Agent Systems Need Their Own ADR Discipline Architecture Decisions Basics An ADR Template for Agent Framework Selection Trade-off Guide: Single Agent vs Multi-Agent Architecture Trade-off Guide: Managed Gateway vs Direct Provider Integration Documenting Model and Provider Decisions for Future Migrations Revisiting Old Agent Architecture Decisions as the Field Moves Architecture Decisions Best Practices

What a Case Study Should Capture for Future Reference Case Studies Basics Case Study: Building a Customer-Support Agent with RAG and Escalation Case Study: A Code-Review Agent Wired into GitHub CI Case Study: A Self-Hosted Personal Agent with Multi-Platform Chat Integration Case Study: A Multi-Agent Research Pipeline with Citation Verification Before-and-After Case Study: Cutting an Agent's Cost by Switching to OpenRouter Routing Case Studies Best Practices

How Opinionated Rules Prevent Agent Production Incidents The Core Agent Rules: A Quick-Reference List Model and Provider Rules: Routing, Fallback, and Cost Discipline Tool Design Rules for Safe, Composable Agents Security Guardrail Rules Every Tech Lead Should Enforce Observability and Eval Rules for Production Agent Systems Team Rules for Reviewing and Approving Agent Changes AI Agent Rules Best Practices

Why Agent Teams Still Need Solid Git and Linux Fundamentals Git & Linux Basics for Agent Developers Git Workflows for Prompt, Tool, and Config Changes Linux CLI Essentials for Debugging Agent Processes Onboarding a New Developer to an Agent Codebase Documenting Agent-Specific Conventions for New Team Members Common Git Conflicts in Prompt and Config Files Git, Linux CLI & Team Onboarding Best Practices

/

/

© 2026 @csjcode|SystemsArchitect.io: Cloud Systems Tools|Terms

An independent, unofficial educational resource. Not affiliated with, endorsed, or sponsored by the brand/trademark maintainers/owners.

Search Documentation

Search across all documentation pages

AI Agents/Architecture Decisions

Architecture Decisions

8 pages in this section.

1

Why Agent Systems Need Their Own ADR Discipline

Explains why fast-moving framework and model choices demand documented, revisitable decisions.

Python Architecture Decisions Explainer Adr

2

Architecture Decisions Basics

A first ADR documenting a small framework choice and its rationale.

Python Architecture Decisions Basics Adr

3

An ADR Template for Agent Framework Selection

A ready-to-use ADR template capturing framework trade-offs and the decision made.

Python Architecture Decisions List Cheatsheet

4

Trade-off Guide: Single Agent vs Multi-Agent Architecture

Python Architecture Decisions Advanced Multi Agent

5

Trade-off Guide: Managed Gateway vs Direct Provider Integration

Weighs OpenRouter-style gateway convenience against direct provider integration control.

Python Architecture Decisions Trade Off Openrouter

6

Documenting Model and Provider Decisions for Future Migrations

Python Architecture Decisions Advanced Models

7

Revisiting Old Agent Architecture Decisions as the Field Moves

Covers scheduling periodic ADR reviews given how fast agent tooling changes.

Python Architecture Decisions List Ranked Decision

8

Architecture Decisions Best Practices

Ten practices for documenting and revisiting agent architecture decisions over time.

Python Architecture Decisions Best Practices List