Merge branch 'main' into fix/eval-instruction-session-state

Author: sgoel2be24-cyber

.agents/skills/adk-agent-builder/SKILL.md

@@ -1,69 +1,71 @@
 ---
 name: adk-agent-builder
-description: Central hub for building, testing, and iterating on ADK agents. Trigger this skill when the user wants to create a new agent, configure modes (task, single-turn), or build graph-based workflows.
+description: >-
+  Builds ADK (Agent Development Kit) Python agents: LLM agents with tools,
+  graph workflows of function and agent nodes, conditional routing, fan-out and
+  join, schema-validated delegation between agents, human-in-the-loop pauses,
+  and pytest coverage for all of it. Use when asked to create an agent or a
+  workflow, add a tool to one, branch or loop between nodes, run steps in
+  parallel, pause for user approval, or test an agent. Don't use for explaining
+  how ADK works internally or designing its core components (use
+  `adk-architecture`), for an agent that already runs but misbehaves (use
+  `adk-debug`), for authoring a sample under `contributing/` (use
+  `adk-sample-creator`), or for naming, typing, and formatting conventions (use
+  `adk-style`).
 ---
 
 # ADK Agent Builder
 
-This file serves as a directory of specialized reference guides for developing
-agents with ADK. To avoid context pollution, read only the relevant reference
-file based on your current task.
+Read only the reference that matches the task. Loading the whole tree costs
+context and buries the part that matters.
 
-## Core Concepts Directory
+Every API below was checked against `google-adk` 2.6.2. If a symbol is missing
+at runtime, read the source under `src/google/adk/` rather than guessing a
+neighbouring name.
 
-Refer to these files for foundational knowledge:
+## Start here
 
-- **Getting Started & Basic Agents**: [getting-started.md](references/getting-started.md)
-  - Environment setup, API key configuration, and minimal agent definitions.
-- **Tool Catalog**: [tool-catalog.md](references/tool-catalog.md)
-  - How to bind function tools, MCP tools, OpenAPI specs, and Google API tools.
-- **Agent Modes (Task / Single-Turn)**: [task-mode.md](references/task-mode.md)
-  - Multi-turn structured delegation and autonomous single-turn execution patterns.
--   **Import Paths**: [import-paths.md](references/import-paths.md)
-    -   Canonical and verbose import paths for core components, tools, and
-        events.
+| Task | Reference |
+|---|---|
+| First agent, environment, `adk` CLI | [getting-started.md](references/getting-started.md) |
+| Which import path is the canonical one | [import-paths.md](references/import-paths.md) |
+| The rules that cause most runtime failures | [best-practices.md](references/best-practices.md) |
 
-## Workflow & Graph Orchestration
+## Building blocks
 
-Refer to these files when building complex graphs:
+- [tool-catalog.md](references/tool-catalog.md) — function tools, MCP, OpenAPI,
+  Google API toolsets, built-in tools, custom `BaseTool` and `BaseToolset`.
+- [function-nodes.md](references/function-nodes.md) — plain functions as nodes:
+  parameter resolution, generators, `node_input` typing rules.
+- [llm-agent-nodes.md](references/llm-agent-nodes.md) — an `LlmAgent` used as a
+  workflow node: output types, instruction templates, `output_schema`,
+  auto-wrapping behavior.
+- [task-mode.md](references/task-mode.md) — `mode='task'` and
+  `mode='single_turn'` delegation with schema-validated input and output.
 
-- **Function Nodes**: [function-nodes.md](references/function-nodes.md)
-  - How to use functions as nodes, type resolution, and generators.
-- **Routing & Conditions**: [routing-and-conditions.md](references/routing-and-conditions.md)
-  - Edge patterns, dict-based routing, self-loops, and conditional execution.
-- **LLM Agent Nodes**: [llm-agent-nodes.md](references/llm-agent-nodes.md)
-  - How to use LLM agents as workflow nodes, task wrappers, and handling output schemas.
--   **Advanced Patterns**:
-    [advanced-patterns.md](references/advanced-patterns.md)
-    -   Nested workflows, custom node types, and graph validation rules.
+## Graph orchestration
 
-## Advanced Orchestration Patterns
+- [routing-and-conditions.md](references/routing-and-conditions.md) — routed
+  edges, dict routing maps, default routes, self-loops, revision loops.
+- [parallel-and-fanout.md](references/parallel-and-fanout.md) — fan-out edges,
+  `JoinNode` fan-in, `parallel_worker=True` list processing.
+- [dynamic-nodes.md](references/dynamic-nodes.md) — scheduling nodes at runtime
+  with `ctx.run_node()` and imperative workflow construction.
+- [human-in-the-loop.md](references/human-in-the-loop.md) — `RequestInput`,
+  resume behavior, resumable vs replayed sessions.
+- [advanced-patterns.md](references/advanced-patterns.md) — nested workflows,
+  retries, custom `BaseNode` subclasses, graph validation rules.
+- [multi-agent.md](references/multi-agent.md) — chat-transfer hierarchies, and
+  the deprecated `SequentialAgent` / `LoopAgent` / `ParallelAgent` shells that
+  `Workflow` replaces.
 
-- **Parallel Processing & Fan-Out**: [parallel-and-fanout.md](references/parallel-and-fanout.md)
-  - `ParallelWorker` for list splitting and concurrent processing, fan-out/join patterns.
-- **Human-in-the-Loop**: [human-in-the-loop.md](references/human-in-the-loop.md)
-  - Pausing execution for user input, resumable workflows, and AuthConfig on nodes.
-- **Dynamic Nodes**: [dynamic-nodes.md](references/dynamic-nodes.md)
-  - Scheduling nodes at runtime dynamically via `ctx.run_node()`.
+## Runtime and verification
 
-## Infrastructure & Utilities
-
-- **State & Events**: [state-and-events.md](references/state-and-events.md)
-  - Using context API, sharing global state, and yield event structures.
--   **Session & Memory**:
-    [session-and-state.md](references/session-and-state.md)
-    -   Session state mutation, scope conventions, and database session
-        services.
--   **Callbacks & Plugins**:
-    [callbacks-and-plugins.md](references/callbacks-and-plugins.md)
-    -   Implementing callbacks, plugin manager integration, and override
-        behavior.
-- **Multi-Agent Systems**: [multi-agent.md](references/multi-agent.md)
-  - Hierarchical execution (e.g., `SequentialAgent`, `LoopAgent`, `ParallelAgent`).
-- **Testing Strategies**: [testing.md](references/testing.md)
-  - Automated queries with `adk run`, unit tests, and integration testing with sample agents.
-
-## Standards & Guidelines
-
-- **Best Practices**: [best-practices.md](references/best-practices.md)
-  - Critical rules (Pydantic schemas, content events, state-based data flow).
+- [state-and-events.md](references/state-and-events.md) — the `Context` object,
+  `Event` fields, and how state flows between nodes.
+- [session-and-state.md](references/session-and-state.md) — session services,
+  artifacts, memory, and state key scoping.
+- [callbacks-and-plugins.md](references/callbacks-and-plugins.md) — the six
+  agent callbacks and app-level plugins.
+- [testing.md](references/testing.md) — `pytest` with `InMemoryRunner`, faking a
+  model, asserting on node output.