Cheatsheet

AI Agents

What an agent is made of, how to write its tools, how to run it, and how to read what it did.

The three parts

A chatbot only talks. An agent can also do things.

```
model + instruction + tools
```
The model decides what to do next, the instruction defines the job, the tools are Python functions it can call.
```
question -> model -> tool -> result -> model -> answer
```
The loop an agent follows. It may go round more than once before it answers.
```
instruction="You help students check books and fines."
```
Say who the agent is and what it is for, in plain sentences.
```
A tool is a function the model may ask for
```
The model never runs code itself; the framework calls your function and hands the result back.

Writing a tool

```
def lookup_book(title: str) -> dict:
    """Find a book by its title."""
    ...
```
The name, the type hints and the docstring are what the model sees, so write them for it.

return {"found": True, "title": book["title"], "available": book["available"]}

Return a small dictionary of plain values, with the same keys every time.

```
return {"found": False}
```
Say clearly when there is no answer, so the model does not have to guess.
```
key = title.strip().lower()
```
Clean the input; a model may add spaces or capital letters.

def calculate_fine(days_overdue: int, item_type: str = "book") -> dict:

Defaults let the model leave out what it does not need to say.

```
if days_overdue <= 0:
```
Check the inputs. A tool should answer sensibly to a value that makes no sense.

Building the agent

```
from google.adk import Agent, Runner
```
The two classes you use to define and to run an agent.

desk_agent = Agent(
    name="library_desk",
    model=ScriptedModel(model="scripted"),
    instruction="You help students check books and fines.",
    tools=[lookup_book, calculate_fine],
)

Put the model, the instruction and the tool functions together. The lab uses a stand-in model so it works offline.

```
tools=[lookup_book, calculate_fine]
```
Pass the functions themselves, not the result of calling them.
```
name="library_desk"
```
A short name with no spaces; it appears in the trace.

Running it and reading the trace

run_agent(desk_agent, "Is Deep Learning available?", "agent_trace.json")

Ask one question and save everything that happened in a file.

json.load(open("agent_trace.json"))["final_answer"]

The answer the agent gave in the end.

```
[e for e in trace['events'] if e['type'] == 'tool_call']
```
Every tool the agent asked for, in order, with its arguments.
```
from google.adk.sessions import InMemorySessionService
```
Keeps the conversation of one run in memory; a real service would store it.
```
The trace is the proof
```
If the answer is wrong, read the trace before you change anything: did it pick the right tool, and did the tool return the right thing?

Good habits

```
One small job per tool
```
A tool that does one thing is easy to describe to a model and easy to test.
```
Test a tool by itself first
```
Call lookup_book("Deep Learning") yourself before an agent does.
```
Keep secrets out of instructions and results
```
Anything in the instruction, a tool result or the trace can be shown to the user.
```
Let a tool refuse
```
Return an error value for a request that must not be done, rather than hoping the model will not ask.

Cheatsheet for the AI Agents path · Deboistech · All cheatsheets