diff --git a/skills/adk-debugger/references/trace-summarization.md b/skills/adk-debugger/references/trace-summarization.md index 7e082af..01a5d7f 100644 --- a/skills/adk-debugger/references/trace-summarization.md +++ b/skills/adk-debugger/references/trace-summarization.md @@ -19,9 +19,19 @@ adk traces conversation= --include-llm --format json adk traces --include-llm --format json ``` -**Always pass `--include-llm`** when summarizing. Without it, `think` spans are omitted and you lose the model's reasoning, which is essential for explaining _why_ the agent did what it did. +**Always pass `--include-llm`** when summarizing. Without it, span `data` is omitted and you lose the model's reasoning, which is essential for explaining _why_ the agent did what it did. -**Always pass `--format json`** for structured, parseable output. +**Pass `--format json`** when piping into `jq`; for reading, the default text output is already condensed. + +**Keep it small.** Narrow to the spans you need instead of dumping the whole trace (`--format json` caps long `data` by default; `--full` for the complete blob): + +```bash +# iteration/LLM/tool spans only, as a flat list (substring match on span name) +adk traces trace= span=iteration,cognitive,tool --include-llm + +# or jq to a specific span (the field is `name`, not `type`) +adk traces trace= --include-llm --format json | jq '.spans[] | select(.name=="autonomous.tool")' +``` --- diff --git a/skills/adk/references/autonomous-execution.md b/skills/adk/references/autonomous-execution.md index a4f7f4f..17923e2 100644 --- a/skills/adk/references/autonomous-execution.md +++ b/skills/adk/references/autonomous-execution.md @@ -722,6 +722,7 @@ await execute({ ## Pitfalls +- **Tool results are not auto-echoed into the reply.** Declare a typed `output` schema and instruct the agent to answer with the real values, never placeholders — see [Surfacing Tool Results](./tools.md#surfacing-tool-results-to-the-user). - **Do not redefine built-in exits.** Creating an exit named `listen`, `think`, or `done` will conflict with the built-in ListenExit, ThinkExit, and DefaultExit. - **Exits require good descriptions.** The LLM decides which exit to use based on the `description`. Vague descriptions lead to wrong exit selection. - **Writable properties need a schema.** If `writable: true` without `type`, the sandbox cannot validate writes and they will be unchecked. diff --git a/skills/adk/references/cli.md b/skills/adk/references/cli.md index 920e386..ec055e7 100644 --- a/skills/adk/references/cli.md +++ b/skills/adk/references/cli.md @@ -545,6 +545,7 @@ adk traces [tokens...] [options] - `trigger=` — filter by trigger name - `conversation=` — filter by conversation id - `trace=` — drill into a specific trace (shows the full span tree) +- `span=` — drill-in only: keep only spans whose name/label matches (comma-separated substring, e.g. `tool,cognitive`). Renders as a flat list. - `since=` / `until=` — e.g. `30s`, `5m`, `1h`, `2d`, `1w` - `limit=` — max traces to show (default: 20) @@ -552,6 +553,7 @@ adk traces [tokens...] [options] - `-f, --follow` — stream new traces as they complete - `--include-llm` — include LLM instructions, code, and tools in drill-in mode +- `--full` — with `--include-llm --format json`: don't truncate large `data` fields. Omitted, long strings are capped by default. - `--format ` — `json` only (omit for default text output) **Examples:** @@ -562,10 +564,18 @@ adk traces error # error traces only adk traces workflow=onboarding # traces for a workflow adk traces conversation= --format json adk traces trace= --include-llm # drill into one trace with LLM content +adk traces trace= span=iteration,cognitive,tool --include-llm # only those spans adk traces since=1h limit=50 --format json adk traces error --follow # stream errors live ``` +> For a drill-in, prefer smaller output over the raw JSON dump: +> +> - Default text output (`adk traces trace= --include-llm`) is already condensed — start here. +> - Narrow with `span=` (e.g. `span=iteration,cognitive,tool`) to drop noise. +> - `--format json` caps long `data` by default; add `--full` only for the complete blob. +> - `jq` to specific spans, e.g. `... --format json | jq '.spans[] | select(.name=="autonomous.tool")'`. + ### adk workflows Inspect workflow definitions and runs on the linked dev bot. All `adk workflows ...` commands target the dev bot (same credentials path as `adk dev`) and only accept `--format json` — any other `--format` value is rejected. diff --git a/skills/adk/references/tools.md b/skills/adk/references/tools.md index 805bd30..80d260d 100644 --- a/skills/adk/references/tools.md +++ b/skills/adk/references/tools.md @@ -65,7 +65,7 @@ export default new Autonomous.Tool({ | **name** | `string` | Yes | Unique TypeScript-compatible identifier | | **description** | `string` | Recommended | Helps AI understand when and how to use the tool | | **input** | `z.ZodType` | No | Zod schema for input validation (defaults to `z.any()`) | -| **output** | `z.ZodType` | No | Zod schema for output validation (defaults to `z.any()`) | +| **output** | `z.ZodType` | Recommended | Zod schema for output validation (defaults to `z.any()`) | | **handler** | `function` | Yes | Async function implementing tool logic | | **aliases** | `string[]` | No | Alternative names the AI can use to call this tool | | **metadata** | `Record` | No | Custom information for tool categorization | @@ -151,6 +151,22 @@ export const anotherTool = new Autonomous.Tool({ | Typical use | Internal functions, any context | AI-callable, conversation context | | Handler signature | `handler({ input, client })` | `handler(input, ctx?)` or `handler({ ...fields }, ctx?)` | +## Surfacing Tool Results to the User + +A tool's return value is **not** auto-echoed — only the text the model explicitly emits reaches the user. Left to itself the model often sends a placeholder ("see the tool output above"), an empty `<>`, or `[object Object]`. To keep the real values in the reply: + +1. Declare a typed `output` schema (not the `z.any()` default) so the model can read fields like `result.count`. +2. Instruct the conversation to answer in plain text with the concrete returned values, never placeholders. + +```typescript +export const queryVendors = new Autonomous.Tool({ + name: 'queryVendors', + input: z.object({ term: z.string() }), + output: z.object({ results: z.array(z.object({ name: z.string(), rate: z.number() })), count: z.number() }), + handler: async ({ term }) => queryRows(term), +}) +``` + ## Accessing Context in Tools Tools can use global runtime proxies directly, but conversation-specific values should be loaded through `context.get(...)`: