# Practices for Embedding AI Agents in Software # Eval Harness 🎯 The Hook Changed a prompt and quality silently dropped. The provider updated the model and accuracy drifted. You found out from user complaints. An eval harness catches these before deployment. 🔥 The Problem AI agents are probabilistic -- deterministic unit tests don't apply. Hallucinations can't be caught by spot-checking individual outputs. LLM drift (quality shifts from provider-side model updates) happens even when your team changes nothing. Without an eval harness, quality degradation surfaces only as production incidents and user complaints. 💡 The Pattern Build an evaluation pipeline combining golden datasets (input + expected output pairs) with automated eval functions (exact match, LLM-as-Judge, custom metrics). Run regression detection in CI on every prompt, model, or code change. Schedule periodic runs (daily to weekly) even without changes to catch LLM drift. Evaluation operates at three layers: offline (pre-deploy batch), online (production sampling), and shadow (A/B comparison). Regression gate thresholds are category-specific, with zero-tolerance for safety category degradation. ✅ When to Use Use when: - The agent handles production traffic with ongoing prompt, model, or code changes - Quantitative quality evidence is required (SLA compliance, regulatory reporting) - Domain experts can create and maintain golden datasets Don't use when: - Prototype stage where prompts change drastically daily - Output is creative generation (fiction, poetry) where "correct" is hard to define - Downstream deterministic validation already auto-corrects errors ⚠️ Pitfalls - Golden data rots. When product specs change, outdated expected outputs flag correct results as regressions. Assign owners and last-updated dates, and schedule regular reviews - LLM-as-Judge is also probabilistic. Even at temperature 0, scores can vary. For critical cases, use majority vote across 3 runs - Define when baseline scores are updated (e.g., after successful deploy). Without explicit update triggers, degradation becomes invisible 🔧 Implementation Approach - Structure golden datasets with category, eval function name, and expected keywords per case, enabling category-level aggregation and regression detection - Operate the eval pipeline at three layers: offline (pre-deploy batch in CI), online (production sampling), and shadow (A/B comparison of old vs. new) - Set regression gates as relative comparisons against baseline scores -- zero tolerance for safety categories, roughly 2% degradation threshold for general categories - In shadow mode, dry-run any side-effecting tool calls; in canary deploys, use sticky sessions to keep users on the same version - Assign owners and last-updated dates to golden data to prevent rot from spec changes, with scheduled periodic reviews #AIAgents# #SoftwareArchitecture#

Practices for embedding AI agents into enterprise systems [Feedback Flywheel] 💡 Is your agent "deploy and forget"? You need a mechanism to channel production user feedback into a continuous improvement cycle. This pattern systematically collects user feedback, converts it into eval datasets, and drives ongoing quality improvement. 🔥 Problems it solves - No post-deployment quality improvement cycle exists - Quality degradation from model changes, data drift, or new query patterns goes undetected - No data to prioritize which problems to fix first 🏗️ Proposed pattern Collect both implicit signals (retries, abandonment, manual corrections) and explicit signals (thumbs up/down, text feedback, human escalations). Convert low-rated and escalated cases into eval datasets and add them to regression tests. Prioritize improvements by frequency and severity of negative feedback, then apply fixes to prompts, tools, routing, or RAG. Validate all changes through eval gates before redeployment. Since reviewing every interaction is impossible, start by sampling 100% of negative cases and 5-10% of successful ones, then adjust based on measured review capacity and improvement yield. ✅ Selection criteria - Good fit: Every production agent intended for ongoing operation - Not a fit: Throwaway experiments or PoCs ⚠️ Pitfalls - Ignoring implicit signals means you miss quality degradation that users never explicitly complain about - Without an operational process connecting collected feedback to improvement actions, data piles up with no impact - Failing to update golden datasets causes eval gates to become stale and miss new failure patterns 🛠️ Implementation Approach 1. Collect feedback via in-app UI and Slack reactions (thumbs up/down), and automatically detect implicit signals (retries, abandonment, manual corrections) as trackable events 2. Build a pipeline that automatically converts low-rated and escalated cases into eval datasets and adds them to the regression test suite 3. Create a dashboard that visualizes improvement priorities by frequency and severity of negative feedback (start with 100% of negative cases and 5-10% of successful ones as the sampling baseline) 4. Validate all prompt, tool, and routing changes through eval gates (P26) to confirm no quality regression before redeployment 5. Set up an A/B testing infrastructure combining LLM-as-judge automated evaluation with human review to quantitatively measure improvement impact #AIAgents# #EnterpriseArchitecture#

