Context engineering is the process of designing and controlling the information (context) that is sent to language models to guide their behavior and outputs. In Agno, this means carefully crafting the system message, which includes the agent’s description, instructions, and other relevant settings. By thoughtfully engineering this context, you can:
  • Steer the agent toward specific behaviors or roles.
  • Constrain or expand the agent’s capabilities.
  • Ensure outputs are consistent, relevant, and aligned with your application’s needs.
  • Enable advanced use cases such as multi-step reasoning, tool use, or structured output.
Effective context engineering involves iteratively refining the system message, experimenting with different descriptions and instructions, and leveraging features like input/output schemas or tool integrations. The context of an Agno agent consists of the following:
  • System message: The system message is the main context that is sent to the agent, including all additional context
  • User message: The user message is the message that is sent to the agent.
  • Chat history: The chat history is the history of the conversation between the agent and the user.
  • Additional input: Any few-shot examples or other additional input that is added to the context.

System message context

The following are some key parameters that are used to create the system message:
  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.
  3. Expected Output: A description of the expected output from the Agent.
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. For example:
from agno.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,  # Set to True to view the detailed logs and see the compiled system message
)
agent.print_response("Tell me a 2 sentence horror story.", stream=True)
Will produce the following system message:
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.
</instructions>

<additional_information>
- Use markdown to format your answers.
</additional_information>

Additional Context

You can add additional context to the end of the system message using the additional_context parameter. In this example, we add additional context to the system message that the agent has access to specific tables in a database.
from textwrap import dedent

from agno.agent import Agent
from agno.models.langdb import LangDB
from agno.tools.duckdb import DuckDbTools

duckdb_tools = DuckDbTools(
    create_tables=False, export_tables=False, summarize_tables=False
)
duckdb_tools.create_table_from_path(
    path="https://phidata-public.s3.amazonaws.com/demo_data/IMDB-Movie-Data.csv",
    table="movies",
)

agent = Agent(
    model=LangDB(id="llama3-1-70b-instruct-v1.0"),
    tools=[duckdb_tools],
    markdown=True,
    additional_context=dedent("""\
    You have access to the following tables:
    - movies: contains information about movies from IMDB.
    """),
)
agent.print_response("What is the average rating of movies?", stream=True)

System message Parameters

The Agent creates a default system message that can be customized using the following parameters:
ParameterTypeDefaultDescription
descriptionstrNoneA description of the Agent that is added to the start of the system message.
instructionsList[str]NoneList of instructions added to the system prompt in <instructions> tags. Default instructions are also created depending on values for markdown, expected_output 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.
markdownboolFalseAdd an instruction to format the output using markdown.
add_datetime_to_contextboolFalseIf 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
add_name_to_contextboolFalseIf True, add the name of the agent to the context.
add_location_to_contextboolFalseIf True, add the location of the agent to the context. This allows for location-aware responses and local context.
add_session_summary_to_contextboolFalseIf True, add the session summary to the context. See sessions for more information.
add_memories_to_contextboolFalseIf True, add the user memories to the context. See memory for more information.
add_dependencies_to_contextboolFalseIf True, add the dependencies to the context. See dependencies for more information.
add_knowledge_to_contextboolFalseIf True, add retrieved knowledge to the context, to enable RAG. See knowledge for more information.
system_messagestrNoneOverride the default system message.
build_contextboolTrueOptionally disable the building of the context.
See the full Agent reference for more information.

Set the system message directly

You can manually set the system message using the system_message parameter. This will ignore all other settings and use the system message you provide.
from agno.agent import Agent

agent = Agent(system_message="Share a 2 sentence story about")
agent.print_response("Love in the year 12000.")
Some models via some model providers, like llama-3.2-11b-vision-preview on Groq, require no system message with other messages. To remove the system message, set build_context=False and system_message=None. Additionally, if markdown=True is set, it will add a system message, so either remove it or explicitly disable the system message.

User message

The input sent to the Agent.run() or Agent.print_response() is used as the user message. See dependencies for how to do dependency injection for your user message.

Chat history

If you have database storage enabled on your agent, session history is automatically stored (see sessions). You can now add the history of the conversation to the context using add_history_to_context.
from agno.agent.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIChat

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

db = PostgresDb(db_url=db_url)

agent = Agent(
    model=OpenAIChat(id="gpt-5-mini"),
    db=db,
    session_id="chat_history",
    instructions="You are a helpful assistant that can answer questions about space and oceans.",
    add_history_to_context=True,
    num_history_runs=2,  # Optionally limit the number of history responses to add to the context
)

agent.print_response("Where is the sea of tranquility?")

agent.print_response("What was my first question?")
This will add the history of the conversation to the context, which can be used to provide context for the next message. See more details on sessions.

Additional input

You can add entire additional messages to your agent’s context using the additional_input parameter. These messages are added to the context as if they were part of the conversation history. You can give your agent examples of how it should respond (also called “few-shot prompting”):
from agno.agent import Agent
from agno.models.message import Message
from agno.models.openai.chat import OpenAIChat

# Few-shot examples showing good support patterns
support_examples = [
    # Example 1: Simple issue resolution
    Message(role="user", content="I forgot my password and can't log in"),
    Message(
        role="assistant",
        content="""
    I'll help you reset your password right away.

    **Steps to Reset Your Password:**
    . Go to the login page and click "Forgot Password"
    . Enter your email address
    . Check your email for the reset link
    . Follow the link to create a new password
    . Use a strong password with uppercase, lowercase, numbers, and symbols

    f you don't receive the email within 5 minutes, please check your spam folder. Let me know if you need any assistance with these steps!
    """.strip(),
    ),
    # Example 2: Billing issue pattern
    Message(
        role="user",
        content="I've been charged twice for the same order and I'm frustrated!",
    ),
    Message(
        role="assistant",
        content="""
    I sincerely apologize for the billing error and the frustration this has caused you.

    **Immediate Action Plan:**
    1. I'll investigate your account to confirm the duplicate charge
    2. Process a full refund for the duplicate transaction
    3. Ensure this doesn't happen again by checking your payment method settings
    4. Provide you with a confirmation number once the refund is processed

    The refund typically takes 3-5 business days to appear on your statement. As an apology for this inconvenience, I'd also like to offer you a 10% discount on your next order.

    Is there anything else I can help you with regarding this issue?
    """.strip(),
    ),
    # Example 3: Technical support pattern
    Message(role="user", content="Your app keeps crashing when I try to upload photos"),
    Message(
        role="assistant",
        content="""
    I'm sorry you're experiencing crashes with photo uploads. Let me help you troubleshoot this issue.

    **Troubleshooting Steps:**
    1. **Check App Version:** Ensure you have the latest version from the app store
    2. **Restart the App:** Close completely and reopen the application
    3. **Check Storage:** Make sure you have sufficient device storage (at least 1GB free)
    4. **Photo Size:** Try uploading smaller photos (under 10MB each)
    5. **Network Connection:** Ensure you have a stable internet connection

    **If the issue persists:**
    - Try uploading one photo at a time instead of multiple
    - Clear the app cache in your device settings
    - Restart your device

    If none of these steps resolve the issue, please let me know your device type and OS version, and I'll escalate this to our technical team for further investigation.
    """.strip(),
    ),
]

if __name__ == "__main__":
    # Create agent with few-shot learning
    agent = Agent(
        name="Customer Support Specialist",
        model=OpenAIChat(id="gpt-5-mini"),
        add_name_to_context=True,
        additional_input=support_examples,  # few-shot learning examples
        instructions=[
            "You are an expert customer support specialist.",
            "Always be empathetic, professional, and solution-oriented.",
            "Provide clear, actionable steps to resolve customer issues.",
            "Follow the established patterns for consistent, high-quality support.",
        ],
        markdown=True,
    )

    for i, example in enumerate(support_examples, 1):
        print(f"📞 Example {i}: {example}")
        print("-" * 50)
        agent.print_response(example)

Developer Resources