omarcevi.dev / workshops / coding-agent-workshop / 2 · Hands

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.

agents/step2_files/agent.py
agent.pyagents/step2_files/
# 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
agent.pyagents/step2_files/
# 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.py
agent.pyagents/step2_files/
root_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.