Skip to content

Concepts

Science ADK is a small number of ideas applied consistently. This section explains each one and, more importantly, why it constrains you the way it does.

  • Built on Google ADK

    Why a Science ADK agent is a google.adk.agents.BaseAgent, verified against measurements rather than preference.

  • The research workspace

    GOAL.md, HYPOTHESIS.md, workflow.json, runs/, LEARNINGS.md — the whole project as diffable files.

  • Agents and typed ports

    The programming model: declare ports, implement execute, read inputs, call tools, return outputs.

  • Agent primitives

    Seven specialised base classes, each enforcing one scientific discipline.

  • Workflows and the DAG

    Nodes, edges, topological execution, and what validate proves before anything runs.

  • Tools and MCP

    Local Python functions with zero boilerplate; stdio and HTTP MCP servers through science.toml.

  • Provenance and datasets

    The ledger the runtime keeps behind the agent's back, and how large values travel as references.

  • Integrity gates and audit

    Six deterministic gates, three human pillars, and why a failed gate scores exactly zero.

The one-paragraph version

A research project states a question in GOAL.md with one target metric and one threshold. Each experiment states a falsifiable hypothesis and defines a workflow: a DAG of nodes, each backed by one Python agent with typed input and output ports. Running the workflow produces a trace containing every output, log and timing, plus a provenance ledger recorded by the runtime rather than by the agent. Six deterministic gates are computed from that trace; if any fails the run scores 0.00. If they all pass, a human or an auditing agent records three pillar ratings and a rationale, and only then does the run have a score. Insights get appended to LEARNINGS.md, and the next experiment cites its parent.

The three things that are unusual

  1. A green run is not a result. Passing the gates proves the number was really computed. It says nothing about whether the number matters. That judgement is a separate, recorded, attributable step.

  2. The agent cannot write its own evidence. call_tool, fetch and artifact record provenance in a structure the agent code does not control. Deleting a tool call to hard-code an answer fails tool_use_verified, no matter how plausible the rest of the run looks.

  3. The threshold is deliberately out of reach of the experiment. The target value lives in GOAL.md and is compared outside the workflow. An evaluation node that could see the number it must beat is one that will eventually be written to beat it.