Scaffold an eval-ready ADK agent

Most agents become hard to evaluate for structural reasons, decided on the first day: arguments with no contract, tools that raise, an instruction that describes a vibe rather than an order of operations. This scaffold makes the opposite choices, so that the first eval case has something exact to assert.

${CLAUDE_SKILL_DIR} is this skill's directory.

Flow

1. Discover. Is there already an agent here, and what do the neighbours look like?

   python3 ${CLAUDE_SKILL_DIR}/../adk/scripts/discover.py <dir> --focus layout,env --no-probe

2. Options. All free; pick one before the interview:

   Option	When
   recipes layout (recommended)	a project of its own, with tests/eval/ beside the package
   flat layout	matches adk create; config auto-discovered beside a single evalset
   workflow graph (--workflow, with either layout)	deterministic steps around one LLM node
   add a tool to an existing agent (render_tool.py)	the agent exists; one more contract is needed
   eval scaffolding only (/adk:eval-run gen_test_eval.py)	the agent exists; only the gate is missing
   context caching (--with-cache, not with --workflow)	a long, fixed procedure reused over multi-turn sessions; pointless for one- or two-turn use

3. Interview. Only the questions the request has not already answered:

   Ask	Why it matters
   name, and where it goes	the directory name becomes the app name
   the tools, with their arguments and value constraints	contracts are what eval cases assert against
   the order of operations, and what must be refused	each branch becomes an eval case

   Push for value constraints: which values are legal for each argument, what shape identifiers have, what ranges numbers fall in.

4. Confirm, scaffold with --dry-run, show the write plan, write.
5. Verify. Run discovery again and crosscheck_tools.py on the starter evalset. Then hand off to /adk:eval-create.

What gets generated, and why

Layouts

recipes (default): <project>/app/{__init__,agent,tools,schemas}.py, <project>/tests/eval/{eval_config.json,test_eval.py,evalsets/happy.evalset.json}.

flat, what adk create produces: <project>/<name>/{__init__.py,agent.py,.env.example,test_config.json,happy.test.json}.

The difference that matters: in the flat layout test_config.json sits beside the evalset, so adk eval finds it when a single evalset is passed. In the recipes layout the config must always be passed with --config_file_path.

workflow (--workflow): a Workflow with two function nodes and one LlmAgent node, exported as app = App(root_agent=workflow). Eval cases for a graph read nodeInfo.path in traces; a node may set its output once.

Decision rules

• No tools, no evaluation. An agent with no tools has no trajectory, so the scaffold requires at least one.
• The agent name is a Python identifier and never user. ADK rejects both.
• Sampling settings go in generate_content_config. Passing temperature= to the agent raises at construction, and that config must not carry tools, system_instruction or response_schema.
• Do not cap a thinking model's output to save tokens. max_output_tokens is a ceiling on thoughts and answer together; under 1024 a hard turn comes back truncated (AGT084). Set the thinking level in thinking_config and bound the answer in the instruction.
• Prefer Workflow over SequentialAgent / ParallelAgent / LoopAgent, which are deprecated, unless an LlmAgent has to transfer into the block.
• Never overwrite by default. Existing files, functions and eval ids are left alone unless the user asks for --force.
• Long procedures go in skills, not the instruction. A procedure needed for one kind of request belongs in a SkillToolset skill the agent loads on demand; a large tool result belongs in an artifact, and a long conversation wants event compaction. The instruction stays short and always relevant.
• Each skill's description must be its own. The model routes on name and description alone; two skills in the same words (AGT083) let one take the other's requests. Encode habits (check flags, least privilege, ask before a billable change), not reference tables, and prove each skill earns its place with a with/without run (skills-and-progressive-disclosure.md).
• A live (voice) agent: read live-agents.md first. A slow tool there is silence; make it a streaming (yield) or non-blocking tool, add stop_streaming, and give its evals live_model_config. A streaming tool on a text model never streams (AGT081: on 2.12+ a second yield aborts the run).
• A remote step is a state, not a crash. A RemoteA2aAgent that cannot be reached yields an error event and the pipeline runs on; write the manual-review hold yourself (workflow-graphs.md). Through 2.13.0 constructing it prints an [EXPERIMENTAL] warning (ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS=1); only main after 2.13.0 graduates A2A.
• Throttle a parallel worker on a function node, not an agent. max_parallel_workers on an LlmAgent exists only on main after 2.13.0, and every release refuses it at construction (AGT085); parallel_worker=True alone is fine, and @node(parallel_worker=True, max_parallel_workers=N) caps a function node since 2.4.0.
• Memory stays with the caller of an AgentTool through 2.13.0. A wrapped agent's load_memory searches a fresh, empty store (AGT082); call the memory tool from the parent, or transfer (context-engineering.md).
• The generated TODOs are not decoration. A tool docstring that still says "TODO" is a tool the model has to guess about; say so before the user runs anything.

References

Scripts

Tool spec: name:field=type,field=type;name:... where a type is str, int, float, bool, literal(a|b|c) or pattern(^RE$).

Completion checklist

• The agent loads: discovery reports the expected layout and export.
• Every tool has a docstring with an Args: section, and no TODOs left.
• Every tool argument has a contract, not just a type.
• The instruction states the order and the refusals explicitly.
• The model id comes from the environment.
• The starter evalset cross-checks clean against the tools.
• The user knows the next step is /adk:eval-create.