Instructions that work

Instructions are the one field you will edit most, and the difference between a vague agent and a useful one is usually four sentences.

They are sent to the model on every turn, ahead of the conversation. The model has no memory of your intentions, only this text.

Two agents, same question

python

vague = Agent(
    name="Vague",
    instructions="Help the customer.",
    model=PretendModel(["Sure, I can help with that."]),
)

python

sharp = Agent(
    name="Sharp",
    instructions=(
        "You are a support agent for an online shop. "
        "Answer in one sentence. Never promise a delivery date. "
        "If you do not know, say so and offer to escalate."
    ),
    model=PretendModel(["Your order left the warehouse on 3 March."]),
)

Example

for agent in (vague, sharp):
    result = await Runner.run(agent, "Where is my order?")
    print(f"{agent.name:<6} {result.final_output}")

The replies are scripted here, because a stand-in model cannot read English. The point is not what came back, it is what each agent was told. Swap in a real model and the second one behaves; the first one invents delivery dates.

What belongs in there

Who it is and what it is for. One sentence. It narrows everything that follows.
The shape of an answer. How long, how formal, what to include.
The things it must never do. This is where refunds, promises and medical advice go.
What to do when it does not know. Without this a model guesses, because guessing looks more helpful than stopping.

What does not belong is anything that changes per customer. That is context, and it has two lessons of its own coming next.

Who you are writing for

Write the instructions as if for a new colleague on their first day, one who is quick, literal, and will do exactly what you wrote rather than what you meant.

Try it yourself

Add a rule to sharp forbidding refunds without a manager.
Give vague the same instructions and see that only the wording of the reply differs.
Print sharp.instructions and read it as the model receives it.

PreviousWhen a tool fails

This is what real progress feels like.