Address feedback

Author: JakeSCahill

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/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

@@ -20,25 +20,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 +78,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.
@@ -102,7 +112,7 @@ NOTE: Cross-agent calling between separate Redpanda Cloud agents is not supporte
 
 === 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
 
@@ -136,33 +146,55 @@ Avoid these architecture mistakes that lead to unmaintainable agent systems.
 
 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:
 
-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.
+* 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. Use subagents to partition tools by domain. For tool design patterns, see xref:ai-agents:mcp/remote/tool-patterns.adoc[].
+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
 

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

@@ -20,6 +20,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 +35,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 +52,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
 

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

@@ -8,6 +8,8 @@
 
 AI agents are systems that combine large language models (LLMs) with the ability to execute actions and process data. Redpanda Cloud provides real-time streaming infrastructure and standardized tool access to support agent development.
 
+include::ai-agents:partial$byoc-aws-requirement.adoc[]
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
@@ -16,15 +18,15 @@ After reading this page, you will be able to:
 
 == What is an AI agent?
 
-An AI agent is a system built around a large language model that can interpret user intent, decide which actions are required, invoke external tools, process live and historical data, and chain multiple steps into a workflow. AI agents differ from text-only LLMs by executing actions and invoking external tools.
+An AI agent is a system built around a glossterm:large language model (LLM)[] that can interpret user intent, decide which actions are required, invoke external tools, process live and historical data, and chain multiple steps into a workflow. AI agents differ from text-only LLMs by executing actions and invoking external tools.
 
 == How agents work
 
 Every AI agent consists of four essential components:
 
 * *System prompt*: Defines the agent's role, responsibilities, and constraints
 * *LLM*: Interprets user intent and decides which tools to invoke
-* *Tools*: External capabilities exposed through the Model Context Protocol (MCP)
+* *Tools*: External capabilities exposed through the xref:ai-agents:mcp/remote/overview.adoc[Model Context Protocol (MCP)]
 * *Context*: Conversation history, tool results, and real-time events from Redpanda topics
 
 Agents can invoke Redpanda Connect components as tools on-demand. Redpanda Connect pipelines can also invoke agents for event-driven processing. This bidirectional integration supports both interactive workflows and automated streaming.
@@ -35,7 +37,7 @@ For a deeper understanding of how agents execute, manage context, and maintain s
 
 == Key benefits
 
-Redpanda Cloud provides real-time streaming data so agents access live events instead of batch snapshots. Remote MCP support enables standardized tool access. Managed infrastructure handles deployment, scaling, and security for you. Low-latency execution means tools run close to your data. Integrated secrets management securely stores API keys and credentials.
+Redpanda Cloud provides real-time streaming data so agents access live events instead of batch snapshots. xref:ai-agents:mcp/remote/overview.adoc[Remote MCP] support enables standardized tool access. Managed infrastructure handles deployment, scaling, and security for you. Low-latency execution means tools run close to your data. Integrated secrets management securely stores API keys and credentials.
 
 == Use cases
 

modules/ai-agents/pages/agents/create-agent.adoc

@@ -292,9 +292,9 @@ Guide agents to:
 
 For cost management strategies including iteration limits and monitoring, see xref:ai-agents:agents/concepts.adoc[].
 
-== Example: Complete system prompt
+== Example: System prompt with all best practices
 
-This example demonstrates all best practices:
+This complete example demonstrates all the patterns described in this guide:
 
 [,text]
 ----