cleanup

Author: micheleRP

modules/ai-agents/pages/adp-overview.adoc

@@ -7,7 +7,7 @@
 :learning-objective-2: Describe how each component addresses enterprise governance and reliability requirements
 :learning-objective-3: Determine whether Redpanda ADP fits your organization's requirements for AI agent deployment
 
-glossterm:AI agent[,AI agents] are moving from demos to production. Enterprises need governance, reliability, and cost control to deploy them safely. Redpanda Agentic Data Plane (ADP) combine a streaming-native immutable log, 300+ proven data connectors, and declarative glossterm:AI agent[,AI agents] into a unified platform with built-in compliance-grade audit trails.
+glossterm:AI agent[,AI agents] are moving from demos to production. Enterprises need governance, reliability, and cost control to deploy them safely. Redpanda Agentic Data Plane (ADP) combines a streaming-native immutable log, 300+ proven data connectors, and declarative AI agents into a unified platform with built-in compliance-grade audit trails.
 
 After reading this page, you will be able to:
 

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

@@ -18,11 +18,11 @@ After reading this page, you will be able to:
 
 == What is an AI agent?
 
-An AI agent is a system built around a glossterm:large language model (LLM)[] that interprets user intent, selects the right tools, and chains multiple steps into a workflow. In Redpanda Cloud, agents are declarative: you configure what the agent should do (its role, constraints, and available tools) rather than writing imperative agent code. This is possible because Redpanda Connect provides 300+ connectors and robust data processing capabilities that the framework orchestrates for you.
+An AI agent is a system built around a glossterm:large language model (LLM)[] that interprets user intent, selects the right tools, and chains multiple steps into a workflow. In Redpanda Cloud, agents are declarative: you configure what the agent should do (its role, constraints, and available tools) rather than writing imperative agent code. This is possible because Redpanda Connect provides the connectors and robust data processing capabilities that the framework orchestrates for you.
 
 == How agents work
 
-When you create an agent, you configure these four components through the Redpanda Cloud Console rather than writing code:
+When you create an agent, you configure the components through the Redpanda Cloud Console rather than writing code:
 
 * *System prompt*: Defines the agent's role, responsibilities, and constraints
 * *LLM*: Interprets user intent and decides which tools to invoke

modules/ai-agents/pages/ai-gateway/builders/discover-gateways.adoc

@@ -34,7 +34,7 @@ Click the Configuration, API, MCP Tools, and Changelog tabs for additional infor
 
 Using the API::
 +
-You can also list gateways programmatically:
+To list gateways programmatically:
 +
 [source,bash]
 ----

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

@@ -8,11 +8,11 @@
 
 include::ai-agents:partial$ai-gateway-byoc-note.adoc[]
 
-This page provides technical details about AI Gateway's architecture, request processing, and capabilities. For an introduction to AI Gateway and the problems it solves, see xref:ai-agents:ai-gateway/what-is-ai-gateway.adoc[]
+This page provides technical details about AI Gateway's architecture, request processing, and capabilities. For an overview of AI Gateway, see xref:ai-agents:ai-gateway/what-is-ai-gateway.adoc[]
 
 == Architecture overview
 
-AI Gateway consists of three planes: a glossterm:control plane[] for configuration and management, a glossterm:data plane[] for request processing and routing, and an observability plane for monitoring and analytics.
+AI Gateway consists of a glossterm:control plane[] for configuration and management, a glossterm:data plane[] for request processing and routing, and an observability plane for monitoring and analytics.
 
 // PLACEHOLDER: Add architecture diagram showing:
 // 1. Control Plane:
@@ -38,7 +38,7 @@ AI Gateway consists of three planes: a glossterm:control plane[] for configurati
 The control plane manages gateway configuration and policy definition:
 
 * **Workspace management**: Multi-tenant isolation with separate namespaces for different teams or environments
-* **Provider configuration**: Enable and configure LLM providers (OpenAI, Anthropic, etc.)
+* **Provider configuration**: Enable and configure LLM providers (such as OpenAI and Anthropic)
 * **Gateway creation**: Define gateways with specific routing rules, budgets, and rate limits
 * **Policy definition**: Create CEL-based routing policies, spend limits, and rate limits
 * **MCP server registration**: Configure which MCP servers are available to agents
@@ -51,7 +51,7 @@ The data plane handles all runtime request processing:
 * **Authentication**: Validate API keys and gateway access
 * **Policy evaluation**: Apply rate limits, spend limits, and routing policies
 * **Provider pool management**: Select primary or fallback providers based on availability
-* **MCP aggregation**: Aggregate tools from multiple MCP servers with deferred loading
+* **MCP proxy**: Aggregate tools from multiple MCP servers with deferred loading
 * **Response transformation**: Normalize provider-specific responses to OpenAI format
 * **Metrics collection**: Record token usage, latency, and cost for every request
 
@@ -143,7 +143,7 @@ In AI Hub mode, resources are divided into two categories:
 * Failover logic
 * Provider selection algorithms
 
