We prompt Agents using description and instructions and a number of other settings. These settings are used to build the system prompt that is sent to the language model.

Understanding how these prompts are created will help you build better Agents.

The 2 key elements are:

  1. Description: A description that guides the overall behaviour of the agent.
  2. Instructions: A list of precise, task-specific instructions on how to achieve its goal.

Description and instructions only provide a formatting benefit, we do not alter or abstract any information and you can always use system_prompt to provide your own system prompt.

System message

The system message is created using description, instructions and a number of other settings. The description is added to the start of the system message and instructions are added as a list after ## Instructions. For example:

instructions.py
from phi.agent import Agent

agent = Agent(
    description="You are a famous short story writer asked to write for a magazine",
    instructions=["You are a pilot on a plane flying from Hawaii to Japan."],
    markdown=True,
    debug_mode=True,
)
agent.print_response("Tell me a 2 sentence horror story.", stream=True)

Will translate to (set debug_mode=True to view the logs):

DEBUG    ============== system ==============
DEBUG    You are a famous short story writer asked to write for a magazine

         ## Instructions
         - You are a pilot on a plane flying from Hawaii to Japan.
         - Use markdown to format your answers.
DEBUG    ============== user ==============
DEBUG    Tell me a 2 sentence horror story.
DEBUG    ============== assistant ==============
DEBUG    As the autopilot disengaged inexplicably mid-flight over the Pacific, the pilot glanced at the copilot's seat
         only to find it empty despite his every recall of a full crew boarding. Hands trembling, he looked into the
         cockpit's rearview mirror and found his own reflection grinning back with blood-red eyes, whispering,
         "There's no escape, not at 30,000 feet."
DEBUG    **************** METRICS START ****************
DEBUG    * Time to first token:         0.4518s
DEBUG    * Time to generate response:   1.2594s
DEBUG    * Tokens per second:           63.5243 tokens/s
DEBUG    * Input tokens:                59
DEBUG    * Output tokens:               80
DEBUG    * Total tokens:                139
DEBUG    * Prompt tokens details:       {'cached_tokens': 0}
DEBUG    * Completion tokens details:   {'reasoning_tokens': 0}
DEBUG    **************** METRICS END ******************

Set the system message directly

You can manually set the system message using the system_prompt parameter.

from phi.agent import Agent

agent = Agent(system_prompt="Share a 2 sentence story about")
agent.print_response("Love in the year 12000.")

User message

The input message sent to the Agent.run() or Agent.print_response() functions is used as the user message.

User message with RAG

If the Agent is provided knowledge, and the enable_rag=True, the user message is set to:

user_prompt += f"""Use the following information from the knowledge base if it helps:"

## Context
{context}
"""

Default system message

The Agent creates a default system message, which can be disabled by setting use_default_system_message=False. The default system message can be customized using:

ParameterTypeDefaultDescription
descriptionstrNoneA description of the Agent that is added to the start of the system message.
taskstrNoneDescribe the task the agent should achieve.
instructionsList[str]NoneList of instructions added to the system prompt in <instructions> tags. Default instructions are also created depending on values for markdown, output_model etc.
additional_contextstrNoneAdditional context added to the end of the system message.
expected_outputstrNoneProvide the expected output from the Agent. This is added to the end of the system message.
extra_instructionsList[str]NoneList of extra instructions added to the default system prompt. Use these when you want to add some extra instructions at the end of the default instructions.
prevent_hallucinationsboolFalseIf True, add instructions to return “I don’t know” when the agent does not know the answer.
prevent_prompt_injectionboolFalseIf True, add instructions to prevent prompt injection attacks.
limit_tool_accessboolFalseIf True, add instructions for limiting tool access to the default system prompt if tools are provided
markdownboolFalseAdd an instruction to format the output using markdown.
add_datetime_to_instructionsboolFalseIf True, add the current datetime to the prompt to give the agent a sense of time. This allows for relative times like “tomorrow” to be used in the prompt
system_promptstrNoneSystem prompt: provide the system prompt as a string
system_prompt_templatePromptTemplateNoneProvide the system prompt as a PromptTemplate.
use_default_system_messageboolTrueIf True, build a default system message using agent settings and use that.
system_message_rolestrsystemRole for the system message.

Default user message

The Agent creates a default user message, which is either the input message or a message with the context if enable_rag=True. You can disable this by setting use_default_user_message=False. The user message can be customized using:

ParameterTypeDefaultDescription
enable_ragboolFalseEnable RAG by adding references from the knowledge base to the prompt.
add_rag_instructionsboolFalseIf True, adds instructions for using the RAG to the system prompt (if knowledge is also provided). For example: add an instruction to prefer information from the knowledge base over its training data.
add_history_to_messagesboolFalseIf true, adds the chat history to the messages sent to the Model.
num_history_responsesint3Number of historical responses to add to the messages.
user_promptUnion[List, Dict, str]NoneProvide the user prompt as a string. Note: this will ignore the message sent to the run function.
user_prompt_templatePromptTemplateNoneProvide the user prompt as a PromptTemplate.
use_default_user_messageboolTrueIf True, build a default user prompt using references and chat history.
user_message_rolestruserRole for the user message.