> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/manual/agents/instructions.md).

# Instructions

Agent instructions define the behaviour of an AI agent while it completes a task. They tell the agent:

* who it is
* what it is responsible for
* what information it should use
* which tools it can use
* what it must and must not do
* how it should work through the task
* what a successful result should look like
* what to do when something is missing or ambiguous

A strong instruction is not just a better sentence. It is a clear behavioural contract.

> A good agent prompt removes ambiguity. A weak prompt leaves the model to guess.

## The agent instruction blueprint

Use these eight building blocks when you write instructions:

| Building block | Question it answers                                          |
| -------------- | ------------------------------------------------------------ |
| Role           | Who is the agent?                                            |
| Goal           | What must it achieve?                                        |
| Context        | What information should it use?                              |
| Tools          | Which capabilities can it use?                               |
| Rules          | What must or must not happen?                                |
| Workflow       | How should the task be executed?                             |
| Output         | What should the final result look like?                      |
| Edge cases     | What should the agent do when something fails or is missing? |

## 1. Define the role clearly

The role should explain the agent's responsibility, not just make it sound impressive.

Weak example:

> You are an expert.

Better example:

> You are a sales operations assistant responsible for retrieving current customer account information and answering account-related questions.

This is better because it defines the domain, the scope, and the type of work.

## 2. Define the goal

The role tells the agent who it is. The goal tells it what success looks like.

A useful goal is specific and outcome-focused.

Weak example:

> Help users with customer data.

Better example:

> Retrieve the latest customer account data from the CRM and answer the question using only the retrieved information.

## 3. Define the context and source of truth

Agents should know which information source they must rely on.

Good instructions explain where the truth comes from.

Examples:

* Use the CRM as the source of truth for current customer information.
* Use the knowledge base only for policy and product documentation.
* Do not rely on conversation history when current data is available.

This matters because agents often have access to multiple inputs: the user message, memory, files, APIs, tools, MCP servers, and knowledge bases. The instruction should give a clear priority.

## 4. Define tool use explicitly

When an agent has tools, it should know when to use them and what to do with the results.

Useful guidance includes:

* when to call a tool
* which data source to trust
* what to do when a tool returns no data
* what must never be invented

Example:

> Use the CRM tool when the user asks about a customer's current account state. Base the answer only on data returned by the CRM. Do not invent the account information.

Avoid writing instructions that describe the tool in detail. The tool definition already explains the tool. The prompt should describe the expected behaviour.

## 5. Add rules and boundaries

Rules define what the agent must not do.

These are often the most important instructions because they stop the agent from guessing or acting beyond its remit.

Examples:

* Never invent a customer, metric, or transaction.
* Never send an email without explicit user confirmation.
* Never expose credentials or internal system information.
* If the request is outside scope, explain that you cannot assist.
* Only use information retrieved from approved knowledge sources.

A good instruction defines both what the agent should do and what it should avoid.

## 6. Turn the task into a workflow

Many tasks are multi-step. If the agent is not told how to proceed, it may improvise.

Instead of:

> Generate a report.

Use:

> When generating a report:
>
> 1. Retrieve the required data.
> 2. Validate that all required inputs are available.
> 3. Calculate the required metrics using approved tools.
> 4. Build the report using the defined structure.
> 5. Return the final report with the required sections.

Workflow guidance works especially well for tasks with branching logic.

Example:

> If exactly one customer matches, continue.
>
> If multiple customers match, ask the user to clarify.
>
> If no customer matches, explain that the customer could not be found.

## 7. Define output format explicitly

An agent needs to know what a successful final answer should look like.

Weak example:

> Give the user a useful answer.

Better example:

> Return the response with:
>
> * customer name
> * account status
> * current subscription
> * relevant account information
> * source references
>
> Keep the answer concise and factual.

This matters whether the output is a summary, a report, a recommendation, or a structured response.

If the format matters, describe it directly.

## 8. Design for failure and ambiguity

A robust agent instruction always covers edge cases.

Ask questions like:

* What if required data is missing?
* What if the user request is ambiguous?
* What if multiple records match?
* What if a tool fails?
* What if the action is outside the agent's scope?
* What if the user asks for something the agent is not allowed to do?

Example:

> If required data is unavailable, do not estimate it. Explain which information is missing and ask the user for the missing details.

This prevents the agent from making up answers when the correct behaviour is to stop and ask for clarification.

## Example: complete agent instruction

Here is a practical example based on the prompt-training blueprint:

> You are a sales operations assistant responsible for helping sales representatives retrieve current customer account information.
>
> Use the CRM tool as the source of truth for current customer information. Do not rely on outdated conversation history when current data is available.
>
> When a user asks about a customer:
>
> 1. Identify the customer.
> 2. Search the CRM.
> 3. If exactly one customer matches, continue.
> 4. If multiple customers match, ask the user to clarify.
> 5. If no customer matches, explain that the customer could not be found.
> 6. Answer using the retrieved CRM information only.
>
> Never invent customer information. Never modify customer records unless the user explicitly asks to do so.
>
> Return the answer with the customer name, account status, current subscription, and relevant account information. Keep the response concise and factual.

This is stronger than a generic instruction because it adds role, source of truth, workflow, rules, and output requirements.

## Common mistakes

### 1. Being too vague

> Be helpful.

Instead:

> Answer account questions using only CRM data and explain when information is unavailable.

### 2. Describing the tool instead of the behaviour

> The CRM tool has functions X, Y, and Z.

This is unnecessary in most agent instructions. The tool metadata already tells the agent what it can do. The prompt should say when it should be used and how the result should influence the answer.

### 3. Forgetting edge cases

Only defining the happy path often creates unreliable results. Always define what happens when the expected information or action is unavailable.

### 4. Mixing unrelated responsibilities

A single agent should not be simultaneously a researcher, a CRM administrator, a financial analyst, and a customer support agent unless that combination is truly required. If responsibilities are too broad, consider splitting them into separate agents or sub-agents.

### 5. Over-constraining the agent

A long list of rules can make the agent brittle. Only define the constraints that truly matter.

## Prompt review checklist

Before publishing or enabling an agent, review the following:

* Role: Is the responsibility clear?
* Goal: Is the desired outcome clear?
* Context: Does the agent know which information sources to use?
* Tools: Does it know when to use important tools?
* Rules: Are key constraints explicit?
* Workflow: Is multi-step work broken down clearly?
* Decisions: Are important branches defined?
* Output: Is the expected result clearly specified?
* Edge cases: Does the agent know what to do when information is missing or ambiguous?
* Examples: Would an example make the expected behaviour clearer?

## Best practice summary

A strong agent instruction should be:

* specific
* unambiguous
* scoped to the actual task
* grounded in real sources of truth
* explicit about rules and failure handling
* clear about the output format
* easy to test and iterate

The goal is not to write the longest possible prompt. The goal is to make the agent's behaviour predictable.

> Good agent instructions are about clarity, boundaries, and repeatability.