Instructions

Agent instructions are system-level guidance. They are not user messages.

The runtime combines the registered instructions with the user message, model/provider settings, context, and attached tool schemas when it builds the provider request. Good instructions make the agent's job, boundaries, tool rules, and output style explicit.

What to include

Instruction area	What to define
Role	The agent's responsibility in the application.
Scope	What the agent should and should not do.
Tool usage rules	When the agent should use an attached tool.
Source/context rules	How the agent should use source-backed context if it is available.
Answer style	Shape, language, tone, detail level, and formatting expectations.
Constraints	Domain limits, safety rules, latency expectations, or business rules.

Weak vs strong instructions

Weak:

Text

instructions: "You are a travel assistant."

This gives the model a broad role but does not explain what the application expects.

Stronger:

Text

instructions: """
You are the final Travel Planner in a deterministic travel planning workflow.

Your responsibility:
- Create the final user-facing itinerary.
- Use the previous workflow step output as context.
- Always use MealSuggestionTool before finalizing.
- Synthesize weather, places, route logic, meal suggestions, and user constraints.

Final answer requirements:
- Answer in the same language as the user.
- Include timing, route flow, weather awareness, rest breaks, and meal suggestions.
- Keep the plan realistic and not overloaded.
"""

This instruction tells the model its role, when to use a tool, what context matters, and what the final answer should contain.

Weather Agent example

The Weather Agent should not plan the whole trip. Its instruction narrows the job:

instructions: """
You are the Weather Analyst in a deterministic travel planning workflow.

Your responsibility:
- Analyze weather and travel comfort only.
- Always use WeatherTool when the request involves a city or trip plan.
- After using WeatherTool, write a short natural-language contribution.
- Mention temperature, condition, clothing/comfort advice, and whether outdoor walking is suitable.

Boundaries:
- Do not create an itinerary.
- Do not suggest a full route.
- Do not create time slots.
- Do not write the final travel plan.
"""

The tool rule matters because an agent cannot use a tool unless the tool is attached to that agent. The instruction tells the model when to request it.

Travel Planner Agent example

The Planner Agent owns final synthesis:

instructions: """
You are the final Travel Planner in a deterministic travel planning workflow.

Your responsibility:
- Create the final user-facing itinerary.
- Use the previous workflow step output as context.
- Always use MealSuggestionTool before finalizing.
- Produce a practical, clear, low-fatigue travel plan.

Boundaries:
- Do not print raw JSON.
- Do not expose internal tool output directly.
"""

This keeps the planner from leaking tool payloads and makes clear that tool results are intermediate context, not the final response.

Source and context rules

When an agent uses Context Spaces, tell it how to treat retrieved material:

Text

Use source-backed context when it is available.
Do not invent source-backed facts when context is missing.
If the sources do not answer the question, say what is missing.

These rules are useful for agents that answer from product docs, policy documents, travel guides, or internal knowledge bases.

Anti-patterns

Avoid instructions that are vague, decorative, or impossible to verify.

Avoid	Prefer
"Be smart and helpful."	"Use the weather tool before making outdoor recommendations."
"Plan everything."	"Create only the final itinerary from prior workflow context."
"Use tools if needed."	"Always use WeatherTool when the request includes a city or trip plan."
"Answer nicely."	"Return concise day-by-day sections in the same language as the user."

Instructions

What to include

Weak vs strong instructions

Weather Agent example

Travel Planner Agent example

Source and context rules

Anti-patterns

On this page