Remove sessions and tasks topics from agent documentation

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 <noreply@anthropic.com>

Author: JakeSCahill

modules/ai-agents/examples/mcp-tools/processors/get_shipping_info.yaml

@@ -7,7 +7,7 @@ processors:
         {
           "order_id": $order_id,
           "tracking_number": "FX1234567890",
-          "carrier": "FedEx",
+          "carrier": "Example Shipping",
           "status": "in_transit",
           "estimated_delivery": "2025-01-17",
           "last_location": "San Francisco Distribution Center",

modules/ai-agents/examples/mcp-tools/processors/order_workflow.yaml

@@ -39,7 +39,7 @@ processors:
               root = this.merge({
                 "processing_tier": "premium",
                 "processing_time_estimate": "2-4 hours",
-                "assigned_rep": "premium-team@company.com",
+                "assigned_rep": "premium-team@example.com",
                 "priority_score": 95
               })
 
@@ -51,7 +51,7 @@ processors:
               root = this.merge({
                 "processing_tier": "vip",
                 "processing_time_estimate": "1-2 hours",
-                "assigned_rep": "vip-team@company.com",
+                "assigned_rep": "vip-team@example.com",
                 "priority_score": 90,
                 "perks": ["expedited_shipping", "white_glove_service"]
               })
@@ -63,7 +63,7 @@ processors:
               root = this.merge({
                 "processing_tier": "standard",
                 "processing_time_estimate": "24-48 hours",
-                "assigned_rep": "support@company.com",
+                "assigned_rep": "support@example.com",
                 "priority_score": 50
               })
 

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

@@ -23,10 +23,10 @@ Agents that implement A2A expose their capabilities through a standardized agent
 
 The protocol provides:
 
-* **Standardized discovery:** Agent cards describe capabilities in a machine-readable format.
-* **Platform independence:** Any system can call any A2A-compliant agent.
-* **Version negotiation:** Protocol versions ensure compatibility between agents.
-* **Communication mode flexibility:** Supports synchronous request/response and streaming.
+* Standardized discovery: Agent cards describe capabilities in a machine-readable format.
+* Platform independence: Any system can call any A2A-compliant agent.
+* Version negotiation: Protocol versions ensure compatibility between agents.
+* Communication mode flexibility: Supports synchronous request/response and streaming.
 
 For the complete specification, see link:https://a2a.ag/spec[a2a.ag/spec^].
 
@@ -49,10 +49,10 @@ The `.well-known` path follows internet standards for service discovery, making
 
 An agent card describes:
 
-* **Agent capabilities:** Skills and tools the agent provides.
-* **Input/output formats:** Expected request and response structures.
-* **Protocol version:** A2A specification version the agent supports.
-* **Communication modes:** Whether the agent supports synchronous calls, streaming, or both.
+* Agent capabilities: Skills and tools the agent provides.
+* Input/output formats: Expected request and response structures.
+* Protocol version: A2A specification version the agent supports.
+* Communication modes: Whether the agent supports synchronous calls, streaming, or both.
 
 Example agent card structure:
 
@@ -89,19 +89,13 @@ For integration pattern guidance, see xref:ai-agents:agents/integration-overview
 
 === Internal pipeline-to-agent integration
 
-Redpanda Connect pipelines use the xref:develop:connect/components/processors/a2a_message.adoc[`a2a_message`] processor to invoke agents for each event in a stream:
-
-----
-Redpanda Connect Pipeline sends events to a2a_message (A2A) which invokes Redpanda Cloud Agent
-----
-
-Use cases:
+Redpanda Connect pipelines use the xref:develop:connect/components/processors/a2a_message.adoc[`a2a_message`] processor to invoke agents for each event in a stream. This enables real-time interaction between streaming data and AI agents, enabling use cases like:
 
 * Real-time fraud detection on every transaction.
 * Streaming data enrichment with AI-generated fields.
 * Event-driven agent invocation for automated processing.
 
-The xref:develop:connect/components/processors/a2a_message.adoc[`a2a_message`] processor uses A2A protocol internally to discover and call agents. For pipeline patterns, see xref:ai-agents:agents/pipeline-integration-patterns.adoc[].
+The `a2a_message` processor uses the A2A protocol internally to discover and call agents. For pipeline patterns, see xref:ai-agents:agents/pipeline-integration-patterns.adoc[].
 
 == How agents discover each other
 
@@ -133,9 +127,9 @@ External callers use these credentials to obtain access tokens:
 
 This flow ensures:
 
-* **Credentials stay secure:** Applications never send them directly to agents, only access tokens.
-* **Exposure is limited:** Tokens expire, reducing the window for compromised credentials.
-* **Integration is standard:** Applications can use existing OAuth2 libraries.
+* Credentials stay secure: Applications never send them directly to agents, only access tokens.
+* Exposure is limited: Tokens expire, reducing the window for compromised credentials.
+* Integration is standard: Applications can use existing OAuth2 libraries.
 
 === External integration
 
@@ -153,6 +147,6 @@ The A2A protocol uses semantic versioning (major.minor.patch). Agents declare th
 
 == Next steps
 
-* xref:ai-agents:agents/integration-overview.adoc[]: Choose the right integration pattern for your use case
-* xref:ai-agents:agents/create-agent.adoc[]: Create an agent that exposes an A2A agent card
-* link:https://a2a.ag/spec[A2A Protocol Specification^]: Complete technical reference
+* xref:ai-agents:agents/integration-overview.adoc[]
+* xref:ai-agents:agents/create-agent.adoc[]
+* link:https://a2a.ag/spec[A2A Protocol Specification^]

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

@@ -18,14 +18,10 @@ After reading this page, you will be able to:
 
 Agent architecture determines how you manage complexity as your system grows. The right pattern depends on your domain complexity, organizational structure, and how you expect requirements to evolve.
 
-=== When simple agents become unmaintainable
-
-Single agents work well initially but break down as complexity grows.
+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.
 
-=== Domain complexity drives architecture
-
 Match agent architecture to domain structure:
 
 [cols="2,3,3"]
@@ -45,7 +41,6 @@ Match agent architecture to domain structure:
 | Organizational boundaries require system boundaries
 |===
 
-=== Trade-offs
 
 Every architecture pattern involves trade-offs.
 
@@ -131,33 +126,6 @@ External A2A lets different teams own and deploy their agents independently, wit
 
 External A2A adds network latency on every cross-agent call, and authentication complexity multiplies with each agent requiring credential management. Removing capabilities or changing contracts requires coordination across consuming systems, and debugging requires tracing requests across organizational boundaries.
 
-=== Choosing between patterns
-
-[cols="1,2,2"]
-|===
-| Use Case | Internal Subagents | External A2A
-
-| Domain separation within one team
-| Recommended
-| Unnecessary complexity
-
-| Cross-organization workflows
-| Not possible
-| Required
-
-| Shared infrastructure acceptable
-| Simpler
-| Use external if independence needed
-
-| Different deployment requirements
-| Limited (same cluster)
-| Full flexibility
-
-| Real-time performance critical
-| Lower latency
-| Higher latency
-|===
-
 For implementation details on external A2A integration, see xref:ai-agents:agents/integration-overview.adoc[].
 
 == Common anti-patterns
@@ -252,31 +220,10 @@ Use retry logic for transient failures like network timeouts. Report permanent f
 
 Provide clear error messages to users. Log errors for debugging.
 
-== Summary
-
-Choose architecture patterns based on domain complexity and organizational needs:
-
-[cols="1,2,2"]
-|===
-| Pattern | Use When | Trade-off
-
-| Single agent
-| Narrow domain, single organization
-| Limited scalability
-
-| Internal subagents
-| Complex domains, shared infrastructure
-| Higher operational complexity
-
-| External A2A
-| Multi-organization, independent systems
-| Network latency, coordination overhead
-|===
-
 == Next steps
 
-* xref:ai-agents:agents/integration-overview.adoc[]: Choose between agents invoking tools and pipelines calling agents
-* xref:ai-agents:agents/a2a-concepts.adoc[]: Learn how the A2A protocol enables agent communication
-* xref:ai-agents:mcp/remote/tool-patterns.adoc[]: Explore tool design patterns
-* xref:ai-agents:agents/overview.adoc[]: Review agent components
-* xref:ai-agents:mcp/remote/best-practices.adoc[]: Learn MCP tool best practices
+* xref:ai-agents:agents/integration-overview.adoc[]
+* xref:ai-agents:agents/a2a-concepts.adoc[]
+* xref:ai-agents:mcp/remote/tool-patterns.adoc[]
+* xref:ai-agents:agents/overview.adoc[]
+* xref:ai-agents:mcp/remote/best-practices.adoc[]

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

@@ -133,8 +133,6 @@ The agent's context includes the system prompt (always present), user messages,
 
 Agents persist conversation context within a session. When you use the *Inspector* tab in the Redpanda Cloud Console, it automatically maintains session state across multiple requests. For programmatic access, applications must pass a session ID to maintain conversation continuity across requests.
 
-All conversation data is stored in the agent's sessions topic. For details on accessing conversation history, see <<agent-data-topics>>.
-
 === Context window limits
 
 LLM context windows limit how much history fits. Small models support 8K-32K tokens, medium models support 32K-128K tokens, and large models support 128K-1M+ tokens.
@@ -145,120 +143,13 @@ Design workflows to complete within context limits. Avoid unbounded tool chainin
 
 === State across conversations
 
-Redpanda Cloud automatically persists conversation history and task execution data to agent-specific topics:
-
-* *Sessions topic* (`redpanda.aiagent.<agent-id>.sessions`): Stores all conversation messages and history
-* *Tasks topic* (`redpanda.aiagent.<agent-id>.tasks`): Stores task execution records with status and artifacts
-
-The *Inspector* tab automatically manages sessions for you. For programmatic integration, pass a session ID in API requests to maintain conversation continuity.
-
-You can consume from these topics to:
-
-* Review past conversations and agent responses
-* Analyze conversation patterns and common requests
-* Debug agent behavior by examining full conversation history
-* Build conversation analytics and monitoring dashboards
-* Implement custom conversation management in your application
-
-For complete details on topic schemas and usage, see <<agent-data-topics>>.
+Redpanda Cloud automatically persists conversation history. The *Inspector* tab automatically manages sessions for you. For programmatic integration, pass a session ID in API requests to maintain conversation continuity.
 
 If you need additional state management beyond conversation history, create tools that read/write to custom state stores, or pass relevant context in each request.
 
-[[agent-data-topics]]
-== Agent data topics
-
-Each agent automatically creates two topics for storing session and task data:
-
-* `redpanda.aiagent.<agent-id>.sessions`: Conversation history and session state
-* `redpanda.aiagent.<agent-id>.tasks`: Task execution records with status and artifacts
-
-Two schemas are also registered: `redpanda-session-value` and `redpanda-a2a-task-value`.
-
-Redpanda uses these topics internally to persist conversation history and reload context when sessions resume. This allows agents to maintain continuity across interactions.
-
-These topics and schemas are managed automatically by Redpanda. If you delete either a topic or schema, they are recreated automatically. However, deleting a topic permanently deletes all stored data (including conversation history), and the topic comes back empty. Do not produce your own data to these topics. They are reserved for agent data.
-
-For guidance on consuming these topics, analyzing conversation history, and monitoring agent performance, see xref:ai-agents:agents/monitor-agents.adoc[].
-
-=== Sessions topic
-
-The sessions topic stores conversation data, including all messages exchanged between users and the agent:
-
-[source,json]
-----
-{
-  "id": "agent-chat-abc123-WqyUmxv0fuACoSE69MCx4",
-  "messages": [
-    {
-      "role": "MESSAGE_ROLE_USER",
-      "content": [
-        {
-          "kind": "PART_KIND_TEXT",
-          "text": "What's the weather in Seattle?"
-        }
-      ]
-    },
-    {
-      "role": "MESSAGE_ROLE_ASSISTANT",
-      "content": [
-        {
-          "kind": "PART_KIND_TEXT",
-          "text": "The current weather in Seattle is 52°F with light rain."
-        }
-      ]
-    }
-  ],
-  "metadata": {}
-}
-----
-
-Use session data for debugging conversation flow, auditing agent interactions, and building conversation analytics.
-
-=== Tasks topic
-
-The tasks topic stores execution records for each agent task, including status, artifacts, message history, and token usage:
-
-[source,json]
-----
-{
-  "id": "019bc2d5-13e0-785b-9ff4-a218708e52bc",
-  "contextId": "agent-chat-abc123-oGoqyBCeH5RHTsit8qpRi",
-  "status": {
-    "state": "TASK_STATE_COMPLETED",
-    "timestamp": "2026-01-15T18:05:03.993157355Z"
-  },
-  "artifacts": [
-    {
-      "artifactId": "019bc2d5-186a-76c7-97d1-feb13c75a2d4",
-      "parts": [
-        {
-          "text": "The current weather in Seattle is 52°F with light rain."
-        }
-      ]
-    }
-  ],
-  "history": [...],
-  "metadata": {
-    "usage": {
-      "input_tokens": 64,
-      "output_tokens": 9,
-      "total_tokens": 130
-    }
-  }
-}
-----
-
-Task states include:
-
-* `TASK_STATE_COMPLETED`: Task finished successfully
-* `TASK_STATE_FAILED`: Task encountered an error
-* `TASK_STATE_RUNNING`: Task is in progress
-
-Use task data for monitoring task completion rates, tracking token usage and costs, debugging failed tasks, and building operational dashboards.
-
 == Next steps
 
-* xref:ai-agents:agents/architecture-patterns.adoc[]: Apply these concepts to design patterns
-* xref:ai-agents:agents/quickstart.adoc[]: See execution concepts in action
-* xref:ai-agents:agents/prompt-best-practices.adoc[]: Write prompts that guide agent reasoning
-* xref:ai-agents:mcp/remote/best-practices.adoc[]: Design tools that work well with agent execution
+* xref:ai-agents:agents/architecture-patterns.adoc[]
+* xref:ai-agents:agents/quickstart.adoc[]
+* xref:ai-agents:agents/prompt-best-practices.adoc[]
+* xref:ai-agents:mcp/remote/best-practices.adoc[]