-*User-Configurable Resources:*
+*User-configurable resources:*
 
 * Provider credentials (OpenAI, Anthropic, Google Gemini)
 * 6 preference toggles

modules/ai-agents/pages/ai-gateway/gateway-quickstart.adoc

@@ -1,7 +1,7 @@
 = AI Gateway Quickstart
 :description: Get started with AI Gateway. Configure providers, create your first gateway with failover and budget controls, and route your first request.
 :page-topic-type: quickstart
-:personas: app_developer, platform_admin
+:personas: evaluator, app_developer, platform_admin
 :learning-objective-1: Enable an LLM provider and create your first gateway
 :learning-objective-2: Route your first request through AI Gateway and verify it works
 :learning-objective-3: Verify request routing and token usage in the gateway overview
@@ -61,7 +61,7 @@ ifdef::ai-hub-available[]
 ====
 When creating a gateway, you choose between two modes:
 
-* *AI Hub Mode*: Zero-configuration with pre-configured routing and backend pools. Just add provider credentials and start routing requests. Ideal for quick starts and standard use cases.
+* *AI Hub Mode*: Zero-configuration with pre-configured routing and backend pools. Just add provider credentials and start routing requests. Ideal for quickstarts and standard use cases.
 * *Custom Mode*: Full control over all routing rules, backend pools, and policies. Requires manual configuration. Ideal for custom routing logic and specialized requirements.
 
 See xref:ai-gateway/gateway-modes.adoc[] to understand which mode fits your needs. This quickstart focuses on Custom mode configuration.
@@ -273,9 +273,9 @@ The gateway provides these built-in MCP tools:
 * *Data catalog API*: Query your data catalog
 * *Memory store*: Persistent storage for agent state
 * *Vector search*: Semantic search over embeddings
-* *MCP orchestrator*: Built-in tool for programmatic multi-tool workflows
+* *MCP Orchestrator*: Built-in tool for programmatic multi-tool workflows
 
-The *MCP orchestrator* enables agents to generate JavaScript code that calls multiple tools in a single orchestrated step, reducing round trips. For example, a workflow requiring 47 file reads can be reduced from 49 round trips to just 1.
+The *MCP Orchestrator* enables agents to generate JavaScript code that calls multiple tools in a single orchestrated step, reducing round trips. For example, a workflow requiring 47 file reads can be reduced from 49 round trips to just 1.
 
 To add external tools (for example, Slack, GitHub), add their MCP server endpoints to your gateway configuration.
 
@@ -284,14 +284,10 @@ To add external tools (for example, Slack, GitHub), add their MCP server endpoin
 When many tools are aggregated, listing all tools upfront can consume significant tokens. With deferred tool loading, the MCP gateway initially returns only:
 
 * A tool search capability
-* The MCP orchestrator
+* The MCP Orchestrator
 
 Agents then search for specific tools they need, retrieving only that subset. This can reduce token usage by 80-90% when you have many tools configured.
 
-// REVIEWERS: When/how exactly do you use the orchestrator? Also what happens after they create a gateway? Please provide an example of how to validate end-to-end routing against the gateway endpoint!
-
-// REVIEWERS: How do users connect to the ADP catalog + MCP servers exposed through RPCN?
-
 == Configure CEL routing rule (optional)
 
 Use CEL (Common Expression Language) expressions to route requests dynamically based on headers, content, or other request properties.

modules/ai-agents/pages/ai-gateway/mcp-aggregation-guide.adoc

@@ -13,14 +13,14 @@ The MCP Gateway provides glossterm:MCP[,Model Context Protocol (MCP)] aggregatio
 MCP Gateway benefits:
 
 * Single endpoint: One MCP endpoint aggregates all approved MCP servers
-* Token reduction: Often 80-90% fewer tokens through deferred tool loading (depending on configuration)
+* Token reduction: Fewer tokens through deferred tool loading (depending on configuration)
 * Centralized governance: Admin-approved MCP servers only
 * Orchestration: JavaScript-based orchestrator reduces multi-step round trips
 * Security: Controlled tool execution environment
 
 == What is MCP?
 
-glossterm:MCP[,Model Context Protocol (MCP)] is a standard for exposing tools (functions) that AI agents can discover and invoke. MCP servers provide tools like:
+Model Context Protocol (MCP) is a standard for exposing tools (functions) that AI agents can discover and invoke. MCP servers provide tools like:
 
 * Database queries
 * File system operations
