> ## Documentation Index > Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt > Use this file to discover all available pages before exploring further. # Foundational architecture considerations The following table covers the most common foundational architecture anti-patterns that affect agent reliability and scalability. ##### ⭐️ Most common anti-patterns | Anti-pattern | Problem | Impact | Fix | | --------------------------------------------- | ---------------------------------- | ----------------------------------------------- | ----------------------------------------------------------- | | ⭐️ The monolithic mega-prompt | 500-line instructions | Over constrained agents and reasoning conflicts | Split reasoning from formatting and execution | | ⭐️ The agent-as-business-process fallacy | Agents approximate processes | Deterministic processes not followed 100% | Use workflows | | Invisible state | Hidden state | Incorrect state tracking assumed | External state | | All-or-nothing autonomy | Binary autonomy | Cost/UX issues | Risk-based controls | | Passing 'as-is' information through the model | Paraphrasing authoritative content | Compliance risk | Route around LLM | | Chasing the latest research paper | Premature adoption | Low ROI | Stick to well known patterns and fix tools/workflow instead | #### What it is * Giving a single agent hundreds of procedural instructions (e.g., 500-line prompts) * Expecting the agent to follow them exactly, in order, every time * Treating the agent like a workflow engine that executes from memory #### Why it fails * LLMs compress context and lose detail in long instruction sets * Steps at the end of the list rely on lossy memory * Agent becomes nondeterministic even when process isn't #### What to do instead: Decompose and delegate * **Split into multi-agent system:** Break monolithic agent into focused sub-agents, each with a well-scoped task. Use a supervisor agent to handle routing and orchestration. * **Offload to workflow layer:** Move deterministic, repeatable sequences out of the agent entirely into workflow engines (BAW, wxO Agentic Workflow). * **Keep instructions small:** Each agent should have a targeted instruction set that stays within reliable attention range (not hundreds of lines). #### What it is * Replacing a structured business process (with branches, loops, approvals, rollback) with an agent * Assuming the agent will honor the same guarantees as a process engine * Using agent reasoning where deterministic execution is required #### Why it fails * Agents approximate processes rather than execute them exactly * No enforced transitions, rollback, or guaranteed audit trail * Compliance requirements demand deterministic execution #### What to do instead: separate reasoning from execution * **Use workflow engines for processes:** Business processes require explicit state machines with enforced transitions, rollback, and audit trails. Use dedicated workflow platforms (IBM BAW, wxO Agentic Workflow). * **Clear separation of concerns:** Agents handle open-ended reasoning, ambiguity resolution, and recommendations. Workflows handle decisions, branches, loops, approvals, and deterministic execution. * **Agent as participant:** An agent can be called at a specific workflow node to handle a reasoning task, but should not be the workflow itself. #### What it is * Assuming the LLM will track all past actions from conversation history * No explicit state object; state is implicit in the context window * Expecting the model to maintain structured state across long workflows #### Why it fails * Models create compressed mental maps that lose detail * Long threads cause older context to be dropped * State becomes increasingly distorted across steps #### What to do instead: Externalize state * **Explicit state objects:** Create structured state that is stored and passed intentionally between steps (not buried in conversation history). * **Structured updates:** Every step reads from and writes to specific state fields (e.g., `order_id`, `approval_status`, `items_processed`). * **No inference required:** Agents access state directly rather than trying to reconstruct what happened from context. #### What it is * Two extremes: agent acts freely without constraints, or asks permission for every decision * No calibrated middle ground based on risk or user context * Autonomy is binary rather than adjustable #### Why it fails * Too much autonomy: runaway costs, harmful sequences * Too little autonomy: slow, high-friction chatbot experience #### What to do instead: Calibrate autonomy by risk * **Action budgets:** Limit how many actions an agent can take per session (e.g., max 5 API calls, max \$10 spend). * **Approval gates:** Require human confirmation for high-risk actions (delete, purchase, send external communication). * **Risk-based thresholds:** Low-risk actions (read, search) run autonomously; medium-risk require notification; high-risk require approval. * **Context-aware levels:** Adjust autonomy based on user role, environment (dev vs prod), and task sensitivity. #### What it is * Passing legal statements, disclosures, or regulatory notices through the LLM * Expecting the model to deliver content exactly as written * Treating the model as a pass-through for verbatim content #### Why it fails * Models paraphrase, condense, and reformat by design * Even with strict instructions, exact content gets altered * Compliance violations in regulated industries #### What to do instead: Route around the model * **Tools deliver directly:** Have tools return exact content in documents (PDF generation) or push directly to user channels (email, SMS, portal) without passing through model generation. * **Workflow HITL steps:** Use Human-in-the-Loop workflow nodes to surface exact content directly to users, bypassing the agent for that step. * **MCP audience annotation:** Use Model Context Protocol's `audience` annotation to signal content is for end user, not model processing (requires agent support). * **Reference, don't regenerate:** Agent acknowledges the content exists and where to find it, but doesn't attempt to reproduce it. #### What it is * Adopting novel agent architectures (Swarm, CodeAct, CUGA, LLM-as-Judge) without clear need * Assuming architectural novelty will fix foundational problems * Reaching for complexity before exhausting proven patterns #### Why it fails * Misdiagnosis: problem is usually foundational, not architectural * Exotic patterns are harder to debug and maintain * Adds complexity without addressing root cause #### What to do instead: Exhaust proven patterns first * **Follow the progression:** Start with Single Prompt agent → ReAct (Reason-Act-Observe) → Chain-of-Thought → Supervisor pattern. Each adds complexity only when needed. * **Prove the need:** Only adopt advanced patterns (Swarm, CodeAct, LLM-as-Judge) after genuinely exhausting simpler approaches with real workloads. * **Diagnose first:** Make architectural decisions based on specific, diagnosed failure modes (e.g., "context loss at step 15") not on novelty or publication date. ## Related topics [Tooling and scalability considerations](/agents/agent_design/tooling_scalability) [Knowledge and document processing considerations](/agents/agent_design/knowledge_processing) [watsonx Orchestrate skills](/agents/agent_design/wxo_skills)