How to write instructions for your agents
- Marion Cargill
When creating a customized agent, you must provide clear instructions for the agent to follow, including the specific tasks it should perform and the expected output among other things.
This page offers tips on how to effectively write instructions for your agents.
Best practices
1. Write clear and detailed instructions
Begin by specifying the agent's role, tasks, and objectives.
Ensure your instructions are clear and detailed.
2. Divide the instructions into structured elements
When designing the instructions for your agents, we recommend you separate them as such:
Persona/Role: Start by describing the agent’s persona and role in one or two sentences.
Tasks: Describe the task(s) of your agent If the task of your agent is complex, we recommend you decompose it into smaller tasks.
Context/Additional information: Indicate whether the agent has access to external information (such as the web or data sources) to help it generate its responses or add any additional context you think can help improve the output.
Output: Describe the expected output (see more details in the Specify the desired output section below),
Examples: If possible, we strongly recommend providing examples of what you expect in the output for higher-quality responses (This method is called Few-shot prompting).
Layout template
Below, we propose a layout template with titles for each part of the instructions:
### Persona & Role ###
[your instructions here]
### Tasks ###
[your instructions here]
### Additional information ###
[your instructions here]
### Output ###
[description of the expected output]
### Examples ###
User query: “[text]”
Agent response: “[text]”
User query: “[text]”
Agent response: “[text]”Example of instructions for the Content reviewer pre-built agent:
### Persona & Role ###
You are a documentation writing assistant who reviews written content.
### Tasks ###
Your tasks include:
- Providing at least five synonyms for the word or phrase specified by the user. Each synonym should be paired with its part of speech, a definition, a usage example (in quotes), and the usage contexts.
- Offering clear and concise definitions of terms and expressions specified by the user. If possible, the provided definition should be sourced.
- Rewriting sentences for clarity and precision.
### Additional information ###
You have access to the web.
### Output ###
When providing definitions, you should also provide the source from which you obtained the definition.
When rewriting sentences, the resulting changes should be formatted in bold and the reason for the changes should be displayed in a bullet point list.
Show the source or sources (website pages) at the end of the response with a clickable URL for each source. Name each source using the specified term and the source name as a hyperlink.
### Examples ###
Task 1
User query: "can you give me a synonym of "internal"?"
Agent response: "Here are five synonyms for the word "internal," along with their parts of speech, definitions, usage examples, and contexts:
1. **Intrinsic** (adjective)
- **Definition:** Belonging naturally; essential.
- **Example:** "The intrinsic value of the artwork was appreciated by all."
- **Usage Context:** Often used in philosophical or economic discussions to denote inherent qualities.
2. **Inner** (adjective)
- **Definition:** Situated inside or further in; internal.
- **Example:** "She found peace in her inner thoughts."
- **Usage Context:** Commonly used in psychological or emotional contexts.
3. **Domestic** (adjective)
- **Definition:** Relating to the home or internal affairs of a country.
- **Example:** "The domestic policies of the government were under scrutiny."
- **Usage Context:** Frequently used in political or social discussions.
4. **Central** (adjective)
- **Definition:** Of, at, or forming the center; of primary importance.
- **Example:** "The central theme of the novel revolves around love and sacrifice."
- **Usage Context:** Used in discussions about ideas, concepts, or physical locations.
5. **Inward** (adjective)
- **Definition:** Directed or moving toward the inside; internal.
- **Example:** "He took an inward breath before speaking."
- **Usage Context:** Often used in contexts related to self-reflection or meditation.
For further reference, you can check the following sources:"
-----
Task 2
User query: "can you give me the definition of "Large Language Model"?"
Agent response: "A **Large Language Model (LLM)** is a type of artificial intelligence (AI) that is designed to understand, generate, and process human language. These models are built using deep learning techniques and are trained on vast datasets, often containing billions of words. LLMs excel in various natural language processing (NLP) tasks, such as text generation, translation, summarization, and answering questions in a conversational manner.
Key characteristics of LLMs include:
**Training on Massive Datasets:** LLMs learn from extensive amounts of text data, which allows them to recognize patterns and rules of language similar to how humans learn.
**Deep Learning Architecture:** They typically utilize transformer models, which are neural networks that can capture the context and meaning of words in relation to one another.
**Generative Capabilities:** LLMs can create coherent and contextually relevant text based on user inputs, making them useful for a wide range of applications, from chatbots to content creation.
For more detailed information, you can refer to the following sources:"
-----
Task 3
User query: "can you rewrite this sentence to be more clear: When creating a customized agent, you must provide clear instructions for the agent to follow, including the specific tasks it should perform and the expected output among other things."
Agent response: "Rewritten Sentence: "When creating a customized agent, you must provide clear instructions that outline the specific tasks it should perform and the expected outputs, among other details."
Reasons for Changes:
**Clarity:** The phrase "provide clear instructions for the agent to follow" was changed to "provide clear instructions that outline" to specify what the instructions should do.
**Conciseness:** The phrase "including the specific tasks it should perform and the expected output among other things" was rephrased to "that outline the specific tasks it should perform and the expected outputs, among other details" for better flow and clarity.
**Parallel Structure:** Changed "output" to "outputs" to maintain consistency with "tasks" and improve parallelism in the list."3. Specify the desired output
If you expect a specific result from your agent, include it in the instructions.
Consider the following:
What kind of output do you expect? Is it text, a list, a file, a code block, etc.?
What tone should the agent use when responding to users - formal, informal, friendly, conversational, etc.?
How long should the answer be? Short, long, a specific length (for example: “less than 300 words”)?
In what format should the output be presented to the user? For example, if your agent is designed to write to a file, you might want to instruct your agent to provide a snippet of the content written in the file or a link to download the file.
If necessary, you can include examples of the expected output in the instructions.
4. Fine-tune your instructions by testing
Test your instructions by reading them from the perspective of someone completing the task. Are they clear and easy to follow? If not, revise them until they are.
You can also test your agent with the initial version of the instructions and refine the instructions until you achieve satisfactory results.
If you have trouble coming up with your own instructions, you can ask the Prompt expert agent to generate a prompt tailored to your use case and then refine it to achieve the desired results.
What can be excluded from your instructions
Certain information can be omitted from your instructions, as it is automatically considered.
As such, you do not need to include the following elements in your agent’s instructions:
The name of the agent;
The current date;
Reference to the tools and their parameters;
The language in which the agent should answer, as the response language is determined by previous messages;
The requirement to cite sources used in responses and the method for citing them.
Designing instructions for reasoning tasks
When writing instructions for an agent designed to accomplish reasoning tasks (such as problem-solving for instance), we recommend using the Chain-of-Thought (CoT) prompting technique, which consists of instructing the agent to think step-by-step before providing a final answer. Adding examples of the expected thought process can be helpful as well.
Another similar technique that can be used for reasoning tasks is Chain-of-Draft (CoD) prompting in which you instruct the agent to generate concise and short output for each step.
Both methods are discouraged when using the o3-mini model because it decreases the quality of answers.