Merge branch 'ai-agents-documentation' into adp-pkg1

# Conflicts:
#	modules/ai-agents/pages/observability/concepts.adoc

Author: paulohtb6

modules/ai-agents/examples/agents/account-agent-prompt.txt

@@ -24,7 +24,7 @@ You are the account agent for ACME Bank's dispute resolution system. You special
 ## PII Protection Rules
 
 Always return masked data:
-- Email: First letter + **** + @domain (e.g., "s****@example.com")
+- Email: First letter + **** + @domain (for example, "s****@example.com")
 - Phone: ***-***-XXXX (last 4 digits only)
 - Card: Last 4 digits only
 - Never return: Full card numbers, SSNs, full account numbers

modules/ai-agents/examples/agents/dispute-root-agent-prompt.txt

@@ -61,12 +61,12 @@ Never:
 **Clear, bank-appropriate language:**
 - Use "I've reviewed your account" not "I called the account-agent"
 - Use "this charge doesn't match your typical spending" not "fraud score is 95/100"
-- Use "I'm blocking this card" not "I recommend you freeze it"
+- Use "We're blocking this card" not "I recommend you freeze it"
 - Don't reveal merchant reputation scores or fraud report counts
 
 **Proactive protection:**
 For likely fraud (score 80+):
-- Block the card immediately: "I'm blocking your card ending in [XXXX] right now to prevent additional fraudulent charges"
+- Block the card immediately: "We're blocking your card ending in [XXXX] right now to prevent additional fraudulent charges"
 - Issue replacement: "We'll send you a replacement card with a new number"
 - Process the claim: "You'll see the credit for this charge within 10 business days"
 

modules/ai-agents/examples/mcp-tools/processors/get_weather_complete.yaml

@@ -46,7 +46,7 @@ meta:
     properties:
       - name: city
         type: string
-        description: "City name (e.g., 'London', 'New York', 'Tokyo')"
+        description: "City name (for example, 'London', 'New York', 'Tokyo')"
         required: true
       - name: units
         type: string

modules/ai-agents/examples/mcp-tools/processors/search_jira.yaml

@@ -22,7 +22,7 @@ meta:
     properties:
       - name: jql
         type: string
-        description: "JQL query (e.g., 'project = DOC AND status = Open')"
+        description: "JQL query (for example, 'project = DOC AND status = Open')"
         required: true
       - name: max_results
         type: number

modules/ai-agents/images/agent-exit-conditions.png

@@ -8,6 +8,8 @@
 
 The Agent-to-Agent (A2A) protocol is an open standard for agent communication and discovery. Redpanda Cloud uses A2A for both external integration and internal pipeline-to-agent communication.
 
+include::ai-agents:partial$byoc-aws-requirement.adoc[]
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}

modules/ai-agents/images/agent-reasoning-loop.png

@@ -6,7 +6,9 @@
 :learning-objective-2: Choose appropriate LLM models based on task requirements
 :learning-objective-3: Apply agent boundary design principles for maintainability
 
-Design agent systems that are maintainable, discoverable, and reliable by choosing the right architecture pattern and applying clear boundary principles.
+This topic helps you design agent systems that are maintainable, discoverable, and reliable by choosing the right architecture pattern and applying clear boundary principles.
+
+include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
 After reading this page, you will be able to:
 
@@ -20,25 +22,33 @@ Agent architecture determines how you manage complexity as your system grows. Th
 
 Starting with a simple architecture is tempting, but can lead to unmaintainable systems as complexity increases. Planning for growth with clear boundaries prevents technical debt and costly refactoring later.
 
-Warning signs include system prompts exceeding 2000 words, too many tools for the LLM to select correctly, multiple teams modifying the same agent, and changes in one domain breaking others. These symptoms indicate you need architectural boundaries, not just better prompts.
+Warning signs that you need architectural boundaries, not just better prompts:
+
+* System prompts exceeding 2000 words
+* Too many tools for the LLM to select correctly
+* Multiple teams modifying the same agent
+* Changes in one domain breaking others
 
 Match agent architecture to domain structure:
 
