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

paulohtb6 · paulohtb6 · commit 29a712386074 · 2026-01-30T10:59:14.000-03:00
diff --git a/modules/ai-agents/examples/mcp-tools/inputs/event_driven_workflow.yaml b/modules/ai-agents/examples/mcp-tools/inputs/event_driven_workflow.yaml
@@ -20,12 +20,16 @@ redpanda:
             - http:
                 url: "${secrets.INVENTORY_API}/reserve"
                 verb: POST
+                headers:
+                  Content-Type: application/json
                 body: '{"order_id": "${! this.order_id }", "items": ${! json("items") }}'
         - check: this.event_type == "payment_confirmed"
           processors:
             - http:
                 url: "${secrets.FULFILLMENT_API}/ship"
                 verb: POST
+                headers:
+                  Content-Type: application/json
                 body: '{"order_id": "${! this.order_id }"}'
 # end::component[]
 
diff --git a/modules/ai-agents/examples/mcp-tools/processors/get_order_status.yaml b/modules/ai-agents/examples/mcp-tools/processors/get_order_status.yaml
@@ -1,9 +1,7 @@
 label: get_order_status
-
-processors:
-  - mapping: |
-      let order_id = this.order_id
-      root = if $order_id == "ORD-12345" {
+mapping: |
+  let order_id = this.order_id
+  root = if $order_id == "ORD-12345" {
         {
           "order_id": $order_id,
           "status": "shipped",
@@ -23,7 +21,7 @@ processors:
         }
       } else if $order_id == "ORD-99999" {
         {
-          "error": true,
+          "error": "order_not_found",
           "message": "Order not found"
         }
       } else {
diff --git a/modules/ai-agents/examples/mcp-tools/processors/get_risk_indicators.yaml b/modules/ai-agents/examples/mcp-tools/processors/get_risk_indicators.yaml
@@ -74,6 +74,8 @@ mapping: |
       "critical_count": 0,
       "high_count": 0,
       "medium_count": 2,
+      "low_count": 1,
+      "none_count": 0,
       "overall_assessment": "medium_fraud_probability"
     },
     this.transaction_id == "TXN-89015" => {
@@ -99,6 +101,8 @@ mapping: |
       "critical_count": 0,
       "high_count": 0,
       "medium_count": 0,
+      "low_count": 1,
+      "none_count": 2,
       "overall_assessment": "low_fraud_probability"
     },
     _ => {
@@ -108,6 +112,8 @@ mapping: |
       "critical_count": 0,
       "high_count": 0,
       "medium_count": 0,
+      "low_count": 0,
+      "none_count": 0,
       "overall_assessment": "insufficient_data"
     }
   }
diff --git a/modules/ai-agents/examples/mcp-tools/processors/get_transaction_details.yaml b/modules/ai-agents/examples/mcp-tools/processors/get_transaction_details.yaml
@@ -9,7 +9,7 @@ mapping: |
       "merchant": {
         "name": "LUXURY WATCHES INT",
         "category": "jewelry",
-        "country": "Singapore",
+        "country": "SG",
         "mcc": "5944"
       },
       "card_last_four": "4532",
@@ -29,7 +29,7 @@ mapping: |
       "merchant": {
         "name": "EXAMPLE MKTPLACE",
         "category": "online_retail",
-        "country": "USA",
+        "country": "US",
         "mcc": "5942"
       },
       "card_last_four": "4532",
@@ -49,7 +49,7 @@ mapping: |
       "merchant": {
         "name": "EXAMPLE STREAMING",
         "category": "subscription_service",
-        "country": "USA",
+        "country": "US",
         "mcc": "4899"
       },
       "card_last_four": "8821",
@@ -70,7 +70,7 @@ mapping: |
       "merchant": {
         "name": "HOTEL PARIS",
         "category": "lodging",
-        "country": "France",
+        "country": "FR",
         "mcc": "7011"
       },
       "card_last_four": "2193",
diff --git a/modules/ai-agents/examples/mcp-tools/processors/openai_chat.yaml b/modules/ai-agents/examples/mcp-tools/processors/openai_chat.yaml
@@ -12,7 +12,7 @@ openai_chat_completion:
     2. Key themes
     3. Actionable insights
 
-    Feedback: ${! json("feedback_text") }
+    Feedback: ${! json(feedback_text) }
   max_tokens: 500
 # end::component[]
 
diff --git a/modules/ai-agents/examples/mcp-tools/processors/transform_validate.yaml b/modules/ai-agents/examples/mcp-tools/processors/transform_validate.yaml
@@ -14,7 +14,7 @@ processors:
       root.is_premium = this.subscription_tier == "premium"
 
       # Filter sensitive data
-      root.profile = this.profile.without("ssn", "credit_card")
+      root.profile = this.profile.or({}).without("ssn", "credit_card")
   # end::mapping[]
 
 meta:
diff --git a/modules/ai-agents/examples/mcp-tools/processors/verify_merchant.yaml b/modules/ai-agents/examples/mcp-tools/processors/verify_merchant.yaml
@@ -103,6 +103,13 @@ mapping: |
       "reputation_score": 50,
       "reputation_level": "unknown",
       "verification_status": "not_found",
