Index of every page on this site: llms.txt
All skills
google avatar

/custom-investigation

@ead8d7f
by googlegoogle/adk-recipes11k stars
2,961
Run it yourself

Run a custom investigation: review a chosen slice of conversations instead of a random sample, by writing a SQL selector over the observed agent's telemetry, and optionally narrow what the reviewer reports. Use when a message asks to investigate only certain conversations -- ones that hit an error, used a particular tool, ran slowly, mention a topic, looped, or were abandoned -- or asks to re-review conversations already seen with a different focus. Covers the telemetry table a selector reads, writing the selector, previewing what it matched, and starting the run.

  • 4 files
  • 30.4 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/google/adk-recipes/custom-investigation

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencescloud_ops.md

≈897 tokens on demand. Your agent reads this file only when SKILL.md points to it.

The selector table: SELECTOR_TABLE

SELECTOR_TABLE stands for the table that describe_telemetry returns; replace it in every recipe below. On this source it is the Cloud Trace linked dataset. It holds one row per span. The session id is the gen_ai.conversation.id span attribute, not a column.

Columns worth knowing

describe_telemetry lists every column the table has, nested fields included. These are the ones selectors lean on:

  • trace_id -- the trace; one trace is one turn.
  • span_id -- the span.
  • name -- the span name, such as call_llm or execute_tool <name>.
  • start_time, end_time -- when the span started and ended, in UTC.
  • attributes JSON -- the span attributes; the keys are described below.
  • events -- events recorded on the span, each with a name and attributes.
  • status.code -- the span outcome: 0 unset, 1 ok, 2 error.
  • resource.attributes JSON -- attributes of the process that emitted the span.

The column set is fixed; the keys inside attributes are not. They depend on what the observed agent's instrumentation emits, so check a key with a preview before relying on it.

Read attributes with JSON_VALUE(attributes, '$."<key>"'). The keys that matter: gen_ai.conversation.id (the session), gen_ai.agent.name, gen_ai.tool.name, gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions, gen_ai.tool.definitions. The deployment revision is a resource attribute: JSON_VALUE(resource.attributes, '$."service.version"').

Execution spans carry no session id. call_llm and execute_tool <name> spans omit gen_ai.conversation.id, so a condition on a tool, an error status or a span name cannot project the session directly. Match those spans, keep their trace_id, and join back to the spans that do carry the session id. Both sides read the same table, so the join is allowed.

An error shows up two ways: status.code = 2, and an exception entry in the span's events array.

A long payload may be offloaded to GCS under the same attribute key with a _ref suffix, holding a gs:// URI instead of the text. Content predicates match only what is inline.

1. Conversations containing a failed span

SELECT JSON_VALUE(s.attributes, '$."gen_ai.conversation.id"') AS target_id
FROM `SELECTOR_TABLE` AS s
JOIN (
  SELECT DISTINCT trace_id
  FROM `SELECTOR_TABLE`
  WHERE start_time BETWEEN @window_start AND @window_end
    AND status.code = 2
) AS failed
USING (trace_id)
WHERE s.start_time BETWEEN @window_start AND @window_end
  AND JSON_VALUE(s.attributes, '$."gen_ai.agent.name"') = @agent_name
  AND JSON_VALUE(s.attributes, '$."gen_ai.conversation.id"') IS NOT NULL
GROUP BY target_id

Swap the inner WHERE to select by tool -- JSON_VALUE(attributes, '$."gen_ai.tool.name"') = 'issue_refund', or name = 'execute_tool issue_refund' -- or by elapsed span time, TIMESTAMP_DIFF(end_time, start_time, SECOND) > 30.

2. Conversations from one deployment revision

SELECT JSON_VALUE(attributes, '$."gen_ai.conversation.id"') AS target_id
FROM `SELECTOR_TABLE`
WHERE start_time BETWEEN @window_start AND @window_end
  AND JSON_VALUE(attributes, '$."gen_ai.agent.name"') = @agent_name
  AND JSON_VALUE(resource.attributes, '$."service.version"') = '12'
  AND JSON_VALUE(attributes, '$."gen_ai.conversation.id"') IS NOT NULL
GROUP BY target_id

The AI.IF pattern in the skill's "Semantic selection with AI.IF" works here too, over JSON_VALUE(attributes, '$."gen_ai.input.messages"'), on spans that carry the messages inline.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at ead8d7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 weeks ago

README badge

README badge for google/adk-recipes/custom-investigation