Supplying instructions and context

When we define an agent with the SDK, we are not just creating a callable object. We are also shaping how that agent thinks, responds, and stays focused. Instructions and context are the primary tools we use to do that.

This lesson exists because most useful agents need more than raw user input. They need guidance about their role and background information about the situation they are operating in.

Providing high-level instructions to an agent

Instructions describe what the agent is and how it should behave. They are stable, high-level guidance rather than moment-to-moment prompts.

In the SDK, instructions are typically supplied when the agent is created. They act as a standing frame of reference for all future interactions.

from openai import OpenAI
from openai.agents import Agent

client = OpenAI()

agent = Agent(
    name="planet_writer",
    instructions="You write concise HTML descriptions of planets for a science website."
)

These instructions establish scope and intent. They do not ask the agent to do anything yet. They tell the agent how to approach future requests.

Supplying contextual information at startup

Context provides background information the agent can rely on when responding. This might include facts, constraints, or shared assumptions.

Startup context is often embedded directly into the instructions, especially when it rarely changes.

agent = Agent(
    name="planet_writer",
    instructions=(
        "You write concise HTML descriptions of planets for a science website. "
        "Assume the audience is curious but non-technical."
    )
)

This kind of context helps the agent make consistent choices without needing to restate the same information every time it is invoked.

Differentiating instructions from dynamic input

Instructions are not the same as user input. Instructions define behavior. Input triggers action.

When the agent runs, dynamic input is supplied separately and can change from call to call.

response = agent.run("Write a short page about Jupiter.")

The agent combines the stable instructions with the dynamic input to decide what to produce. Keeping these roles distinct makes agent behavior easier to reason about.

Controlling agent tone and scope through instructions

Tone, level of detail, and boundaries are best controlled through instructions rather than repeated prompting.

An instruction can constrain length, style, or subject matter without micromanaging output.

agent = Agent(
    name="planet_writer",
    instructions=(
        "You write short, neutral HTML descriptions of planets. "
        "Avoid speculation and do not include opinions."
    )
)

This approach keeps individual inputs simple while maintaining consistent output across many interactions.

Updating context without redefining the agent

Not all context needs to be baked into the agent definition. Some context can be supplied at runtime without changing the agent itself.

This allows the same agent to operate under different conditions while keeping its core identity intact.

response = agent.run(
    "Generate a page for Mars.",
    context={"page_type": "overview"}
)

Here, the agent remains the same, but the additional context influences how it interprets the request.

Conclusion

At this point, we know how to guide an SDK-defined agent using instructions and context. We understand how instructions establish behavior, how context provides background, and how dynamic input drives action.

That is enough to start shaping agents that behave consistently while still responding flexibly to new requests.