-[cols="2,3,3"]
+[cols="2,2,3,3"]
 |===
-| Domain Characteristics | Architecture Fit | Reasoning
+| Domain Characteristics | Architecture | Pros | Cons
 
 | Single business area, stable requirements
 | Single agent
-| Simplicity outweighs flexibility needs
+| Simple to build and maintain, one deployment, lower latency
+| Limited flexibility, difficult to scale to multi-domain problems
 
 | Multiple business areas, shared infrastructure
 | Root agent with internal subagents
-| Domain separation without deployment complexity
+| Separation of concerns, easier debugging, shared resources reduce cost
+| Single point of failure, all subagents constrained to same model and budget
 
 | Cross-organization workflows, independent evolution
 | External agent-to-agent
-| Organizational boundaries require system boundaries
+| Independent deployment and scaling, security isolation, flexible infrastructure
+| Network latency, authentication complexity, harder to debug across boundaries
 |===
 
 
@@ -70,6 +80,8 @@ Single agents are simpler to build and maintain. You have one system prompt, one
 
 However, all capabilities must coexist in one agent. Adding features increases complexity rapidly, making single agents difficult to scale to multi-domain problems.
 
+TIP: You can migrate from a single agent to a root agent with subagents without starting over. Add subagents to an existing agent using the Redpanda Cloud Console, then gradually move tools and responsibilities to the new subagents.
+
 == Root agent with subagents pattern
 
 A multi-agent architecture uses a root agent that delegates to specialized internal subagents.
@@ -98,11 +110,11 @@ Internal subagents provide domain isolation, allowing you to update the order su
 
 External A2A integration connects agents across organizational boundaries, platforms, or independent systems.
 
-NOTE: Cross-agent calling between separate Redpanda Cloud agents is not supported. This pattern applies to connecting Redpanda Cloud agents with external agents you host elsewhere.
+NOTE: Cross-agent calling between separate Redpanda Cloud agents is not supported. This pattern only applies to connecting Redpanda Cloud agents with external agents you host elsewhere.
 
 === When to use external A2A
 
-Use external A2A for multi-organization workflows that coordinate agents across company boundaries, for platform integration connecting Redpanda Cloud agents with agents hosted elsewhere, and when agents require different deployment environments such as GPU clusters, air-gapped networks, or regional constraints.
+Use external glossterm:Agent2Agent (A2A) protocol[] for multi-organization workflows that coordinate agents across company boundaries, for platform integration connecting Redpanda Cloud agents with agents hosted elsewhere, and when agents require different deployment environments such as GPU clusters, air-gapped networks, or regional constraints.
 
 === How it works
 
@@ -130,39 +142,61 @@ For implementation details on external A2A integration, see xref:ai-agents:agent
 
 == Common anti-patterns
 
-Avoid these architecture mistakes that lead to unmaintainable agent systems.
+Avoid these architecture mistakes that lead to unmaintainable agent systems. For examples of well-structured agents, see the xref:ai-agents:agents/tutorials/customer-support-agent.adoc[multi-tool orchestration tutorial] and xref:ai-agents:agents/tutorials/transaction-dispute-resolution.adoc[multi-agent architecture tutorial].
 
 === The monolithic prompt
 
 A monolithic prompt is a single 3000+ word system prompt covering multiple domains.
 
-This pattern fails because LLM confusion increases with prompt length, multiple teams modify the same prompt creating conflicts and unclear ownership, and changes to one domain risk breaking others.
+This pattern fails because:
+
+* LLM confusion increases with prompt length
+* Multiple teams modify the same prompt creating conflicts and unclear ownership
+* Changes to one domain risk breaking others
 
 Split into domain-specific subagents instead. Each subagent gets a focused prompt under 500 words.
 
 === The tool explosion
 
-A tool explosion occurs when a single agent has 30+ tools from every MCP server in the cluster.
+A tool explosion occurs when a single agent has too many tools from every MCP server in the cluster.
 
