@botpress/adk-cli 1.19.0-beta.4 → 1.19.0-beta.5

package/dist/custom-components-y5wdgpey.md

@@ -0,0 +1,167 @@
+# Custom Components
+
+Custom components are React UI elements that render in webchat. The LLM can yield them during autonomous execution, or you can send them explicitly from conversation handlers.
+
+The dev console has a **Component Registry** page (`/components`) where you can browse installed components with live previews, inspect their props, and discover new components from the registry. See the `component-registry` reference in the adk-dev-console skill for details on the UI.
+
+## Creating a Component
+
+### 1. Create a `.bp.tsx` file
+
+Place React function components in `src/components/` with the `.bp.tsx` extension:
+
+```tsx
+// src/components/TicketCard.bp.tsx
+import React from 'react'
+
+type Props = {
+  ticketId: string
+  title: string
+  priority: 'low' | 'medium' | 'high' | 'urgent'
+  status: string
+}
+
+const TicketCard: React.FC<Props> = ({ ticketId, title, priority, status }) => (
+  <div style={{ padding: 16, borderRadius: 8, background: '#f8fafc', fontFamily: 'sans-serif' }}>
+    <strong>{title}</strong>
+    <p style={{ margin: '4px 0', fontSize: 13, color: '#64748b' }}>
+      {ticketId} · {priority} · {status}
+    </p>
+  </div>
+)
+
+export default TicketCard
+```
+
+A component without props also works:
+
+```tsx
+// src/components/WelcomeBanner.bp.tsx
+import React from 'react'
+
+const WelcomeBanner: React.FC = () => (
+  <div style={{ padding: 12, borderRadius: 8, background: '#f0f4ff', color: '#1e3a5f', fontFamily: 'sans-serif' }}>
+    <strong>Acme IT Help Desk</strong>
+    <p style={{ margin: '4px 0 0', fontSize: 13 }}>How can we help you today?</p>
+  </div>
+)
+
+export default WelcomeBanner
+```
+
+### 2. Register in `src/components/index.ts`
+
+Wrap each component with `CustomComponent` and provide metadata so the dev console can preview it and the LLM knows when and how to use it:
+
+```typescript
+import { CustomComponent, z } from '@botpress/runtime'
+import TicketCard from './TicketCard.bp.tsx'
+import WelcomeBanner from './WelcomeBanner.bp.tsx'
+
+export const TicketCardComponent = new CustomComponent(TicketCard, {
+  description: 'Display a ticket summary card. Use after creating or looking up a ticket.',
+  props: z.object({
+    ticketId: z.string().describe('The ticket ID'),
+    title: z.string().describe('Short summary of the issue'),
+    priority: z.enum(['low', 'medium', 'high', 'urgent']).describe('Priority level'),
+    status: z.string().describe('Current ticket status'),
+  }),
+  exampleValues: [
+    { ticketId: 'TKT-001', title: 'VPN not working', priority: 'high', status: 'open' },
+    { ticketId: 'TKT-042', title: "Can't access email", priority: 'low', status: 'in-progress' },
+  ],
+})
+
+// Components without metadata can be sent directly but can't be listed
+// in Conversation.components (the LLM won't know about them).
+export const WelcomeBannerComponent = new CustomComponent(WelcomeBanner)
+```
+
+### Metadata Fields
+
+All three fields are required together — provide all or none:
+
+- **description** — shown in the dev console and tells the LLM when to use this component
+- **props** — Zod schema for the component's props; drives dev console forms and LLM prop validation
+- **exampleValues** — seed values for dev console previews and LLM usage examples
+
+## Using Components in Conversations
+
+### LLM Autonomous Usage
+
+List components in the `components` array so the LLM can yield them during `execute()`:
+
+```typescript
+import { Conversation } from '@botpress/runtime'
+import { TicketCardComponent } from '../components'
+
+export const Chat = new Conversation({
+  channel: 'webchat.channel',
+  components: [TicketCardComponent],
+
+  async handler({ execute }) {
+    await execute({
+      instructions: 'Always use the TicketCard component to display ticket details.',
+      tools: [lookupTicket]
+    })
+  },
+})
+```
+
+Components in the `components` array must have metadata — the runtime throws an error otherwise.
+
+### Sending Directly
+
+Outside of autonomous execution, send a component message explicitly:
+
+```typescript
+import { WelcomeBannerComponent } from '../components'
+
+await conversation.send({
+  type: 'customComponent',
+  payload: {
+    component: WelcomeBannerComponent,
+    props: {},
+  },
+})
+```
+
+This works for any component, with or without metadata.
+
+### Channel Fallback
+
+Custom components only work in webchat. For multi-channel bots, fall back to agnostic message types:
+
+```typescript
+if (conversation.channel === 'webchat.channel') {
+  await conversation.send({
+    type: 'customComponent',
+    payload: {
+      component: TicketCardComponent,
+      props: { ticketId: 'TKT-001', title: 'VPN issue', priority: 'high', status: 'open' },
+    },
+  })
+} else {
+  await conversation.send({
+    type: 'card',
+    payload: {
+      title: 'TKT-001: VPN issue',
+      subtitle: 'Priority: high · Status: open',
+      actions: [],
+    },
+  })
+}
+```
+
+## Component Lifecycle
+
+1. **Create** — Add a `.bp.tsx` file in `src/components/` and register it in `index.ts`
+2. **Preview** — The dev console Installed tab shows live previews with hot reload
+3. **Register** — List the component in a `Conversation`'s `components` array for LLM usage
+4. **Deploy** — `adk deploy` bundles and uploads components; URLs are resolved automatically
+5. **Render** — The webchat renders the component when the LLM yields it or you send it explicitly
+
+## File Naming Conventions
+
+- `.bp.tsx` — React component source
+- `.bp.css` — Optional component styles (scoped via shadow DOM in the dev console and webchat)

