Instructions that work

The instruction is the field you will edit most. It has one feature worth knowing early: it can read from state.

An instruction is a string template. Write {customer} in it and ADK puts the value of that key from session state in before the model sees it.

agent = LlmAgent(
    name="support",
    model=PretendModel(replies=[say("Hello again.")]),
    instruction="You are helping {customer}, who is on the {plan} plan. Be brief.",
)

Two holes in the instruction, and nothing yet to fill them. The values come from the session, not from the agent.

print(await ask(agent, "hello", state={"customer": "Asha", "plan": "annual"}))
print("the template on the agent:", agent.instruction)

The agent still holds the template. The substitution happened for that one run against that one session, which is how a single agent serves every customer without a different instruction for each.

When the key is missing

The documentation is precise: if the state variable does not exist, the agent raises an error. A question mark makes it optional.

instruction = "You are helping {customer?}. Be brief."

Use the question mark for anything that might not be set yet, and leave it off for anything the agent cannot work without. The error is better than a prompt with a hole in it.

Three fields, three audiences

Mixing up the first two is the most common structural mistake in a multi-agent setup. The description is not a summary of the instruction. It is the sentence another agent reads when choosing.

• The job, in one or two sentences.
• What to do when it cannot answer, which is the line most people leave out.
• Hard limits: what it must never say or do.
• How to use the tools, only where the descriptions are not enough on their own.