+      "fraud_reports": {
+        "total_reports": 0,
+        "recent_reports_30d": 0,
+        "confirmed_fraud_cases": 0
+      },
+      "business_details": {},
+      "red_flags": [],
       "message": "Merchant not found in verification database",
       "recommendation": "manual_review_required"
     }
diff --git a/modules/ai-agents/examples/mcp-tools/snippets/defaults.yaml b/modules/ai-agents/examples/mcp-tools/snippets/defaults.yaml
@@ -17,4 +17,8 @@ properties:
     type: string
     description: "Temperature units: 'metric' or 'imperial' (default: metric)"
     required: false
+  - name: limit
+    type: number
+    description: "Max results (default: 10)"
+    required: false
 # end::properties[]
diff --git a/modules/ai-agents/examples/pipelines/fraud-detection-routing.yaml b/modules/ai-agents/examples/pipelines/fraud-detection-routing.yaml
@@ -32,7 +32,7 @@ pipeline:
                 Return JSON: { "fraud_score": 0-100, "reason": "explanation", "recommend_block": true/false }
         result_map: |
           root = this
-          root.fraud_analysis = content()
+          root.fraud_analysis = content().parse_json().catch({})
 
     - mapping: |
         root = this
diff --git a/modules/ai-agents/pages/agents/a2a-concepts.adoc b/modules/ai-agents/pages/agents/a2a-concepts.adoc
@@ -45,7 +45,7 @@ For example, if your agent URL is `\https://my-agent.ai-agents.abc123.cloud.redp
 
 The `.well-known` path follows internet standards for service discovery, making agents discoverable without configuration.
 
-To configure these fields, see xref:ai-agents:agents/create-agent.adoc#configure-a2a-discovery-metadata-optional[Configure A2A discovery metadata].
+To configure the agent card, see xref:ai-agents:agents/create-agent.adoc#configure-a2a-discovery-metadata-optional[Configure A2A discovery metadata].
 
 == Where A2A is used in Redpanda Cloud
 
diff --git a/modules/ai-agents/pages/agents/troubleshooting.adoc b/modules/ai-agents/pages/agents/troubleshooting.adoc
@@ -60,7 +60,7 @@ NEVER respond about order status without calling the tool first.
 ----
 
 . Review tool descriptions in your MCP server configuration.
-. Use a more capable model (GPT-5.2, Claude Sonnet 4.5, or equivalent).
+. Use a more capable model from the supported list for your gateway.
 . Increase max iterations if the agent is stopping before reaching tools.
 
 **Prevention:**
@@ -216,9 +216,7 @@ Diagnose and fix issues related to agent speed and resource consumption.
 
 **Solution:**
 
-. Use a faster model for simple queries:
-.. GPT-5 Mini for straightforward tasks
-.. Reserve larger models for complex reasoning
+. Use a faster, lower-latency model tier for simple queries and reserve larger models for complex reasoning.
 . Review conversation history in the *Inspector* tab to identify unnecessary tool calls.
 . Optimize tool implementations:
 .. Add caching where appropriate
diff --git a/modules/ai-agents/pages/agents/tutorials/customer-support-agent.adoc b/modules/ai-agents/pages/agents/tutorials/customer-support-agent.adoc
@@ -213,7 +213,7 @@ Click *Clear context* to clear the conversation history. Then enter this query:
 Where is my order?
 ----
 
-The agent recognizes the request is missing an order ID and asks the customer to provide it. Watch the conversation panel—the agent calls zero tools. Instead of guessing or fabricating information, it asks a clarifying question.
+The agent recognizes the request is missing an order ID and asks the customer to provide it. Watch the conversation panel and see that the agent calls zero tools. Instead of guessing or fabricating information, it asks a clarifying question.
 
 This demonstrates pre-condition checking. Effective orchestration includes knowing when NOT to invoke tools.
 
diff --git a/modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc b/modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc
@@ -24,9 +24,9 @@ These patterns apply beyond banking to any domain requiring specialized expertis
 
 Banks handle thousands of dispute calls daily. Customers report unauthorized charges, billing errors, or unrecognized transactions. Each investigation requires cross-referencing multiple systems and applying consistent fraud detection logic.
 
-Traditionally, human agents manually open multiple systems, cross-reference data, and take notes—a 10-15 minute process prone to inconsistencies and incomplete compliance logging.
+Traditionally, human agents manually open multiple systems, cross-reference data, and take notes. A 10-15 minute process prone to inconsistencies and incomplete compliance logging.
 
-Multi-agent automation transforms this workflow by enabling instant data aggregation from all sources, consistent logic applied every time, 30-60 second resolution for simple cases, and structured results for compliance. Human agents handle only complex escalations.
+Multi-agent automation transforms this workflow by enabling instant data aggregation from all sources, consistent logic applied every time, 10-15 second resolution, and structured results for compliance. Human agents handle only complex escalations.
 
 When a customer calls saying "I see a $247.83 charge from 'ACME CORP' but I never shopped there. Is this fraud?", the system must investigate account history, calculate fraud scores, verify merchant legitimacy, and make a recommendation with structured results.
 
@@ -215,7 +215,7 @@ The root agent orchestrates sub-agents and makes final recommendations. You'll c
 
 [IMPORTANT]
 ====
-Sub-agents inherit the LLM provider, model, resource tier, and max iterations from the root agent. This tutorial uses GPT-5 Mini and max iterations of 15 to optimize performance. Using slower models (GPT-5.2, Claude Sonnet 4.5) or high max iterations (50+) will cause sub-agents to execute slowly—each sub-agent call could take 60-90 seconds instead of 10-15 seconds.
+Sub-agents inherit the LLM provider, model, resource tier, and max iterations from the root agent. This tutorial uses GPT-5 Mini and max iterations of 15 to optimize performance. Using slower models (GPT-5.2, Claude Sonnet 4.5) or high max iterations (50+) will cause sub-agents to execute slowly. Each sub-agent call could take 60-90 seconds instead of 10-15 seconds.
 ====
 
 . Go to *Agentic AI* > *AI Agents*.
@@ -229,11 +229,6 @@ Sub-agents inherit the LLM provider, model, resource tier, and max iterations fr
 * *Model*: GPT-5 Mini (fast, cost-effective for structured workflows)
 * *API Key*: Your LLM provider API key
 * *Max Iterations*: 15
-+
-[NOTE]
-====
-This tutorial uses GPT-5 Mini and reduced max iterations to optimize for tutorial speed. Multi-agent investigations typically complete in 30-90 seconds with these settings. For production deployments handling complex edge cases, consider GPT-5.2 or Claude Sonnet 4.5 with higher max iterations.
-====
 
 . In the *System Prompt* field, enter:
 +
@@ -521,7 +516,7 @@ The Service Account is required for the `a2a_message` processor to authenticate
 . Name the pipeline `dispute-pipeline`.
 . Paste this configuration:
 +
-[,yaml]
+[,yaml,role="no-placeholders"]
 ----
 include::ai-agents:example$pipelines/dispute-pipeline.yaml[]
 ----
diff --git a/modules/ai-agents/pages/mcp/remote/create-tool.adoc b/modules/ai-agents/pages/mcp/remote/create-tool.adoc
@@ -6,7 +6,7 @@
 // Learning objectives - what readers can do after reading this page:
 :learning-objective-1: Create a tool with the correct structure and MCP metadata
 :learning-objective-2: Map MCP parameters to component configuration fields using Bloblang
-:learning-objective-3: Test tools using the MCP inspector
+:learning-objective-3: Test tools using the MCP Inspector
 
 After xref:ai-agents:mcp/remote/quickstart.adoc[deploying your first MCP server], create custom tools that AI clients can discover and invoke. This guide walks you through the process using any Redpanda Connect component.
 
diff --git a/modules/ai-agents/pages/mcp/remote/monitor-mcp-servers.adoc b/modules/ai-agents/pages/mcp/remote/monitor-mcp-servers.adoc
@@ -71,7 +71,7 @@ Example: Find all invocations of a specific tool:
 [,bash]
 ----
 rpk topic consume redpanda.otel_traces --offset start \
-  | jq 'select(.instrumentationScope.name == "rpcn-mcp" and .name == "weather")'
+  | jq '.value | select(.instrumentationScope.name == "rpcn-mcp" and .name == "weather")'
 ----
 
 === Measure performance
diff --git a/modules/develop/pages/connect/cookbooks/jira.adoc b/modules/develop/pages/connect/cookbooks/jira.adoc
@@ -7,7 +7,8 @@
 :learning-objective-2: Combine generate input with Jira processor for scheduled queries
 :learning-objective-3: Create Jira issues using the HTTP processor and REST API
 
-The Jira processor enables querying Jira issues using JQL (Jira Query Language) and returning structured data. Unlike traditional connectors, the Jira processor only supports queries and can be used as both an input (with `generate`) and an output (with `drop`).
+The Jira processor enables querying Jira issues using JQL (Jira Query Language) and returning structured data. It’s a processor, so you can use it in pipelines for input-style flows (pair with `generate`) or output-style flows (pair with `drop`).
+
 
 Use this cookbook to:
 

Original file line number	Diff line number	Diff line change
`@@ -1,9 +1,7 @@`
`1`	`1`	`label: get_order_status`
`2`		`-`
`3`		`-processors:`
`4`		`- - mapping: \|`
`5`		`- let order_id = this.order_id`
`6`		`- root = if $order_id == "ORD-12345" {`
	`2`	`+mapping: \|`
	`3`	`+ let order_id = this.order_id`
	`4`	`+ root = if $order_id == "ORD-12345" {`
`7`	`5`	`{`
`8`	`6`	`"order_id": $order_id,`
`9`	`7`	`"status": "shipped",`
`@@ -23,7 +21,7 @@ processors:`
`23`	`21`	`}`
`24`	`22`	`} else if $order_id == "ORD-99999" {`
`25`	`23`	`{`
`26`		`- "error": true,`
	`24`	`+ "error": "order_not_found",`
`27`	`25`	`"message": "Order not found"`
`28`	`26`	`}`
`29`	`27`	`} else {`