-This pattern fails because the LLM struggles to choose correctly from large tool sets, tool descriptions compete for limited prompt space, and the agent invokes wrong tools with similar names, wasting iteration budget on selection mistakes.
+This pattern fails because:
 
-Limit tools per agent. Use subagents to partition tools by domain. For tool design patterns, see xref:ai-agents:mcp/remote/tool-patterns.adoc[].
+* The LLM struggles to choose correctly from large tool sets
+* Tool descriptions compete for limited prompt space
+* The agent invokes wrong tools with similar names, wasting iteration budget on selection mistakes
+
+Limit tools per agent to 10-15 for optimal performance. Agents with more than 20-25 tools often show degraded tool selection accuracy. Use subagents to partition tools by domain. For tool design patterns, see xref:ai-agents:mcp/remote/tool-patterns.adoc[].
 
 === Premature A2A splitting
 
 Premature splitting creates three separate A2A agents when all logic could fit in one agent with internal subagents.
 
-This pattern fails because network latency affects every cross-agent call, authentication complexity multiplies with three sets of credentials, debugging requires correlating logs across systems, and you manage three deployments instead of one.
+This pattern fails because:
+
+* Network latency affects every cross-agent call
+* Authentication complexity multiplies with three sets of credentials
+* Debugging requires correlating logs across systems
+* You manage three deployments instead of one
 
 Start with internal subagents for domain separation. Split to external A2A only when you need organizational boundaries or different infrastructure.
 
 === Unbounded tool chaining
 
 Unbounded chaining sets max iterations to 100, returns hundreds of items from tools, and places no constraints on tool call frequency.
 
-This pattern fails because the context window fills with tool results, requests time out before completion, costs spiral with many iterations multiplied by large context, and the agent loses track of the original goal.
+This pattern fails because:
+
+* The context window fills with tool results
+* Requests time out before completion
+* Costs spiral with many iterations multiplied by large context
+* The agent loses track of the original goal
+
+For best results:
 
-Design workflows to complete in 20-30 iterations. Return paginated results from tools. Add prompt constraints like "Never call the same tool more than 3 times per request."
+* Design workflows to complete in 20-30 iterations
+* Return paginated results from tools
+* Add prompt constraints like "Never call the same tool more than 3 times per request"
 
 == Model selection guide
 
@@ -180,7 +214,7 @@ For complex reasoning, choose premium models such as Claude Opus 4.5 or GPT-5.2.
 
 For real-time responses, choose smaller models. Use models optimized for speed, such as Mini or base tiers.
 
-For batch processing, optimize for accuracy over speed. Use larger models when users don't wait for results.
+For batch processing, optimize for accuracy over speed. Use larger models when users aren't waiting for results.
 
 === Optimize for cost and volume
 

modules/ai-agents/pages/agents/a2a-concepts.adoc

@@ -8,6 +8,8 @@
 
 Agents execute through a reasoning loop where the LLM analyzes context, decides which tools to invoke, processes results, and repeats until the task completes. Understanding this execution model helps you design reliable agent systems.
 
+include::ai-agents:partial$byoc-aws-requirement.adoc[]
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
@@ -20,6 +22,11 @@ Every agent request follows a reasoning loop. The agent doesn't execute all tool
 
 === The reasoning loop
 
+The following diagram shows how agents process requests through iterative reasoning:
+
+.Agent reasoning loop with tool integration
+image::ai-agents:agent-reasoning-loop.png[Diagram showing the agent reasoning loop: User Request flows to LLM Receives Context, then to LLM Decision which branches to Tool Executes, Request Clarification, or Return Response to User]
+
 When an agent receives a request:
 
 . The LLM receives the context, including system prompt, conversation history, user request, and previous tool results.
@@ -30,10 +37,15 @@ When an agent receives a request:
 
 The loop continues until one of these conditions is met:
 
+.Reasoning loop exit conditions
+image::ai-agents:agent-exit-conditions.png[Diagram showing exit conditions: Task Complete returns response, Max Iterations returns partial result, Unrecoverable Error returns error, otherwise continue loop]
+
 * Agent completes the task and responds to the user
 * Agent reaches max iterations limit
 * Agent encounters an unrecoverable error
 
