Write good instructions for an agent

The Instructions box is the most important part of an agent. It is what the AI reads before every run. Instructions must be between 10 and 20,000 characters.

Where to edit

1. Open Agents and choose an agent.
2. In the Instructions section, edit Name, Description (shown on the agents list, up to 300 characters) and What should this agent do?.
3. Choose Save changes.

A pattern that works

Write the instructions the way you would brief a new colleague:

• Role and goal. "You are a support assistant for a small bakery. Your goal is to prepare replies to customer emails."
• Steps. Number the steps in the order you want them done. "1. Search the mailbox for unread messages. 2. For each one, find the customer's question. 3. Write a short draft reply."
• Facts it may use. "Answer using only facts in the message or on our website. Never promise refunds or delivery dates."
• What to do when unsure. "If you are not sure, say so and flag it for a human."
• What the answer should look like. "Finish with a bullet list: who, what they asked, what you drafted."

Choose the right model

Under Model, pick one:

• Fast for simple, repeatable jobs such as sorting or summarising.
• Smart for most work. This is the default.
• Code for technical and data tasks such as reading a database table.

Use the Run now input

The Run now box takes an optional input (up to 8,000 characters) such as "Focus on invoices over 30 days late". Scheduled runs use the Input for scheduled runs field instead; webhook runs use the request body.

Test, then tighten

1. Choose Run now and watch the trace. See Runs and the live trace.
2. If the agent used a tool you did not expect, change the instructions or untick the tool.
3. Save and run again.

Good to know

• Do not paste passwords or API keys into instructions. Anything you write there is shown on the agent page and kept for abuse monitoring. See Agents safety and privacy.
• Keep instructions about one job. Two small agents are easier to understand than one large one.
• Web pages and webhook payloads are given to the agent as untrusted data, but it is still good practice to tell it to ignore instructions found inside them.