Practices for embedding AI agents into enterprise systems [Prompt Supply Chain Management] 💡 Has a "quiet prompt tweak" ever changed production behavior unexpectedly? This pattern treats prompts as code artifacts -- versioned, reviewed, signed, and eval-gated before deployment. 🔥 Problems it solves - Prompt changes cannot be tracked or reviewed, making it impossible to identify the cause of quality regressions - External inputs injected into prompt templates cause unintended behavior - No way to trace which prompt version produced a given result, destroying reproducibility 🏗️ Proposed pattern Manage prompts in Git with a dedicated registry. Require pull requests and code reviews for every change. Mandate eval gate passage on each update, automatically running quality checks against a golden dataset. Sign production-deployed prompts for tamper detection. Apply injection countermeasures -- delimiters, sanitization, and least-privilege scoping -- to all template variable insertion points. In essence, apply the same CI/CD quality process used for software to your prompts. ✅ Selection criteria - Good fit: Production agents with multiple contributors - Not a fit: Throwaway experiments or PoCs (governance overhead is not justified) ⚠️ Pitfalls - Without a culture that treats prompt changes as seriously as code changes, the process becomes hollow - Skipping signing and tamper detection leaves malicious or accidental changes undetectable - Failing to continuously update the golden dataset means new failure patterns slip through unnoticed 🛠️ Implementation Approach 1. Manage prompts, system instructions, and templates in a Git repository, requiring pull requests and code reviews for every change 2. Integrate an eval gate into the CI/CD pipeline to automatically run quality checks against a golden dataset on every prompt change 3. Sign production-deployed prompts with HMAC or similar mechanisms and verify integrity at deploy time for tamper detection 4. Implement injection countermeasures for external inputs in template variables -- delimiters, sanitization, and least-privilege scoping 5. Centralize version and deployment history in a prompt registry, enabling instant rollback when issues are detected in production #AIAgents# #EnterpriseArchitecture#

# Practices for Embedding AI Agents in Software # Short DB Transaction, Long Agent Session 🎯 The Hook Holding a database transaction open while the LLM thinks for 30 seconds? Your connection pool will starve and the entire system grinds to a halt. Separate the long session from the short transaction. 🔥 The Problem Traditional web apps finish request processing in milliseconds, so request-scoped transactions work fine. AI agents are different -- LLM calls take seconds to minutes. Keeping a transaction open during inference causes connection pool exhaustion, deadlocks, lock contention, and transaction timeouts. With P99 latency often several times P50, designs that work "on average" fail at the tail. 💡 The Pattern Never hold a transaction or database connection during LLM inference. Read data in a short transaction, commit and release the connection, call the LLM, then write results in a new short transaction. Intermediate state between steps is persisted to an external state store (Redis, DynamoDB, or a session table). Use optimistic locking (version columns) to handle data races during inference -- never hold pessimistic locks across LLM calls. This reduces required connection pool size to roughly 10-20% of concurrent sessions. ✅ When to Use Use when: - The agent reads from and writes to a database around LLM calls - LLM call latency exceeds roughly 1 second (most LLM calls qualify) - Concurrent session count may reach half the connection pool size Don't use when: - Traditional CRUD processing with no LLM involvement - Operations that must complete atomically in a single transaction (e.g., bank transfers) ⚠️ Pitfalls - Between read and write, another process may update the same row. Always use optimistic locking (version column or updated_at check) - Size your connection pool for concurrent transaction steps, not concurrent sessions. This pattern dramatically reduces the required pool size - For sessions involving irreversible operations, choose a state store with disk persistence over purely in-memory stores 🔧 Implementation Approach - Follow the sequence: short read transaction, commit, release connection, LLM call, re-acquire connection, short write transaction -- never hold transactions or connections during inference - Include optimistic locking (version column or updated_at) in write transactions to handle data races during LLM inference via retry - Persist intermediate state between steps in an external state store (Redis, DynamoDB, or RDB session table) to enable recovery after crashes - Size connection pools for concurrent transaction steps, not concurrent sessions -- typically 10-20% of concurrent session count suffices - For sessions involving irreversible operations, select a state store with disk persistence to meet durability requirements #AIAgents# #SoftwareArchitecture#

Practices for embedding AI agents into enterprise systems [Agent Registry / Internal Marketplace] 💡 Are similar agents proliferating across your organization with no coordination? This pattern catalogs all enterprise agents, tools, and skills to enable discovery, reuse, and centralized governance. 🔥 Problems it solves - Teams independently build similar agents, fragmenting resources and effort - Agents without proper eval or testing make it into production - Agents become unmaintained after their developer transfers to another team - No visibility into which agents hold what permissions and access what data 🏗️ Proposed pattern Attach metadata to each agent -- owner, target department, required permissions, eval results, cost history, SLA, and version -- and register them in a ServiceNow or Backstage-style service catalog. Enforce governance through request-and-approval workflows, and require eval gate passage before any new agent goes live. Track change history via versioning, and manage retirement through a staged lifecycle: deprecation, dependent notification, then shutdown. ✅ Selection criteria - Good fit: Organizations where agents are proliferating and duplicate development or orphaned agents are becoming a problem - Not a fit: Early stages with only a handful of agents (registry overhead is not justified) ⚠️ Pitfalls - Making registry enrollment optional leads to an empty catalog; embed it in the CI/CD pipeline to enforce compliance - Neglecting metadata freshness erodes trust in the catalog - Deleting agents without a deprecation process will break downstream agents and workflows without warning 🛠️ Implementation Approach 1. Leverage a service catalog platform (ServiceNow / Backstage) to centrally register metadata for every agent -- owner, target department, permissions, eval results, cost, and SLA 2. Embed registry enrollment into the CI/CD pipeline so that unregistered agents are automatically blocked from deployment 3. Require eval gate passage before any new agent goes live, preventing agents that fail quality standards from reaching production 4. Introduce versioning and change-history tracking so that every modification is auditable -- who changed what and when 5. Automate the retirement lifecycle (deprecation flag, dependent notification, grace period, shutdown) to prevent cascading failures from abrupt removal #AIAgents# #EnterpriseArchitecture#

