AI agents #487
AI agents #487
Conversation
- Fix period usage in numbered steps and bold labels across all AI agent docs - Add descriptive link text to xref anchor links for better accessibility - Redesign monitor-agents.adoc reducing lists from 9 to 2, converting to prose and tables - Create observability index page - Fix broken xref from billing.adoc to observability/concepts.adoc
📝 WalkthroughWalkthroughThis pull request introduces comprehensive AI agents and MCP tooling documentation, examples, and infrastructure updates for Redpanda Cloud. Changes include new agent prompt specifications for a multi-agent dispute resolution system, extensive MCP tool examples across inputs/outputs/processors/caches, event-driven pipeline configurations, updated CI/CD workflows to test MCP and pipeline examples, restructured navigation and personas documentation, and 40+ new documentation pages covering agent concepts, architecture patterns, best practices, tutorials, and MCP server management. The persona system is reorganized into tiered levels with new personas like executive, security_leader, ai_platform_engineer, agent_developer, knowledge_manager, and business_user. Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Warning Review ran into problems🔥 ProblemsErrors were encountered while retrieving linked issues. Errors (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Change negative headings to positive action-oriented headings - Add explicit 'Enter this query' instructions for each test scenario - Add guidance on what to watch for in the conversation panel - Specify when to start new sessions for context clearing
Moved monitoring how-tos into context where users need them: - Monitor Agents now in agents section - Monitor MCP Servers now in mcp/remote section - Observability concepts remain centralized as single source of truth This follows the "procedures in context, concepts centralized" pattern, reducing navigation overhead and improving task completion. Also removed unnecessary observability index page since only one page remains in that section. Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
Sessions and tasks topics are being soft-hidden with __ prefix as they are internal implementation details. Updated documentation to focus on user-facing monitoring features (transcripts and inspector). Changes: - Remove "Agent data topics" section from concepts.adoc with schemas - Remove "Consume agent data topics" section from monitor-agents.adoc - Update troubleshooting.adoc to reference transcripts instead of topics - Update learning objective to "Track token usage and performance metrics" - Fix xref anchor links to include descriptive text - Fix shipping carrier name to comply with Google style guide Co-Authored-By: Claude Sonnet 4.5 <[email protected]>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
modules/ai-agents/pages/agents/a2a-concepts.adoc (1)
238-238: Fix broken anchor reference.The reference to
#agent-card-metadataanchor does not exist in thecreate-agent.adocfile. The A2A configuration section increate-agent.adoc(lines 205-238) does not define an anchor with this ID.Suggested fix
Either add the missing anchor in
create-agent.adocor update this reference to point to the correct section. If the intent is to reference the entire A2A configuration section:-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 agent cards and discovery, see xref:ai-agents:agents/a2a-concepts.adoc#agent-cards[Agent cards].
🤖 Fix all issues with AI agents
In `@modules/ai-agents/examples/mcp-tools/inputs/stream_processing.yaml`:
- Around line 6-23: The processors block is incorrectly nested inside the
redpanda input; move the processors key out so it is a sibling of the redpanda
input (i.e., configure input-level processors as input.processors). Concretely:
remove the processors: block from under redpanda and add a processors: entry at
the same top-level indentation as redpanda containing the existing mapping: |
payload (the mapping that references root.sensor_id, avg_temperature,
max_temperature, reading_count, window_end) so the mapping block remains
unchanged but lives under the sibling processors key.
In
`@modules/ai-agents/examples/mcp-tools/processors/check_regulatory_requirements.yaml`:
- Around line 3-6: The MCP schema in meta.mcp.properties is out of sync with the
mapping in root = match which branches on this.dispute_type; update the MCP to
include a required dispute_type property (and remove or reconcile
transaction_type, amount, jurisdiction) or alternatively change the match
branches to use the declared properties (transaction_type, amount, jurisdiction)
so the mapping and interface agree; ensure the required field dispute_type is
documented in meta.mcp.required and the mapping branches (the this.dispute_type
checks) are updated accordingly across the file (also apply the same alignment
for the later block around lines 108-124).
In `@modules/ai-agents/examples/mcp-tools/processors/get_merchant_category.yaml`:
- Around line 82-90: The MCP schema and description currently declare
merchant_name but the processor uses this.mcc, causing a mismatch; either update
the schema to accept an MCC input (replace or add a required property named mcc:
string and change description to indicate MCC code input) so it matches the
processor's usage of this.mcc, or modify the processor logic (functions
referencing this.mcc) to accept this.merchant_name and implement/ call a lookup
to derive MCC from merchant_name; pick one approach and keep symbols consistent
(merchant_name vs mcc) across the YAML properties and the processor code.
In `@modules/ai-agents/examples/mcp-tools/processors/log_audit_event.yaml`:
- Around line 7-14: Add the missing MCP property definitions for risk_score,
evidence, and outcome in the meta.mcp.properties section so consumers know to
provide them; specifically, update the meta.mcp.properties block to include
entries for "risk_score" (number or integer), "evidence" (array or string
depending on expected structure), and "outcome" (string or enum) to match how
they are referenced in the mapping (this.risk_score, this.evidence,
this.outcome) and ensure types and descriptions align with the mapping usage in
log_audit_event.yaml.
In `@modules/ai-agents/examples/pipelines/dispute-pipeline.yaml`:
- Around line 116-145: The mapping calls this.agent_investigation.exists(...)
multiple times without guarding that agent_investigation may be absent;
introduce a single let (e.g., let has_agent_investigation =
this.agent_investigation != null && this.agent_investigation.exists(...?) or
simply this.agent_investigation != null) at the top of the Bloblang snippet and
reuse it when computing root.final_decision, root.alert_level and the
"agent_invoked" field in root.pipeline_metadata so all accesses to
agent_investigation are guarded and .exists() is never invoked on a missing
object (refer to symbols: agent_investigation, root.final_decision,
root.alert_level, root.pipeline_metadata).
In `@modules/ai-agents/examples/pipelines/fraud-detection-routing.yaml`:
- Around line 33-40: The pipeline stores the raw agent response bytes into
root.fraud_analysis using root.fraud_analysis = content(), but mapping later
reads this.fraud_analysis.fraud_score expecting a parsed object; update the
result_map to parse the JSON (e.g., decode the content bytes into an object)
with error handling and a safe fallback so parsing failures don't break routing,
ensure the parsed object is assigned to root.fraud_analysis and keep the
downstream mapping that references meta fraud_score =
this.fraud_analysis.fraud_score intact so routing can read the value.
In `@modules/ai-agents/examples/pipelines/test-pipelines.sh`:
- Around line 71-85: The else branch currently treats unknown lint errors as
cloud warnings and increments CLOUD_PROCESSOR_ERRORS; instead, mark these as
real failures so CI fails: in the else branch (the block that now echoes WARNING
and increments CLOUD_PROCESSOR_ERRORS), change it to echo the RED FAILED
message, print the full output (like the YAML error branch) and increment FAILED
(not CLOUD_PROCESSOR_ERRORS). Keep the visual formatting (colors) and output
indentation but replace CLOUD_PROCESSOR_ERRORS=$((CLOUD_PROCESSOR_ERRORS + 1))
with FAILED=$((FAILED + 1)) so unknown lint errors contribute to test failures.
In
`@modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc`:
- Around line 480-498: The doc currently instructs setting overly-broad ACLs
(e.g., selecting "Allow all" on the Clusters and Consumer groups tabs and using
Host=`*` and Operations=Allow all for Topics) — update the steps to follow
least-privilege: replace "Allow all" at the cluster and consumer-group levels
with only the specific cluster-level operations required, restrict Consumer
group selector to the actual consumer-group prefix used by the pipeline, and for
the Topics entry keep Principal=`dispute-pipeline-user`,
Host=`<specific-host-or-range>`, Resource Type=Topic, Selector=`bank.*` (or
explicit topic names) and only the exact Operations needed
(produce/consume/describe), and add a brief callout/warning about avoiding
wildcard hosts/ops in production and to prefer scoped ACLs.
In `@modules/ai-agents/pages/observability/concepts.adoc`:
- Around line 268-273: Update the documentation entry for status.code so it
reflects OpenTelemetry's actual enum: change the text under `status.code` from
"`0` means success, `2` means error" to indicate that `0` is UNSET (default, no
explicit status), `1` is OK (success), and `2` is ERROR; update the bullet that
mentions `status.code` to list these correct mappings and keep the surrounding
explanatory phrasing about status semantics intact.
- Around line 148-149: Update the OTLP JSON example and accompanying text to use
the correct field name and status codes: replace any use of
instrumentationScope.name with scope.name in the JSON example (and any
descriptive text referencing that field) and correct the status.code description
to state that 0 = UNSET (default), 1 = OK (success), and 2 = ERROR; adjust the
text near scope.name and the JSON example to match the OTLP OTLP/OTLP JSON wire
format specification exactly (search for occurrences of
instrumentationScope.name and status.code in the content around the example to
update).
🟡 Minor comments (11)
modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc-216-236 (1)
216-236: Align investigation time claims across sections.
Here you say investigations are “30–90 seconds” and sub-agent calls can take “60–90 seconds,” but later the transcript duration is “typically 5–15 seconds.” Please reconcile or qualify (for example, “with mock tools” vs “production APIs”), to avoid reader confusion.Also applies to: 398-401
modules/ai-agents/examples/mcp-tools/snippets/defaults.yaml-5-19 (1)
5-19: Documentlimitin the properties schema.
Line 7 setsroot.limit, but thepropertiesblock doesn’t definelimit, which can confuse consumers and schema-driven tooling.🔧 Suggested update
properties: - name: city type: string description: "City name to look up" required: true - name: units type: string description: "Temperature units: 'metric' or 'imperial' (default: metric)" required: false + - name: limit + type: number + description: "Max results (default: 10)" + required: falsemodules/ai-agents/examples/mcp-tools/snippets/bloblang_this_context.yaml-10-14 (1)
10-14: Fixargs_mappingsyntax: addroot =before the array expression.Line 14 shows an incomplete Bloblang expression. Arrays must be assigned to root using
root = [...]syntax. All working examples in the codebase (customer_enrichment.yaml, gcp_bigquery_select_processor.yaml) follow this pattern.Required fix
sql_select: table: orders where: customer_id = ? AND status = ? - args_mapping: '[this.customer_id, this.status.or("active")]' + args_mapping: 'root = [this.customer_id, this.status.or("active")]'modules/ai-agents/examples/mcp-tools/processors/calculate_fraud_score.yaml-71-83 (1)
71-83: Document all required input fields in MCP metadata.
The mapping depends on transaction, customer, reputation, and velocity fields, but the schema only lists IDs. That weakens tool discovery and makes the example harder to use.📌 Suggested metadata expansion
mcp: enabled: true description: "Calculate fraud risk score based on transaction patterns and risk indicators. Returns risk level and recommendation." properties: + - name: transaction + type: object + description: "Transaction details including amount, location, merchant, and transaction_id" + required: true + - name: customer + type: object + description: "Customer profile including location, primary_city, avg_transaction, and typical_categories" + required: true + - name: merchant_reputation + type: number + description: "Merchant reputation score (0-100)" + required: true + - name: recent_transactions_count + type: integer + description: "Recent transaction count used for velocity checks" + required: true - name: transaction_id type: string description: "Transaction identifier to analyze (format TXN-XXXXX)" required: true - name: customer_id type: string description: "Customer identifier for historical analysis (format CUST-XXXX)" required: truemodules/ai-agents/examples/mcp-tools/processors/openai_chat.yaml-6-16 (1)
6-16: Consider using raw text interpolation for feedback instead of JSON encoding.The
json()function can add unwanted quotes or escape characters inside the prompt. Use${! this.feedback_text }instead of${! json("feedback_text") }to pass the feedback as plain text.The model
gpt-5.2is a current OpenAI model and does not require updating. While parameterizing the model for flexibility is a valid design pattern, it is not necessary for this configuration.modules/ai-agents/examples/mcp-tools/processors/transform_validate.yaml-16-17 (1)
16-17: Optionalprofilefield breaks mapping when absent.
profileis marked optional, butthis.profile.without(...)fails when called on null. Guard with.or({})per Bloblang idiom.🐛 Proposed fix
- root.profile = this.profile.without("ssn", "credit_card") + root.profile = this.profile.or({}).without("ssn", "credit_card")modules/ai-agents/examples/mcp-tools/processors/get_weather_complete.yaml-14-14 (1)
14-14: Unusedunitsparameter.The
unitsproperty is accepted and defaulted to "metric" (line 14) and documented in the MCP properties (lines 51-54), but it's never used in the HTTP request or response processing. The wttr.in API always returns both Celsius and Fahrenheit in the JSON response.Consider either:
- Removing the
unitsparameter since both temperature values are returned- Using it to filter the response to only the requested unit
Option 2: Use units to select temperature
- mutation: | root.weather = { "location": this.nearest_area.0.areaName.0.value, "country": this.nearest_area.0.country.0.value, - "temperature_c": this.current_condition.0.temp_C, - "temperature_f": this.current_condition.0.temp_F, + "temperature": if root.units == "imperial" { + this.current_condition.0.temp_F + "°F" + } else { + this.current_condition.0.temp_C + "°C" + }, "condition": this.current_condition.0.weatherDesc.0.value, "humidity": this.current_condition.0.humidity, "wind_kph": this.current_condition.0.windspeedKmph }modules/ai-agents/pages/mcp/remote/create-tool.adoc-9-9 (1)
9-9: Align “MCP inspector” casing with the UI label.The learning objective says “MCP inspector,” but the UI label elsewhere in the page still appears capitalized. Please ensure the casing matches the actual console label for consistency.
modules/develop/pages/connect/cookbooks/jira.adoc-10-10 (1)
10-10: Clarify processor placement vs “output” usage.
Line 10 frames the Jira processor as an output, which may confuse readers since it remains a processor even when paired withdrop. Consider a wording tweak to avoid implying it’s an output component.✏️ Suggested wording
-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`)..github/workflows/test-mcp-examples.yaml-53-62 (1)
53-62: Fix shell glob issues in cookbook tests loop.Static analysis correctly identifies two issues:
- Line 56:
-ftest doesn't work with globs - use a nested loop instead- Line 59:
./test-*.shuses a glob as a command, which can fail if multiple files match or none match🔧 Proposed fix using proper glob iteration
- name: Run cookbook tests run: | for dir in modules/develop/examples/cookbooks/*/; do - if [[ -f "${dir}test-"*".sh" ]]; then - echo "Testing ${dir}..." - cd "${dir}" - ./test-*.sh - cd - > /dev/null - fi + for script in "${dir}"test-*.sh; do + if [[ -f "$script" ]]; then + echo "Testing ${dir}..." + cd "${dir}" + ./$(basename "$script") + cd - > /dev/null + break # Run first matching script only + fi + done doneAlternatively, if you intend to run all matching test scripts in a directory:
for dir in modules/develop/examples/cookbooks/*/; do for script in "${dir}"test-*.sh; do [[ -f "$script" ]] && "$script" done donemodules/ai-agents/pages/mcp/remote/monitor-mcp-servers.adoc-71-76 (1)
71-76: Update jq filter to access message value field.The
rpk topic consumecommand wraps each record in a JSON object with metadata fields (partition, offset, etc.); the actual message content is nested under.value. The jq filter needs to be updated to:rpk topic consume redpanda.otel_traces --offset start \ | jq '.value | select(.instrumentationScope.name == "rpcn-mcp" and .name == "weather")'Without the
.valueaccessor, the filter will not find theinstrumentationScopeandnamefields.
🧹 Nitpick comments (26)
modules/ai-agents/examples/mcp-tools/outputs/publish_with_timestamp.yaml (1)
21-24: Consider adding MCP properties to document expected input schema.The
meta.mcpsection lacks property definitions. While outputs may not strictly require them, documenting the expected input structure (e.g., the fields that will be published alongsidepublished_at) would improve discoverability for consumers of this tool.Example: Add properties to document expected input
meta: mcp: enabled: true description: "Add timestamp and publish to Redpanda" + properties: + - name: event_data + type: object + description: "Event payload to publish (published_at timestamp will be added automatically)" + required: truemodules/ai-agents/pages/mcp/remote/best-practices.adoc (1)
40-42: Add descriptive link text for the remaining Next steps items.
The two empty xrefs rely on implicit titles; explicit text keeps consistency and improves scanability.♻️ Proposed tweak
-* xref:ai-agents:mcp/remote/tool-patterns.adoc[] -* xref:ai-agents:mcp/remote/troubleshooting.adoc[] +* xref:ai-agents:mcp/remote/tool-patterns.adoc[MCP tool patterns] +* xref:ai-agents:mcp/remote/troubleshooting.adoc[MCP remote troubleshooting]modules/ai-agents/examples/mcp-tools/inputs/event_driven_workflow.yaml (1)
20-29: AddContent-Type: application/jsonfor the POST bodies.
This avoids silent failures with APIs that require explicit JSON headers.♻️ Suggested headers
- 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 }"}'modules/ai-agents/pages/agents/monitor-agents.adoc (1)
96-103: Avoid hard‑coding model names and per‑token prices in the cost example.
Model SKUs and pricing shift frequently, so this will age quickly. Consider a model‑agnostic example that references the formula rather than fixed vendor pricing.♻️ Suggested tweak
-Example: GPT-5.2 with 4,302 input tokens and 1,340 output tokens at $0.00000175 per input token and $0.000014 per output token costs $0.026 per request. +Example: For 4,302 input tokens and 1,340 output tokens, cost is: +Cost = (4302 × input_price) + (1340 × output_price)modules/ai-agents/pages/agents/troubleshooting.adoc (1)
62-64: Model/version callouts are likely to go stale.
Consider referencing supported model tiers instead of specific versions to keep the doc evergreen.♻️ Suggested tweak
-. 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 workspace. -. 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.Also applies to: 219-221
modules/ai-agents/examples/mcp-tools/processors/get_shipping_info.yaml (1)
12-14: Consider updating example dates.The hardcoded dates (
2025-01-17,2025-01-15) are now in the past. For documentation examples, consider using relative or future-looking dates to avoid reader confusion about whether these are real values.Suggested update
- "estimated_delivery": "2025-01-17", + "estimated_delivery": "2026-02-15", "last_location": "San Francisco Distribution Center", - "last_update": "2025-01-15T14:30:00Z" + "last_update": "2026-02-10T14:30:00Z"modules/ai-agents/pages/agents/integration-overview.adoc (1)
95-97: Clarify latency characteristic.The description "Higher (async acceptable)" may be misleading. Pipeline processing with
a2a_messagecan have variable latency depending on configuration. Consider clarifying:| Latency | Low (agent waits for response) -| Higher (async acceptable) +| Variable (throughput-optimized, batching possible)modules/ai-agents/examples/pipelines/fraud-detection-simple.yaml (1)
5-8: Use an example-specific consumer group to avoid offset collisions.
If users run multiple sample pipelines together, sharingfraud-detectorwill cause partition contention and confusing results. Consider a unique group for this example (Line 7).♻️ Suggested tweak
- consumer_group: fraud-detector + consumer_group: fraud-detector-simplemodules/ai-agents/examples/pipelines/event-driven-invocation.yaml (1)
5-7: Differentiate this example from fraud-detection-simple.
This pipeline uses the same topics and consumer group as the fraud-detection example, so it reads as a duplicate. Consider using generic event names to make the intent obvious (Line 6, Line 7, Line 24).♻️ Suggested tweak
- topics: [transactions] - consumer_group: fraud-detector + topics: [events] + consumer_group: event-invoker ... - topic: fraud-alerts + topic: agent-resultsAlso applies to: 22-24
modules/ai-agents/examples/pipelines/dispute-pipeline.yaml (1)
96-104: Avoid double JSON parsing of the agent response.
The response is parsed twice; store once and reuse to keep behavior consistent and reduce overhead (Line 96).♻️ Suggested tweak
- root.agent_investigation = if content().string().parse_json().catch(null) != null { - content().string().parse_json() + let parsed = content().string().parse_json().catch(null) + root.agent_investigation = if $parsed != null { + $parsed } else { { "recommendation": "manual_review_required", "fraud_score": 50, "confidence": "low", "reasoning": "Agent returned unparseable response: " + content().string().slice(0, 100) } }modules/ai-agents/examples/pipelines/streaming-enrichment.yaml (1)
18-23: Consider using.string()for clarity when storing agent responses. Whilecontent()may serialize directly, the pattern shown in similar examples (like dispute-pipeline.yaml) explicitly usescontent().string()when capturing agent output. For a sentiment field receiving text-based agent responses, using.string()makes the intent explicit and ensures proper serialization.♻️ Suggested improvement
- result_map: 'root.sentiment = content()' + result_map: 'root.sentiment = content().string()'modules/ai-agents/pages/agents/overview.adoc (1)
36-38: Consider reformatting dense benefits paragraph as a list.Line 38 packs five distinct benefits into a single long sentence, which reduces readability. Since this is an overview page introducing the platform, the benefits section would be clearer as a bulleted list.
♻️ Suggested format improvement
== 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 +* Remote MCP support for standardized tool access +* Managed infrastructure that handles deployment, scaling, and security +* Low-latency execution with tools running close to your data +* Integrated secrets management for API keys and credentialsmodules/ai-agents/examples/agents/compliance-agent-prompt.txt (1)
24-28: Add the unlimited liability scenario for Regulation E completeness.The omission of unlimited liability for customers who fail to report unauthorized transactions within 60 days is a material gap in the compliance guidance. Regulation E specifies three distinct liability tiers: $50 (within 2 days), up to $500 (within 60 days), and unlimited liability for transfers occurring after 60 days without notification.
Recommend updating line 26 to include the full liability framework:
- Customer liability: $50 if reported within 2 days, $500 if reported within 60 days, unlimited if reported after 60 daysmodules/ai-agents/pages/agents/pipeline-integration-patterns.adoc (1)
52-52: Consider consolidating placeholder replacement instructions.The instruction "Replace
AGENT_CARD_URLwith your actual agent card URL" appears 6 times throughout the page. While each occurrence provides context-specific guidance, you could reduce repetition by:
- Adding a single admonition block at the top of the "Use cases" section (before line 40) explaining the placeholder once
- Simplifying the repeated instructions to just reference that block
This is a minor readability improvement and not required.
Example consolidation approach
Add after line 41:
[NOTE] ==== All examples in this section use `AGENT_CARD_URL` as a placeholder. Replace it with your actual agent card URL. See xref:ai-agents:agents/a2a-concepts.adoc#agent-card-location[Agent card location]. ====Then simplify each occurrence to just:
**Use case:** Real-time fraud detection on every transaction.Also applies to: 65-65, 78-78, 91-91, 104-104, 129-129
modules/ai-agents/pages/agents/create-agent.adoc (1)
205-238: Consider adding an anchor for the A2A configuration section.The A2A configuration section is referenced from
a2a-concepts.adocbut lacks an anchor ID. While the reference ina2a-concepts.adocneeds to be fixed (already flagged), adding a clear anchor here would enable more precise cross-referencing.Suggested anchor addition
+[`#configure-a2a-metadata`] == Configure A2A discovery metadata (optional)This allows other pages to reference this specific section with
#configure-a2a-metadata.modules/ai-agents/examples/mcp-tools/processors/get_transaction_details.yaml (1)
10-13: Normalize country formatting across merchant and location fields.Merchant countries use full names while
location.countryuses ISO codes, which can confuse readers about the intended schema. Consider standardizing to a single format in the example.♻️ Suggested normalization (ISO-3166-1 alpha-2)
- "country": "Singapore", + "country": "SG", ... - "country": "USA", + "country": "US", ... - "country": "USA", + "country": "US", ... - "country": "France", + "country": "FR",Also applies to: 30-33, 50-53, 71-74
modules/develop/examples/cookbooks/jira/input-periodic.yaml (1)
4-8: Consider aligning poll interval and JQL window to reduce duplicates.With a 30s interval and
updated >= -1h, this example re-fetches a large overlapping window each poll. Consider narrowing the window to better match the poll interval (or lengthen the interval) to reduce duplicate processing and API load.♻️ Example adjustment (verify JQL syntax for relative times)
- interval: 30s + interval: 5m mapping: | - root.jql = "project = MYPROJECT AND updated >= -1h ORDER BY updated DESC" + root.jql = "project = MYPROJECT AND updated >= -5m ORDER BY updated DESC"modules/ai-agents/pages/mcp/remote/scale-resources.adoc (1)
54-66: Consider documenting the mapping between named sizes and API resource values.The Cloud Console section lists named sizes (XSmall, Small, Medium, Large, XLarge), but the API example uses raw values (
memory_shares: "2Gi",cpu_shares: "1000m") without indicating which named size these correspond to. Adding a reference table or inline note would help users understand the equivalence.modules/develop/examples/cookbooks/jira/test-jira-examples.sh (1)
28-42: Optional: Enablenullglobto handle empty directories gracefully.If the directory contains no
.yamlfiles, the glob expands to the literal string*.yaml. While the-f "$file"check prevents errors, enablingnullglobmakes the intent clearer:♻️ Suggested improvement
+shopt -s nullglob for file in *.yaml; do if [[ -f "$file" ]]; thenmodules/ai-agents/examples/mcp-tools/processors/get_order_status.yaml (1)
1-48: LGTM overall, but note the structural inconsistency with sibling files.This file uses
processors: - mapping:(lines 3-4) whileget_customer_account.yamluses a top-levelmapping:directly. Both are valid, but for documentation examples that users may learn from, consistency aids comprehension.Additionally, the error response structure differs:
- Here:
"error": true(boolean)- In
get_customer_account.yaml:"error": "customer_not_found"(string)Consider standardizing these patterns across MCP tool examples if they're intended to demonstrate consistent practices.
modules/ai-agents/examples/mcp-tools/processors/get_risk_indicators.yaml (1)
58-111: Consider counting low/none severities for consistency.
Some indicators uselow/none, but summary fields only count critical/high/medium. If consumers rely on counts, consider addinglow_count/none_countor clarify that counts only track higher severities.modules/ai-agents/examples/mcp-tools/processors/verify_merchant.yaml (1)
101-108: Keep response shape consistent in the fallback branch.
The default branch omits fields returned in other cases, which can force clients to handle multiple schemas. Consider adding empty placeholders forfraud_reports,business_details, andred_flagsto keep the response shape stable.♻️ Suggested fallback shape
_ => { "merchant_name": this.merchant_name, "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" }modules/ai-agents/examples/mcp-tools/test-mcp-tools.sh (1)
109-171: Handle case when glob pattern matches no files.When iterating with
for file in "$dir"/*.yaml, if no YAML files exist in the directory, the loop iterates once with the literal string"$dir"/*.yaml. The-f "$file"check on line 112 handles this, but consider usingnullglobfor cleaner iteration.Additionally, embedding the shell variable
$filedirectly into Python code (lines 124, 135, 146) could cause issues if the filename contains quotes or special characters.♻️ Suggested improvements
Add
shopt -s nullglobbefore the loops to prevent iterating over non-matching patterns:if $RUN_METADATA; then + shopt -s nullglob for dir in "${COMPONENT_DIRS[@]}"; do if [[ -d "$dir" ]]; then for file in "$dir"/*.yaml; do - if [[ -f "$file" ]]; then + # With nullglob, loop only runs for actual filesFor safer Python variable passing, consider using environment variables or properly escaped arguments:
- mcp_exists=$(python3 -c " -import yaml -try: - with open('$file') as f: + mcp_exists=$(python3 -c " +import yaml, os, sys +try: + with open(sys.argv[1]) as f: doc = yaml.safe_load(f) -" 2>/dev/null) +" "$file" 2>/dev/null)modules/ai-agents/pages/mcp/local/quickstart.adoc (1)
14-14: Add descriptive link text for the MCP remote quickstart.Empty xref text makes the link unclear in rendered output. Consider labeling it for clarity.
💡 Suggested tweak
-If you're trying to deploy your own MCP server as a managed service inside your cluster, see xref:ai-agents:mcp/remote/quickstart.adoc[]. +If you're trying to deploy your own MCP server as a managed service inside your cluster, see xref:ai-agents:mcp/remote/quickstart.adoc[Remote MCP quickstart].modules/ai-agents/pages/mcp/local/overview.adoc (1)
69-70: Provide link text for Next steps entries.The xrefs render without descriptive text, which hurts skimmability.
💡 Suggested tweak
-* xref:ai-agents:mcp/local/quickstart.adoc[] -* xref:ai-agents:mcp/local/configuration.adoc[] +* xref:ai-agents:mcp/local/quickstart.adoc[Quickstart] +* xref:ai-agents:mcp/local/configuration.adoc[Configure the MCP server]modules/ai-agents/pages/agents/tutorials/customer-support-agent.adoc (1)
209-210: Consider linking to official model documentation for future-proofing.Both OpenAI GPT-5.2 and Claude Sonnet 4.5 are currently supported models. However, since model names and availability change frequently (e.g., Anthropic retired Claude 3-Opus in January 2026), linking to official model lists would improve long-term documentation sustainability and ensure readers always have access to the latest available options.
modules/ai-agents/examples/mcp-tools/processors/check_regulatory_requirements.yaml
Show resolved
Hide resolved
modules/ai-agents/examples/mcp-tools/processors/get_merchant_category.yaml
Show resolved
Hide resolved
modules/ai-agents/examples/mcp-tools/processors/log_audit_event.yaml
Outdated
Show resolved
Hide resolved
| result_map: | | ||
| root = this | ||
| root.fraud_analysis = content() | ||
| - mapping: | | ||
| root = this | ||
| meta fraud_score = this.fraud_analysis.fraud_score | ||
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -name "fraud-detection-routing.yaml" -type fRepository: redpanda-data/cloud-docs
Length of output: 135
🏁 Script executed:
cat -n modules/ai-agents/examples/pipelines/fraud-detection-routing.yamlRepository: redpanda-data/cloud-docs
Length of output: 2917
🏁 Script executed:
# Search for other pipeline files to understand context and patterns
find modules/ai-agents/examples/pipelines -name "*.yaml" -type fRepository: redpanda-data/cloud-docs
Length of output: 575
🏁 Script executed:
# Search for other uses of content() in this repo
rg "content()" modules/ai-agents/examples/pipelines/ -A 3 -B 3Repository: redpanda-data/cloud-docs
Length of output: 5232
🏁 Script executed:
# Search for a2a_message or similar processor documentation
rg "a2a_message" modules/ai-agents/ -A 5 -B 2Repository: redpanda-data/cloud-docs
Length of output: 23343
🏁 Script executed:
# Look for README or documentation about the AI agents module
find modules/ai-agents -name "README*" -o -name "*.md" | head -10Repository: redpanda-data/cloud-docs
Length of output: 50
🏁 Script executed:
cat -n modules/ai-agents/examples/pipelines/fraud-detection-simple.yamlRepository: redpanda-data/cloud-docs
Length of output: 1069
🏁 Script executed:
# Get the exact syntax from dispute-pipeline.yaml for parsing and fallback
cat -n modules/ai-agents/examples/pipelines/dispute-pipeline.yaml | sed -n '50,70p'Repository: redpanda-data/cloud-docs
Length of output: 1029
🏁 Script executed:
# Search for other parsing patterns with let statements
rg "let parsed" modules/ai-agents/examples/pipelines/ -A 5 -B 2Repository: redpanda-data/cloud-docs
Length of output: 50
🏁 Script executed:
# Get the exact parsing pattern from dispute-pipeline.yaml
cat -n modules/ai-agents/examples/pipelines/dispute-pipeline.yaml | sed -n '73,90p'Repository: redpanda-data/cloud-docs
Length of output: 1254
🏁 Script executed:
# Get lines around the parsing logic in dispute-pipeline.yaml
cat -n modules/ai-agents/examples/pipelines/dispute-pipeline.yaml | sed -n '91,115p'Repository: redpanda-data/cloud-docs
Length of output: 1254
Parse agent response before reading fraud_score.
root.fraud_analysis = content() stores the raw agent response as bytes; the following mapping expects a parsed JSON object, so fraud_score will be null and routing logic will not work. Parse the JSON response with error handling to ensure routing proceeds correctly (lines 35, 39).
🐛 Proposed fix
result_map: |
root = this
- root.fraud_analysis = content()
+ let parsed = content().string().parse_json().catch(null)
+ root.fraud_analysis = if $parsed != null {
+ $parsed
+ } else {
+ { "fraud_score": 0, "reason": "unparseable", "recommend_block": false }
+ }
- mapping: |
root = this
meta fraud_score = this.fraud_analysis.fraud_score🤖 Prompt for AI Agents
In `@modules/ai-agents/examples/pipelines/fraud-detection-routing.yaml` around
lines 33 - 40, The pipeline stores the raw agent response bytes into
root.fraud_analysis using root.fraud_analysis = content(), but mapping later
reads this.fraud_analysis.fraud_score expecting a parsed object; update the
result_map to parse the JSON (e.g., decode the content bytes into an object)
with error handling and a safe fallback so parsing failures don't break routing,
ensure the parsed object is assigned to root.fraud_analysis and keep the
downstream mapping that references meta fraud_score =
this.fraud_analysis.fraud_score intact so routing can read the value.
modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc
Show resolved
Hide resolved
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Description
Establishes comprehensive documentation for Redpanda AI Agents, a new feature enabling LLM-powered agents with MCP tool integration and streaming pipeline orchestration.
Also adds automated testing/linting for example MCP servers and pipelines:
mcp-tools/: Tool configurations (processors, inputs, outputs, caches)pipelines/: Pipeline integration patterns (fraud detection, enrichment, multi-agent orchestration)Page previews
https://deploy-preview-487--rp-cloud.netlify.app/redpanda-cloud/ai-agents/agents/quickstart/
Checks