Step 2 · Give it hands
Tools in ADK are plain Python functions. ADK reads each function's name, type hints and docstring, and sends them to the model as a tool definition. The model never runs your code: it asks for a call, ADK runs the function, and the result goes back to the model.
Start with the folder the agent works in, and a tool to see what's in it. Add from pathlib import Path at the top of the file.
# The folder the agent works in. Recreate it with: uv run reset_workspace.py
WORKSPACE = Path(__file__).resolve().parents[2] / "workspace"
SKIP = {"__pycache__", ".pytest_cache"}
def list_files() -> dict:
"""Lists every file in the project, as paths relative to the project root."""
files = [
str(p.relative_to(WORKSPACE))
for p in sorted(WORKSPACE.rglob("*"))
if p.is_file() and not SKIP & set(p.parts)
]
return {"files": files}Then a tool to read a file and one to write it. The docstrings are written for the model, not for you: they're all it knows about each tool.
agents/step2_files/agent.py# Tools return errors instead of raising them. ADK re-raises a tool's
# exception and ends the run, but an error the model can read is one it can
# recover from (e.g. "no such file", then it lists files and tries again).
def read_file(path: str) -> dict:
"""Reads a text file from the project.
Args:
path: File path relative to the project root, e.g. "cart.py".
"""
try:
return {"content": (WORKSPACE / path).read_text()}
except Exception as e:
return {"error": str(e)}
def write_file(path: str, content: str) -> dict:
"""Creates a file, or replaces an existing file's contents.
Args:
path: File path relative to the project root, e.g. "cart.py".
content: The complete new contents of the file.
"""
try:
file = WORKSPACE / path
file.parent.mkdir(parents=True, exist_ok=True)
file.write_text(content)
return {"status": "ok", "path": path}
except Exception as e:
return {"error": str(e)}Finally, hand the functions to the agent and tell it how to work:
agents/step2_files/agent.pyroot_agent = Agent(
name="coding_agent",
model="gemini-3.8-flash",
instruction=(
"You are a coding agent working on a small Python project. "
"Look before you answer: list the files, then read the ones that matter. "
"When you change a file, write its complete new contents. "
"Finish with a short summary of what you did."
),
tools=[list_files, read_file, write_file],
)Save, and ask:
What's in my project, and what does cart.py do?Create hello.py that prints a greeting.Each tool call shows up in the chat. Click one to see exactly what the model asked for and what came back.
The idea: a tool is a function plus a description the model can read.