# Practices for Embedding AI Agents in Software # Verified Structured Output 🎯 The Hook Feeding raw LLM output into downstream systems? Broken JSON, invalid values, missing fields -- things fail silently until they become production incidents. Two-layer verification stops this. 🔥 The Problem LLM output is inherently ambiguous natural language. When downstream code expects strict types and fields, parse failures, type errors, and invalid values silently corrupt processing. Even when the format is correct, business rule violations like future dates in the past or nonexistent product IDs slip through syntax checks undetected. 💡 The Pattern Enforce structure in two layers. Layer 1 (schema validation) uses response_format or function_calling to constrain output to a JSON Schema. Layer 2 (semantic validation) applies deterministic code to verify business rules -- date ranges, ID existence, permission checks. On failure, error details are fed back into context for self-correction retry (1-3 attempts). If retries exhaust the budget, fail-fast explicitly rather than passing bad data downstream. Temperature is set to 0.0-0.3 for high schema compliance. ✅ When to Use Use when: - LLM output is consumed by downstream code, APIs, or databases - A target schema (types, required fields, value ranges) can be defined - Invalid output causes real business impact in downstream processing Don't use when: - Output is free-form text (summaries, conversations) with no structural requirements - The output schema changes so frequently that maintenance cost exceeds benefit - Invalid output can simply be discarded with no consequence ⚠️ Pitfalls - Appending full error messages on each retry inflates token consumption. Pass only the latest error or a summary - Schemas with too many fields (roughly 15+) reduce LLM compliance rates. Consider splitting into multiple calls - response_format is provider-specific. Manage schema definitions in a portable format like Pydantic or JSON Schema 🔧 Implementation Approach - Layer 1 (schema validation) uses response_format or function_calling to enforce JSON Schema compliance, with Pydantic models for type and value range constraints - Layer 2 (semantic validation) applies deterministic code to verify domain constraints such as date ranges, ID existence, and permissions - On validation failure, feed error details back into context for self-correction retry, with a budget of 1-3 attempts before fail-fast - Set LLM temperature to 0.0-0.3 to maximize structured output compliance rates - Manage schema definitions in a provider-agnostic format (Pydantic, JSON Schema) to ensure portability across LLM providers #AIAgents# #SoftwareArchitecture#

Practices for embedding AI agents into enterprise systems [Department-Scoped Agent] 💡 Is your sales question being answered with IT department knowledge? This pattern defines agent scope along organizational boundaries, naturally separating permissions, knowledge, and tone. 🔥 Problems it solves - Cannot reflect department-specific data access permissions and domain knowledge in agents - Agent ownership and accountability boundaries become unclear - Sales jargon, IT terminology, and HR policies get mixed together - Knowledge scattered across Slack, docs, and tickets becomes inaccessible when projects end 🏗️ Proposed pattern Structured around two axes: department scope (permanent) and project scope (temporary). For department scope, sync the org graph and permissions from Workday or Okta, and configure each department agent with its own tools, data boundaries, and tone. A supervisor routes queries to the right department agent. For project scope, automatically provision agent workspaces when Jira or Asana projects are created, and archive them on completion -- distilling useful knowledge into the organizational knowledge graph. ✅ Selection criteria - Good fit: Large enterprises where workflows, tools, and regulations differ significantly by department; organizations with project-based work - Not a fit: Organizations where cross-functional work dominates and department boundaries are meaningless; purely routine operations ⚠️ Pitfalls - If agent scopes don't track org changes, permission mismatches will occur - Routing accuracy for cross-department queries needs empirical tuning - Neglecting knowledge distillation at project close means valuable insights are lost forever 🛠️ Implementation Approach 1. Sync the org graph from Workday / Okta via SCIM and dynamically maintain agent scopes based on department membership 2. Deploy a supervisor/router at the entry point to classify user intent and automatically route queries to the appropriate department agent (Sales, IT, HR, etc.) 3. Constrain each department agent's tools, data boundaries, and system prompt at the department level, managing permissions with ReBAC (Relationship-Based Access Control) 4. Trigger automatic provisioning of project-scoped agent workspaces on Jira / Asana project creation events, and archive them on project close 5. Build a pipeline that automatically distills valuable project knowledge into semantic memory and the organizational knowledge graph at project end #AIAgents# #EnterpriseArchitecture#