DOC-1962 (#505)

micheleRP · web-flow · commit 6d08f5257863 · 2026-02-19T12:20:47.000-07:00
* DOC-1962

* update admonitions

* update admonition

* service account (singular) in UI

* move up admonition in agents files
diff --git a/modules/ai-agents/pages/adp-overview.adoc b/modules/ai-agents/pages/adp-overview.adoc
@@ -45,7 +45,7 @@ For more information, see xref:ai-agents:mcp/overview.adoc[MCP Servers Overview]
 
 Every agent action is recorded in an end-to-end execution log. A single glossterm:transcript[] can span multiple agents, tools, and models, covering interactions that last minutes to days.
 
-Transcripts are the keystone of agent governance. They are built on Redpanda's immutable log with glossterm:transcript[] consensus and TLA+ correctness proofs. No gaps, no tampering. For regulated industries that require multi-year audit trails, this provides a compliance-grade record of every decision an agent makes and every data source it uses.
+Transcripts are the keystone of agent governance. They are built on Redpanda's immutable log with transcript consensus and TLA+ correctness proofs. No gaps, no tampering. For regulated industries that require multi-year audit trails, this provides a compliance-grade record of every decision an agent makes and every data source it uses.
 
 Redpanda captures 100% of agent actions through OpenTelemetry standards, with end-to-end lineage across the entire execution chain. You can materialize execution logs to Iceberg tables for long-term retention and analysis, or replay them to evaluate and improve agent performance over time.
 
diff --git a/modules/ai-agents/pages/agents/a2a-concepts.adoc b/modules/ai-agents/pages/agents/a2a-concepts.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Explain how agent cards enable discovery
 :learning-objective-3: Identify how authentication secures agent communication
 
-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[]
 
+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.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/architecture-patterns.adoc b/modules/ai-agents/pages/agents/architecture-patterns.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Choose appropriate LLM models based on task requirements
 :learning-objective-3: Apply agent boundary design principles for maintainability
 
-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[]
 
+This topic helps you design agent systems that are maintainable, discoverable, and reliable by choosing the right architecture pattern and applying clear boundary principles.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/concepts.adoc b/modules/ai-agents/pages/agents/concepts.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Describe how agents manage context and state across interactions
 :learning-objective-3: Identify error handling strategies for agent failures
 
-After you declaratively configure an agent's behavior (its LLM, system prompt, and tools), the framework manages execution through a reasoning loop. The LLM analyzes context, decides which tools to invoke, processes results, and repeats until the task completes. Understanding this execution model helps you fine-tune agent settings like iteration limits and tool selection.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+After you declaratively configure an agent's behavior (its LLM, system prompt, and tools), the framework manages execution through a reasoning loop. The LLM analyzes context, decides which tools to invoke, processes results, and repeats until the task completes. Understanding this execution model helps you fine-tune agent settings like iteration limits and tool selection.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/create-agent.adoc b/modules/ai-agents/pages/agents/create-agent.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Connect MCP servers and select tools for your agent
 :learning-objective-3: Set agent execution parameters including max iterations
 
-Create a new AI agent declaratively through the Redpanda Cloud Console. No Python or JavaScript code required. This guide walks you through configuring the agent's model, writing the system prompt, connecting tools from built-in connectors, and setting execution parameters.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+Create a new AI agent declaratively through the Redpanda Cloud Console. No Python or JavaScript code required. This guide walks you through configuring the agent's model, writing the system prompt, connecting tools from built-in connectors, and setting execution parameters.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/index.adoc b/modules/ai-agents/pages/agents/index.adoc
@@ -2,4 +2,4 @@
 :page-layout: index
 :description: Declare agent behavior using built-in connectors in Redpanda Cloud. No custom agent code required.
 
-include::ai-agents:partial$ai-gateway-byoc-note.adoc[]
+include::ai-agents:partial$byoc-aws-requirement.adoc[]
diff --git a/modules/ai-agents/pages/agents/integration-overview.adoc b/modules/ai-agents/pages/agents/integration-overview.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Apply appropriate authentication for internal versus external integration
 :learning-objective-3: Select the right communication protocol for your integration scenario
 
-Redpanda Cloud supports multiple integration patterns for agents, pipelines, and external applications. Choose the pattern that matches your integration scenario.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+Redpanda Cloud supports multiple integration patterns for agents, pipelines, and external applications. Choose the pattern that matches your integration scenario.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/monitor-agents.adoc b/modules/ai-agents/pages/agents/monitor-agents.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Track token usage and performance metrics
 :learning-objective-3: pass:q[Debug agent execution using *Transcripts*]
 
-Use monitoring to track agent performance, analyze conversation patterns, debug execution issues, and optimize token costs.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+Use monitoring to track agent performance, analyze conversation patterns, debug execution issues, and optimize token costs.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/overview.adoc b/modules/ai-agents/pages/agents/overview.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Explain how Redpanda Cloud streaming infrastructure benefits agent architectures
 :learning-objective-3: Identify use cases where Redpanda Cloud agents provide value
 
-AI agents in Redpanda Cloud take a declarative approach: instead of writing Python or JavaScript agent code, you declare the behavior you want by selecting an LLM, writing a system prompt, and connecting tools drawn from 300+ built-in Redpanda Connect connectors. The framework handles execution, tool orchestration, and scaling, backed by real-time streaming infrastructure and built-in filtering and data enrichment.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+AI agents in Redpanda Cloud take a declarative approach: instead of writing Python or JavaScript agent code, you declare the behavior you want by selecting an LLM, writing a system prompt, and connecting tools drawn from 300+ built-in Redpanda Connect connectors. The framework handles execution, tool orchestration, and scaling, backed by real-time streaming infrastructure and built-in filtering and data enrichment.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/pipeline-integration-patterns.adoc b/modules/ai-agents/pages/agents/pipeline-integration-patterns.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: pass:q[Design event-driven agent invocation using the `a2a_message` processor]
 :learning-objective-3: Implement streaming enrichment with AI-generated fields
 
-Build Redpanda Connect pipelines that invoke agents for automated, event-driven processing. Pipelines use the `a2a_message` processor to call agents for each event in a stream when you need AI reasoning, classification, or enrichment at scale.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+Build Redpanda Connect pipelines that invoke agents for automated, event-driven processing. Pipelines use the `a2a_message` processor to call agents for each event in a stream when you need AI reasoning, classification, or enrichment at scale.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/prompt-best-practices.adoc b/modules/ai-agents/pages/agents/prompt-best-practices.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Apply constraint patterns to prevent unintended agent behavior
 :learning-objective-3: Evaluate system prompts for clarity and completeness
 
-Write system prompts that produce reliable, predictable agent behavior. Good prompts define scope, specify constraints, and guide tool usage.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+Write system prompts that produce reliable, predictable agent behavior. Good prompts define scope, specify constraints, and guide tool usage.
+
 After reading this page, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/quickstart.adoc b/modules/ai-agents/pages/agents/quickstart.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Configure the agent with a system prompt and model selection
 :learning-objective-3: Test the agent by generating and publishing events through natural language
 
-This quickstart helps you build your first AI agent in Redpanda Cloud. You'll create an agent that understands natural language requests and uses MCP tools to generate and publish event data to Redpanda topics.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+This quickstart helps you build your first AI agent in Redpanda Cloud. You'll create an agent that understands natural language requests and uses MCP tools to generate and publish event data to Redpanda topics.
+
 After completing this quickstart, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/pages/agents/troubleshooting.adoc b/modules/ai-agents/pages/agents/troubleshooting.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Resolve runtime behavior issues including tool selection and iteration limits
 :learning-objective-3: Fix tool execution problems and authentication failures
 
-Use this page to diagnose and fix common issues with AI agents, including deployment failures, runtime behavior problems, tool execution errors, and integration issues.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+Use this page to diagnose and fix common issues with AI agents, including deployment failures, runtime behavior problems, tool execution errors, and integration issues.
+
 == Deployment issues
 
 Fix issues that prevent agents from connecting to required resources.
diff --git a/modules/ai-agents/pages/agents/tutorials/customer-support-agent.adoc b/modules/ai-agents/pages/agents/tutorials/customer-support-agent.adoc
@@ -6,10 +6,10 @@
 :learning-objective-2: Apply tool orchestration patterns to handle multi-step workflows
 :learning-objective-3: Evaluate how system prompt design affects agent tool selection
 
-This tutorial shows you how to build a customer support agent to learn how agents orchestrate multiple tools, make context-aware decisions, and handle incomplete data.
-
 include::ai-agents:partial$byoc-aws-requirement.adoc[]
 
+This tutorial shows you how to build a customer support agent to learn how agents orchestrate multiple tools, make context-aware decisions, and handle incomplete data.
+
 After completing this tutorial, you will be able to:
 
 * [ ] {learning-objective-1}
diff --git a/modules/ai-agents/partials/ai-gateway-byoc-note.adoc b/modules/ai-agents/partials/ai-gateway-byoc-note.adoc
@@ -1 +1 @@
-NOTE: Redpanda Agentic Data Plane is supported on BYOC clusters running with AWS and Redpanda version 25.3 and later. It is currently in a glossterm:LA[, limited availability] release.
+IMPORTANT: Redpanda Agentic Data Plane is supported only on BYOC clusters running with AWS and Redpanda version 25.3+. It is currently in glossterm:LA[, limited availability].
diff --git a/modules/ai-agents/partials/service-account-authorization.adoc b/modules/ai-agents/partials/service-account-authorization.adoc
@@ -1,25 +1,20 @@
-[[service-account-authorization]]
+[[service-account-authorization]] 
 == Service account authorization
 
-When you create a glossterm:mcp-server[] or glossterm:ai-agent[], Redpanda Cloud automatically creates a glossterm:service-account[] to glossterm:authentication[authenticate] requests to your glossterm:cluster[].
+When you create an MCP server or AI agent, Redpanda Cloud automatically creates a service account to authenticate requests to your cluster. The service account is created with the following:
 
-=== Default configuration
+*Name*: Prepopulated as `cluster-<cluster-id>-<resource-type>-<resource-name>-sa`, where `sa` stands for service account. For example:
 
-The service account is created with:
-
-* *Name*: Pre-filled as `cluster-<cluster-id>-<resource-type>-<resource-name>-sa`, where `sa` stands for service account. For example:
-** MCP server: `cluster-d5tp5kntujt599ksadgg-mcp-my-test-server-sa`
-** AI agent: `cluster-d5tp5kntujt599ksadgg-agent-my-agent-sa`
+* MCP server: `cluster-d5tp5kntujt599ksadgg-mcp-my-test-server-sa`
+* AI agent: `cluster-d5tp5kntujt599ksadgg-agent-my-agent-sa`
 +
 You can customize this name during creation.
 
-* *Role binding*: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage glossterm:topic[,topics], and access cluster resources.
+*Role binding*: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage topics, and access cluster resources.
 
 === Manage service accounts
 
-You can view and manage service accounts created for MCP servers and AI agents in *Organization* > *IAM* > *Service accounts*.
-
-The Organization IAM page shows additional details not visible during creation:
+You can view and manage service accounts created for MCP servers and AI agents at the organization level in *Organization IAM* > *Service account*. This page shows additional details not visible during creation:
 
 [cols="1,2", options="header"]
 |===
@@ -54,8 +49,8 @@ Deleting a service account removes authentication for the associated MCP server
 
 The default Writer role provides broad access suitable for most use cases. If you need more restrictive permissions:
 
-. Exit the cluster. Navigate to *Organization IAM* > *Service accounts*.
+. Exit the cluster and navigate to *Organization IAM* > *Service account*.
 . Find the service account for your resource.
 . Edit the role bindings to use a more restrictive role or scope.
 
-For more about roles and permissions, see xref:security:authorization/rbac/rbac.adoc[Role-based access control].
+For more information about roles and permissions, see xref:security:authorization/rbac/rbac.adoc[Role-based access control].
diff --git a/modules/get-started/pages/whats-new-cloud.adoc b/modules/get-started/pages/whats-new-cloud.adoc
@@ -10,7 +10,7 @@ This page lists new features added to Redpanda Cloud.
 
 === Agentic Data Plane (ADP): LA
 
-Redpanda Agentic Data Plane (ADP) is now available in a glossterm:LA[, limited availability] (LA) release. Redpanda ADP provides enterprise-grade infrastructure for building, deploying, and governing AI agents at scale. Key capabilities include declarative agents, MCP servers backed by 300+ connectors, an AI Gateway with model failover and fiscal controls, and compliance-grade transcripts built on Redpanda's immutable log. 
+Redpanda Agentic Data Plane (ADP) is now available in glossterm:LA[, limited availability] (LA). Redpanda ADP provides enterprise-grade infrastructure for building, deploying, and governing AI agents at scale. Key capabilities include declarative agents, MCP servers backed by 300+ connectors, an AI Gateway with model failover and fiscal controls, and compliance-grade transcripts built on Redpanda's immutable log. 
 
 See xref:ai-agents:adp-overview.adoc[Agentic Data Plane Overview].
 
