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

package/dist/{README-wjb7z7f0.md → README-824wa4jj.md}

@@ -32,7 +32,7 @@ flowchart TD
     C --> E[copyDirRecursive]
     D --> E
     E --> F["Replace {{projectName}}, {{runtimeVersion}}, {{packageManager}}"]
-    F --> G[Write CLAUDE.md + agent.json if missing]
+    F --> G[Write CLAUDE.md, AGENTS.md + agent.json if missing]
     G --> H["Install dependencies (integrations, plugins)"]
 ```
 

package/dist/SKILL-75ym6tcj.md

@@ -0,0 +1,257 @@
+---
+name: adk-debugger
+description: Systematic debugging for ADK agents — trace reading, log analysis, common failure diagnosis, and the debug loop.
+license: MIT
+---
+
+# ADK Debugger Skill
+
+## What is ADK Debugging?
+
+Every ADK agent records its behavior as traces and logs — every conversation turn, tool call, LLM reasoning step, and error. These are the source of truth for understanding what your agent did and why.
+
+The ADK CLI provides the tools you need to debug. Most diagnostic commands support `--format json`; use it for programmatic output. The exception is `adk dev`, which has no `--format` flag and uses `adk dev --non-interactive` for structured NDJSON output.
+
+## When to Use This Skill
+
+Use this skill when the developer asks about:
+
+- **Bot not working** — not responding, wrong responses, unexpected behavior
+- **Tool issues** — wrong tool called, tool errors, hallucinated parameters
+- **Workflow problems** — stuck workflows, steps not executing, state issues
+- **Reading traces/logs** — how to query, filter, and interpret debug output
+- **LLM misbehavior** — hallucinations, refusals, looping, poor extraction
+- **Build/deploy failures** — validation errors, schema mismatches
+- **Config issues** — agent.json vs agent.local.json, integration setup
+- **Post-fix verification** — confirming a fix worked, writing regression evals
+
+**Trigger questions:**
+- "My bot isn't responding"
+- "The wrong tool was called"
+- "My workflow is stuck"
+- "How do I read traces?"
+- "How do I check logs?"
+- "The LLM is hallucinating"
+- "Something broke after my last change"
+- "My deploy failed"
+- "`adk check` found errors"
+- "Summarize this trace"
+- "What happened in trace X?"
+- "Give me an overview of this conversation turn"
+- "Why did the bot do X in this trace?"
+- "Walk me through what happened"
+- "How do I debug this?"
+- "Summarize this conversation"
+- "Explain what happened in conversation X"
+- "Why did the bot respond that way?"
+- "Walk me through this conversation"
+- "What went wrong in this conversation?"
+
+## Available Documentation
+
+| File | Contents |
+|------|----------|
+| `references/traces-and-logs.md` | CLI debugging tools, log querying, trace structure, span types, `onTrace` hooks, reproduction with `adk chat` |
+| `references/common-failures.md` | Runtime failure patterns — validation, bot not responding, tool errors, workflow stuck, integration failures, build errors, config confusion |
+| `references/llm-debugging.md` | LLM behavior issues — wrong tool, hallucinated params, refusals, token limits, looping, reading model reasoning |
+| `references/debug-workflow.md` | The systematic 8-step debug loop: validate → reproduce → logs → traces → classify → fix → verify → prevent |
+| `references/trace-summarization.md` | How to fetch, walk, and summarize traces as free-form natural-language narratives — adapting depth to context |
+| `references/conversation-analysis.md` | How to summarize and explain full conversations — listing conversations, timeline analysis, correlating with traces, common patterns |
+
+## How to Answer
+
+1. **"How do I read traces/logs?"** → Read `traces-and-logs.md` for CLI commands and trace structure
+2. **Something is broken, known pattern** → Read `common-failures.md` for the matching failure pattern
+3. **LLM is misbehaving** → Read `llm-debugging.md` for the matching behavior issue
+4. **Systematic investigation needed** → Read `debug-workflow.md` and follow the 8-step loop
+5. **"Summarize this trace" / "What happened?"** → Read `trace-summarization.md` for how to fetch, walk, and narrate traces
+6. **"Summarize this conversation" / "Explain what happened"** → Read `conversation-analysis.md` for multi-turn conversation summaries and explanations
+7. **After fixing, need to prevent regression** → Point to the `adk-evals` skill for writing evals
+
+---
+
+## Quick Reference
+
+### The Debug Loop
+
+```
+symptom → validate (adk check) → reproduce (adk chat) → logs (adk logs) → traces (adk traces) → root cause → fix → verify
+```
+
+### CLI Commands (prefer structured output)
+
+```bash
+adk check --format json                         # offline validation
+adk logs error --format json                     # recent errors
+adk logs --follow --format json                  # stream live
+adk traces --format json                         # recent traces
+adk traces conversation=<id> --format json       # specific conversation
+adk chat --single "msg" --format json            # test message
+adk dev --non-interactive                        # structured NDJSON dev output (no TUI)
+adk conversations --format json                  # list recent conversations
+adk conversations show <id> --format json        # conversation timeline
+adk conversations show <id> --include-llm --format json  # timeline with LLM reasoning
+```
+
+### Span Types
+
+| Type | What It Shows |
+|------|--------------|
+| `think` | LLM reasoning — why it chose an action |
+| `tool_call` | Tool invocation — name, input, output, success/error |
+| `code_execution_exception` | Runtime error — message and stack trace |
+| `end` | Conversation turn completed |
+
+---
+
+## Prerequisites Check
+
+Before debugging, verify:
+
+- [ ] **Project valid?** Run `adk check --format json` — fix any reported issues first
+- [ ] **Dev server running?** `adk dev` (or `adk dev --non-interactive` for structured NDJSON output)
+- [ ] **Bot linked?** `agent.json` exists with `botId` and `workspaceId` (created by `adk link`)
+- [ ] **Dev bot created?** `agent.local.json` has `devId` (set automatically by the first `adk dev` run)
+- [ ] **Integration configured?** Check Dev Console at localhost:3001 for unconfigured integrations
+
+---
+
+## Critical Patterns
+
+✅ **Run `adk check` before debugging runtime issues**
+
+```bash
+# CORRECT — catch config/schema problems offline first
+adk check --format json
+# Then debug runtime issues
+```
+
+❌ **Skipping offline validation**
+
+```bash
+# WRONG — jumping straight to runtime debugging wastes time on config issues
+adk traces --format json  # might be chasing a config problem
+```
+
+---
+
+✅ **Use `--format json` on all CLI commands**
+
+```bash
+# CORRECT — structured output for reliable parsing
+adk logs error --format json
+adk traces --format json
+adk chat --single "test" --format json
+```
+
+❌ **Parsing human-readable output**
+
+```bash
+# WRONG — human-readable format is for display, not parsing
+adk logs error
+adk traces
+```
+
+---
+
+✅ **Use `adk logs error` to filter errors**
+
+```bash
+# CORRECT — focused error scan
+adk logs error --format json
+adk logs warning since=1h --format json
+```
+
+❌ **Scrolling through all output**
+
+```bash
+# WRONG — too much noise, easy to miss the actual error
+adk logs --format json  # 50 entries of everything
+```
+
+---
+
+✅ **Use `onTrace` hooks for programmatic monitoring**
+
+```typescript
+// CORRECT — structured, automated trace analysis
+hooks: {
+  onTrace: ({ trace }) => {
+    if (trace.type === "tool_call" && !trace.success) {
+      console.error(`[TOOL ERROR] ${trace.tool_name}`, trace.error);
+    }
+  }
+}
+```
+
+❌ **Only checking console output**
+
+```typescript
+// WRONG — console.log in handlers misses the structured trace data
+handler: async (input) => {
+  console.log("tool called");  // not useful for debugging
+}
+```
+
+---
+
+✅ **Write a regression eval after fixing**
+
+```typescript
+// CORRECT — prevents the bug from coming back
+export default new Eval({
+  name: 'fix-order-lookup',
+  type: 'regression',
+  conversation: [{ user: 'Look up order 123', assert: { tools: [{ called: 'lookupOrder' }] } }],
+})
+```
+
+❌ **Fixing and moving on**
+
+```
+// WRONG — the same bug will return and you'll debug it again
+```
+
+---
+
+## Example Questions
+
+**Basic:**
+- "My bot isn't responding — how do I figure out why?"
+- "How do I check for errors in my ADK project?"
+- "What's the difference between agent.json and agent.local.json?"
+
+**Intermediate:**
+- "The bot called createTicket instead of lookupTicket — how do I fix this?"
+- "My workflow starts but the second step never runs"
+- "How do I see what the LLM was thinking when it made a decision?"
+- "Integration actions are failing with auth errors"
+
+**Advanced:**
+- "How do I set up onTrace hooks for automated error detection?"
+- "The model loops on the same tool call — how do I add a guardrail?"
+- "How do I monitor tool call performance with timing metrics?"
+- "How do I systematically debug a multi-step workflow failure?"
+
+---
+
+## Response Format
+
+**Match depth to the question.**
+
+### Simple questions ("how do I check logs?", "what are trace spans?")
+
+Answer directly — one sentence + the CLI command or concept. Don't run the full debug loop for informational questions.
+
+### Active debugging ("my bot is broken", "X isn't working")
+
+Follow the full loop:
+
+1. **Check prerequisites** — verify dev server, config files, project validation
+2. **Start with `adk check --format json`** — rule out offline issues
+3. **Reproduce** — use `adk chat --single "msg" --format json` to create a clean reproduction
+4. **Read the evidence** — `adk logs error --format json` for quick scan, `adk traces --format json` for details
+5. **Identify the root cause** — point to the specific span, log entry, or config issue
+6. **Suggest a targeted fix** — reference the appropriate failure pattern doc
+7. **Verify** — re-run the reproduction, confirm clean output
+8. **Write a regression eval** — load the `adk-evals` skill and generate the eval file automatically