+NOTE: If the agent encounters an unrecoverable error on the first iteration, it returns an error immediately. Unrecoverable errors include authentication failures, invalid tool configurations, or LLM API failures.
+
 === Why iterations matter
 
 Each iteration includes three phases:
@@ -42,9 +54,9 @@ Each iteration includes three phases:
 . **Tool invocation**: If the agent decides to call a tool, execution happens and waits for results.
 . **Context expansion**: Tool results are added to the conversation history for the next iteration.
 
-With higher iteration limits, agents can complete complex tasks but costs more and takes longer.
+With higher iteration limits, agents can complete complex tasks but can cost more and take longer.
 
-With lower iteration limits, agents respond faster and cheaper but may fail on complex requests.
+With lower iteration limits, agents can respond faster and are cheaper but may fail on complex requests.
 
 ==== Cost calculation
 

modules/ai-agents/pages/agents/architecture-patterns.adoc

@@ -8,6 +8,8 @@
 
 Create a new AI agent through the Redpanda Cloud Console. This guide walks you through configuring the agent's model, system prompt, tools, and execution settings.
 
+include::ai-agents:partial$byoc-aws-requirement.adoc[]
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
@@ -16,7 +18,7 @@ After reading this page, you will be able to:
 
 == Prerequisites
 
-* A xref:get-started:cluster-types/byoc/index.adoc[BYOC cluster] with Remote MCP enabled.
+* A xref:get-started:cluster-types/byoc/index.adoc[BYOC cluster].
 * xref:ai-agents:ai-gateway/gateway-quickstart.adoc[AI Gateway configured] with at least one LLM provider enabled.
 * At least one xref:ai-agents:mcp/remote/overview.adoc[Remote MCP server] deployed with tools.
 * System prompt prepared (see xref:ai-agents:agents/prompt-best-practices.adoc[System Prompt Best Practices]).
@@ -169,7 +171,7 @@ Choose based on task complexity:
 
 Start with 30 for most use cases.
 
-=== Configure A2A discovery metadata
+=== Configure A2A discovery metadata (optional)
 
 After creating your agent, configure discovery metadata for external integrations. For detailed agent card design guidance, see link:https://agent2agent.info/docs/guides/create-agent-card/[Create an Agent Card^].
 
@@ -192,8 +194,8 @@ Skills describe what your agent can do for capability-based discovery. External
 .. Click *+ Add Skill* to define what this agent can do.
 .. For each skill, configure:
 +
-* *Skill ID* (required): Unique identifier using lowercase letters, numbers, and hyphens (e.g., `fraud-analysis`, `order-lookup`)
-* *Skill Name* (required): Human-readable name displayed in agent directories (e.g., "Fraud Analysis", "Order Lookup")
+* *Skill ID* (required): Unique identifier using lowercase letters, numbers, and hyphens (for example, `fraud-analysis`, `order-lookup`)
+* *Skill Name* (required): Human-readable name displayed in agent directories (for example, "Fraud Analysis", "Order Lookup")
 * *Description* (required): Explain what this skill does and when to use it. Be specific about inputs, outputs, and use cases.
 * *Tags* (optional): Add tags for categorization and search. Use common terms like `fraud`, `security`, `finance`, `orders`.
 * *Examples* (optional): Click *+ Add Example* to provide sample queries demonstrating how to invoke this skill. Examples help users understand how to interact with your agent.
@@ -202,7 +204,7 @@ Skills describe what your agent can do for capability-based discovery. External
 
 . Click *Save Changes*.
 
-The updated metadata appears immediately at `\https://your-agent-url/.well-known/agent-card.json`. For more about what these fields mean and how they're used, see xref:ai-agents:agents/a2a-concepts.adoc#agent-card-metadata[Agent card metadata].
+The updated metadata appears immediately at `\https://your-agent-url/.well-known/agent-card.json`. For more about what these fields mean and how they're used, see xref:ai-agents:agents/a2a-concepts.adoc#agent-cards[Agent cards].
 
 === Review and create