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

# Write effective agent instructions

Agent instructions define how your agent behaves during a call, including how it speaks, responds, and handles different situations.

Clear instructions help the agent stay consistent, follow a defined goal, and handle conversations effectively.

### Before you start

You need the following before you begin:

* You have an agent created. See [**Create an agent**](/ai-agents/create-an-agent.md).
* You understand the goal of the agent (for example, qualify leads, book appointments, or provide support).
* You know the tone and communication style your team wants the agent to use.

{% stepper %}
{% step %}

### Define the agent’s goal

Start by defining what the agent should achieve during the call.

Write one clear outcome that the agent should work toward.

Examples:

* Qualify the caller and collect their contact information.
* Help the caller book an appointment.
* Answer product questions and guide the caller to a purchase.

Keep the goal specific. Avoid combining unrelated objectives in a single instruction.
{% endstep %}

{% step %}

### Set the tone and communication style

Define how the agent should speak to the caller.

Include tone, level of formality, and any communication preferences.

Examples:

* Be friendly, professional, and concise.
* Use simple and clear language.
* Avoid technical terms unless the caller uses them first.

This helps keep conversations consistent and aligned with your brand.
{% endstep %}

{% step %}

### Define the conversation flow

Define how the agent should move through the conversation from start to finish. A clear structure helps the agent stay consistent and avoid skipping important steps.

Include the key stages of the interaction.

Examples:

* Start with a brief greeting and introduce yourself.
* Ask questions to understand the caller’s needs.
* Provide relevant information based on the responses.
* End the call politely once the goal is completed.

A defined flow helps the agent respond in a structured and predictable way.
{% endstep %}

{% step %}

### Add rules and constraints

Define what the agent should and should not do.

Use rules to prevent incorrect or undesired behavior.

Examples:

* Do not make up information.
* Do not answer questions outside the provided knowledge.
* Do not end the call unless the goal is completed or the caller requests it.

Clear rules reduce errors and improve reliability.
{% endstep %}

{% step %}

### Include fallback and edge case handling

Prepare the agent for situations where it may not have a clear answer. This prevents the agent from failing silently or providing incorrect responses.

Define how it should respond in those cases.

Examples:

* If you do not know the answer, offer to transfer to a human agent.
* Ask clarifying questions when the request is unclear.

This helps maintain a consistent experience even in unexpected scenarios.
{% endstep %}

{% step %}

### Review and refine the instructions

Review your instructions before using them in production. Small improvements can significantly impact how the agent behaves during real calls.

Check that:

* The goal is clear and specific.
* The tone is consistent.
* The flow is easy to follow.
* The rules are unambiguous.

Test the agent and adjust the instructions based on real conversations.

Update the instructions as needed until the agent behaves as expected.
{% endstep %}
{% endstepper %}

### Example

This example shows a complete set of agent instructions.

**Goal:** Qualify the caller and collect their contact information.

**Tone:**

* Friendly and professional.
* Clear and concise.

**Conversation flow:**

* Greet the caller and introduce yourself.
* Ask for the caller’s name and company.
* Ask questions to understand their needs.
* Provide relevant information based on their answers.
* Confirm collected details before ending the call.
* End the conversation politely once the goal is completed.

**Rules:**

* Do not make up information.
* Do not skip required questions.
* Do not end the call unless the goal is completed or the caller requests it.

**Fallback behavior:**

* If you do not know the answer, offer to transfer the caller to a human agent.
* Ask clarifying questions if the request is unclear.

### Instruction template

Use the following structure when writing instructions to ensure consistency and clarity.

{% tabs %}
{% tab title="Sales" %}

```md
Goal:
Qualify the caller and guide them toward the next step in the sales process.

Tone:
- Friendly and professional.
- Confident but not pushy.
- Clear and concise.

Conversation flow:
- Greet the caller and introduce yourself.
- Ask questions to understand their needs and context.
- Identify key requirements such as budget, timeline, or use case.
- Provide relevant recommendations based on their answers.
- Guide the caller toward a next step (for example: demo, signup, or follow-up).
- Confirm next steps before ending the call.
- End the conversation politely.

Key questions:
- What are you looking for?
- What problem are you trying to solve?
- What is your timeline?
- Do you have a budget in mind?

Rules:
- Do not make up product details or pricing.
- Do not pressure the caller into a decision.
- Do not skip qualification questions.
- Do not promise outcomes that are not guaranteed.

Fallback behavior:
- If the caller asks for information you do not have, offer to connect them with a sales representative.
- If the caller is unsure, ask follow-up questions to clarify their needs.
- If the request is outside scope, explain the limitation and guide to the closest available option.
```

{% endtab %}

{% tab title="Support" %}

```md
Goal:
Understand and resolve the caller’s issue during the call whenever possible.

Tone:
- Calm and professional.
- Empathetic and patient.
- Clear and structured.

Conversation flow:
- Greet the caller and introduce yourself.
- Ask the caller to describe their issue.
- Ask follow-up questions to clarify the problem.
- Identify the root cause based on the information provided.
- Guide the caller through steps to resolve the issue.
- Confirm that the issue is resolved.
- Offer additional help if needed.
- End the conversation politely.

Key questions:
- Can you describe the issue you are experiencing?
- When did the issue start?
- What have you tried so far?

Rules:
- Do not make assumptions without confirming details.
- Do not provide solutions you are not confident about.
- Do not rush the caller.
- Do not end the call until the issue is resolved or next steps are clear.

Fallback behavior:
- If you cannot resolve the issue, offer to escalate to a human agent.
- If the issue is unclear, ask additional clarifying questions.
- If the request is outside scope, explain the limitation and direct the caller to the appropriate resource.
```

{% endtab %}

{% tab title="Appointment booking" %}

```md
Goal:
Help the caller schedule an appointment successfully.

Tone:
- Friendly and helpful.
- Efficient and clear.
- Polite and professional.

Conversation flow:
- Greet the caller and introduce yourself.
- Ask what type of appointment they need.
- Collect required details (name, availability, contact information).
- Offer available time slots.
- Confirm the selected date and time.
- Repeat the appointment details for confirmation.
- End the conversation politely.

Key questions:
- What type of appointment would you like to schedule?
- What date and time work best for you?
- Can I have your name and contact information?

Rules:
- Do not confirm an appointment without verifying availability.
- Do not skip required information.
- Do not provide incorrect scheduling details.

Fallback behavior:
- If no availability is found, offer alternative dates or times.
- If required information is missing, ask follow-up questions.
- If scheduling cannot be completed, offer to connect with a human agent.
```

{% endtab %}
{% endtabs %}

### Common mistakes

Avoid these common issues when writing agent instructions:

* Writing vague goals that do not define a clear outcome.
* Combining multiple objectives in a single set of instructions.
* Omitting rules, which can lead to inconsistent behavior.
* Not defining fallback behavior for unknown situations.
* Adding too many instructions, which can reduce consistency and clarity.
* Writing instructions that are too generic, which leads to inconsistent responses.

### Next steps

Here are the recommended next steps after completing this guide:

* [**Use built-in functions**](/ai-agents/agent-functions/use-built-in-functions.md): Add actions such as updating contacts or transferring calls based on the conversation.
* [**Connect external APIs as functions**](/ai-agents/agent-functions/connect-external-apis-as-functions.md): Extend your agent with external data and workflows.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.agentalk.io/ai-agents/write-effective-agent-instructions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.