package/dist/debug-workflow-vz84q80v.md

@@ -0,0 +1,239 @@
+# Systematic Debug Workflow
+
+A step-by-step process for diagnosing and fixing issues in ADK agents. Follow these steps in order — each step narrows the problem space.
+
+Most diagnostic CLI commands use `--format json` for structured, parseable output. Make sure `adk dev` is running in the background, once the project is validated.
+
+---
+
+## The Debug Loop
+
+```
+1. VALIDATE  → adk check --format json
+2. REPRODUCE → adk chat --single "msg" --format json
+3. LOGS      → adk logs error --format json
+4. TRACES    → adk traces --format json
+5. CLASSIFY  → Runtime error? LLM behavior? Config issue?
+6. FIX       → Apply targeted fix
+7. VERIFY    → Re-test with adk chat, confirm clean output
+8. PREVENT   → Write a regression eval
+```
+
+---
+
+## Step 1: Validate
+
+Before debugging runtime behavior, rule out project-level issues.
+
+```bash
+adk check --format json
+```
+
+This catches:
+- Invalid `agent.config.ts`
+- Schema mismatches in actions, tools, workflows
+- Invalid entity names
+- Missing dependencies
+- Import errors
+
+If `adk check` reports errors, fix them first. Many "runtime" issues are actually build/config problems.
+
+---
+
+## Step 2: Reproduce
+
+Create a minimal reproduction with a single message.
+
+```bash
+adk chat --single "the message that triggers the bug" --format json
+```
+
+**Why minimal?** A single message isolates the problem. Most often, multi-turn conversations add noise — the issue might be in turn 3 but caused by context from turn 1. That being said, some bugs are only reproducible by going through many turns.
+
+**Save the conversation ID** from the JSON output — you'll need it for trace queries and follow up conversations.
+
+If the issue requires multi-turn context:
+
+```bash
+# First message
+adk chat --single "Setup message" --format json
+# Note the conversation_id from output
+
+# Trigger the bug
+adk chat --single "Bug-triggering message" --conversation-id <id> --format json
+```
+
+---
+
+## Step 3: Check Logs
+
+Quick scan for errors and warnings.
+
+```bash
+# Errors only
+adk logs error --format json
+
+# Errors and warnings from the last hour
+adk logs warning since=1h --format json
+
+# Stream live while reproducing
+adk logs --follow --format json
+```
+
+Logs give you a high-level view. If the error is obvious here (startup failure, integration auth error, missing config), fix it directly.
+
+If logs don't explain the issue, move to traces.
+
+---
+
+## Step 4: Inspect Traces
+
+Traces show everything the agent did during a conversation turn.
+
+```bash
+# All recent traces
+adk traces --format json
+
+# For a specific conversation
+adk traces conversation=<id> --format json
+```
+
+**Read spans in order.** Look for:
+
+1. **`think` spans** — Does the model's reasoning make sense? Does it understand the user's intent?
+2. **`tool_call` spans** — Was the right tool called? Did it succeed? Are the parameters correct?
+3. **`code_execution_exception` spans** — Any runtime errors? Read the stack trace.
+4. **`end` span** — Did the turn complete normally?
+
+**Find the divergence point:** Compare what happened vs what should have happened. The first span that doesn't match expectations is usually where the bug is.
+
+---
+
+## Step 5: Classify the Failure
+
+Based on what you found in logs and traces, classify the issue:
+
+### Runtime Error
+The code threw an exception or returned an error.
+- **Traces show:** `code_execution_exception` or `tool_call` with `success: false`
+- **Next:** See `common-failures.md` for specific patterns and fixes
+
+### LLM Behavior
+The model made a bad decision — wrong tool, hallucinated values, refusal, or looping.
+- **Traces show:** `think` span with incorrect reasoning, or `tool_call` with wrong tool/params
+- **Next:** See `llm-debugging.md` for diagnosis and fixes
+
+### Config Issue
+Missing or incorrect configuration — integration auth, agent.json, environment.
+- **Traces show:** May not have traces at all, or errors mentioning config/auth
+- **Logs show:** Startup errors, auth failures, missing config warnings
+- **Next:** See `common-failures.md` sections on config, integration failures, and agent.json vs agent.local.json
+
+---
+
+## Step 6: Fix
+
+Apply a targeted fix based on the classification:
+
+| Classification | Where to Fix | Reference |
+|---------------|-------------|-----------|
+| Runtime error in handler | Action/tool/workflow handler code | `common-failures.md` |
+| Schema mismatch | Input/output schema definitions | `common-failures.md` § Build Errors |
+| Wrong tool selected | Tool descriptions, instructions | `llm-debugging.md` § Wrong Tool |
+| Hallucinated params | Input schemas, validation | `llm-debugging.md` § Hallucinated Parameters |
+| Model refusal | Instructions, tool descriptions | `llm-debugging.md` § Refusal |
+| Model looping | `onBeforeTool` guard, output clarity | `llm-debugging.md` § Looping |
+| Integration failure | Dev Console config, `adk add` | `common-failures.md` § Integration Failures |
+| Config issue | `agent.json`, `agent.local.json` | `common-failures.md` § Config Confusion |
+
+---
+
+## Step 7: Verify
+
+Re-run the exact reproduction from Step 2:
+
+```bash
+adk chat --single "the message that triggered the bug" --format json
+```
+
+Then confirm:
+
+```bash
+# No errors in logs
+adk logs error --format json
+
+# Traces show correct behavior
+adk traces --format json
+```
+
+Check that:
+- The bot responds correctly
+- The right tools are called with the right parameters
+- No error spans in the traces
+- No new warnings in logs
+
+---
+
+## Step 8: Prevent with Evals
+
+After fixing, write a regression eval so the bug can't come back. Use the **adk-evals** skill for full guidance.
+
+Quick template:
+
+```typescript
+import { Eval } from '@botpress/adk'
+
+export default new Eval({
+  name: 'fix-description-here',
+  type: 'regression',
+  tags: ['bugfix'],
+
+  conversation: [
+    {
+      user: 'the message that triggered the bug',
+      assert: {
+        response: [
+          { not_contains: 'error' },
+          { llm_judge: 'Response correctly handles the scenario' },
+        ],
+        tools: [{ called: 'expectedTool' }],
+      },
+    },
+  ],
+})
+```
+
+Run it:
+
+```bash
+adk evals fix-description-here --format json
+```
+
+Tag regression evals as `type: 'regression'` so they run in CI and catch future regressions.
+
+---
+
+## When to Escalate
+
+If you've gone through the loop and still can't resolve the issue, gather this information for a bug report:
+
+```bash
+# Project validation
+adk check --format json > check-output.json
+
+# Recent errors
+adk logs error --format json > error-logs.json
+
+# Traces from the failing conversation
+adk traces conversation=<id> --format json > traces.json
+```
+
+Include:
+1. **Reproduction steps** — exact messages/events that trigger the issue
+2. **`adk check` output** — project state
+3. **Error logs** — relevant error entries
+4. **Trace output** — full trace with spans for the failing conversation
+5. **Expected vs actual behavior** — what should happen vs what does happen
+6. **ADK version** — `adk --version`
+
+Let the human know and suggest reaching out to support with the above information.