@@ -58,14 +58,14 @@ glossterm:MCP[,Model Context Protocol (MCP)] is a standard for exposing tools (f
 │  (Claude, GPT)  │
 └────────┬────────┘
          │
-         │ 1. Discover tools via /mcp endpoint
+         │ 1. Discover tools with /mcp endpoint
          │ 2. Invoke specific tool
          │
 ┌────────▼────────────────────────────────┐
 │      AI Gateway (MCP Aggregator)        │
 │                                         │
 │  ┌─────────────────────────────────┐   │
-│  │  Deferred Tool Loading          │   │
+│  │  Deferred tool loading          │   │
 │  │  (Send search + orchestrator    │   │
 │  │   initially, defer others)      │   │
 │  └─────────────────────────────────┘   │
@@ -249,8 +249,8 @@ Agent receives result and can continue reasoning.
 Traditional MCP (No deferred loading):
 
 1. Agent connects to MCP endpoint
-2. Gateway sends ALL tools from ALL MCP servers (50+ tools)
-3. Agent includes ALL tool definitions in EVERY LLM request
+2. Gateway sends all tools from all MCP servers (50+ tools)
+3. Agent includes all tool definitions in every LLM request
 4. High token cost: ~5,000-10,000 tokens per request
 
 Deferred loading (AI Gateway):
@@ -259,11 +259,10 @@ Deferred loading (AI Gateway):
 2. Gateway sends only 2 tools: `search_tools` + `orchestrator`
 3. Agent includes only 2 tool definitions in LLM request (~500-1,000 tokens)
 4. When agent needs specific tool:
-   * Agent calls `search_tools` with query (e.g., "database")
+   * Agent calls `search_tools` with query (for example, "database")
    * Gateway returns matching tools
-   * Agent calls specific tool (e.g., `execute_sql`)
+   * Agent calls specific tool (for example, `execute_sql`)
 5. Total token cost: Initial 500-1,000 + per-query ~200-500
-   * Often 80-90% lower than loading all tools
 
 === When to use deferred loading
 
@@ -282,7 +281,7 @@ Don't use deferred loading when:
 
 === Configure deferred loading
 
-Deferred loading is configured per MCP server through the *Defer Loading Override* setting in the Create MCP Server dialog.
+Deferred loading is configured for each MCP server through the *Defer Loading Override* setting in the Create MCP Server dialog.
 
 . Navigate to your gateway's *MCP* tab.
 . Create or edit an MCP server.
@@ -328,7 +327,7 @@ Compare token usage before/after deferred loading:
 Savings % = ((Before - After) / Before) × 100
 ----
 
-Expected Results: Typically 80-90% reduction in average tokens per request
+Expected results: Typically 80-90% reduction in average tokens per request
 
 == Orchestrator: multi-step workflows
 
@@ -342,7 +341,7 @@ Without Orchestrator:
 2. Agent receives results, evaluates: "Results insufficient"
 3. Agent: "Fallback to web search" → Round trip 2
 4. Agent receives results, processes → Round trip 3
-5. *Total: 3 round trips* (high latency, 3× token cost)
+5. *Total: 3 round trips* (high latency, 3x token cost)
 
 With Orchestrator:
 
@@ -594,9 +593,9 @@ Common MCP servers:
 
 * Database: PostgreSQL, MySQL, MongoDB query tools
 * Filesystem: Read/write/search files
-* API Integrations: Slack, GitHub, Salesforce, Stripe
-* Search: Web search, vector search, enterprise search
-* Code Execution: Python, JavaScript sandboxes
+* API integrations: Slack, GitHub, Salesforce, Stripe
+* Search: web search, vector search, enterprise search
+* Code execution: Python, JavaScript sandboxes
 * Workflow: Zapier, n8n integrations
 
 === MCP server approval workflow
@@ -759,7 +758,7 @@ Possible causes:
 
 Solution:
 
-1. Verify MCP server is active in the Cloud console
+1. Verify MCP server is active in the Redpanda Cloud console
 2. Verify tool is in enabled_tools list
 3. If deferred loading: Agent must call `search_tools` first
 
@@ -768,13 +767,13 @@ Issue: "MCP server timeout"
 Possible causes:
 
 1. MCP server is down/unreachable
-2. Tool execution is slow (e.g., expensive database query)
+2. Tool execution is slow (for example, expensive database query)
 3. Gateway timeout too short
 
 Solution:
 
 1. Check MCP server health
-2. Optimize tool (e.g., add database index)
+2. Optimize tool (for example, add database index)
 3. Contact support if you need to adjust timeout limits
 
 Issue: "Orchestrator workflow failed"
@@ -805,8 +804,8 @@ Orchestrator sandbox:
 * No file system access
 * No network access (except via MCP tools)
 * No system calls
-* Memory limit: // PLACEHOLDER: e.g., 128MB
-* Execution timeout: // PLACEHOLDER: e.g., 30s
+* Memory limit: // PLACEHOLDER: for example, 128MB
+* Execution timeout: // PLACEHOLDER: for example, 30s
 
 MCP tool execution:
 
@@ -856,7 +855,7 @@ Best practice:
 
 * Read-only tools in production gateway
 * Write tools only in staging gateway (with approval workflows)
-* Wrap dangerous operations in MCP server with safeguards (e.g., "require confirmation token")
+* Wrap dangerous operations in MCP server with safeguards (for example, "require confirmation token")
 
 == MCP + LLM routing