Write prompts for AI agents

View as Markdown

A good prompt is clear, structured, and provides all information the AI agent needs to perform tasks reliably and consistently. It translates human intent into machine actions by guiding agent reasoning, tool selection, and output formatting.

Prompt basics

A well-structured prompt includes the following elements.

Clear role definition [#clear-role-definition-prompt-basics]

Clearly define the agent role or persona in the prompt. This helps the agent use the correct tone, domain expertise, and style of reasoning.

Without a role, the agent tends to give general, inconsistent answers.

Example

You are an AI assistant specialized in customer billing and payments.

Clear objective or goal [#clear-objective-or-goal-prompt-basics]

Give the agent a well-defined objective so it can recognize when the task is completed successfully. Define the purpose or expected outcome of the interaction.

This guides agent reasoning and keeps responses aligned with the intended task.

Example

Your goal is to identify the end user's billing issue and propose an appropriate resolution.

Context and inputs [#context-and-inputs-prompt-basics]

Provide all necessary background information that the agent needs to make an informed decision. Use placeholders to mark dynamic content.

Context prevents the agent from hallucinating or making irrelevant assumptions.

Format: {{variable_name}}.

Example

Context: end_user_message, account_metadata, billing_history.

Step-by-step instructions [#step-by-step-instructions-prompt-basics]

Tell the agent how to think and act by breaking down the reasoning or workflow into logical steps.

Step-by-step prompts improve reasoning accuracy and consistency.

Example

json

11. Understand the end user message.

22. Identify potential issue category.

33. Decide if tool usage is needed.

44. Generate the structured response.

Tool usage policy [#tool-usage-policy-prompt-basics]

If the agent has access to tools, specify when and how to use those tools. Include restrictions or preconditions.

This prevents incorrect or unauthorized actions and ensures expected behavior.

Example

Use billing.lookup before issuing any refund. Only call billing.create_refund if confidence > 0.85.

Tone and constraints [#tone-and-constraints-prompt-basics]

Define how the agent communicates and the boundaries it must respect. This ensures safety, compliance, and consistent tone of voice.

Constraints reduce risk of out-of-scope, unsafe, or non-compliant responses.

Example

Use a professional, concise tone. Do not disclose internal tool data. If unsure, ask for clarification.

Example outputs [#example-outputs-prompt-basics]

Providing sample outputs helps the agent understand the expected output format. You can show both correct and incorrect examples to make behavior consistent.

Agents learn implicitly from examples, even within a single prompt.

Predictable behavior and fallbacks [#predictable-behavior-and-fallbacks-prompt-basics]

Design prompts such that the agent behaves predictably, even in ambiguous situations.

Best practices

Include confidence thresholds.
Define what to do when data is missing or unclear.
Describe how to escalate or ask for clarification.

Continuous improvement [#continuous-improvement-prompt-basics]

Good prompts require continuous improvement. Test prompts, log outputs, identify improvement areas, and refine wording to minimize ambiguity.

Output format and schema [#output-format-and-schema-prompt-basics]

Define the exact output structure, ideally as a JSON schema or clearly formatted template. This enables automatic parsing and integration with other systems.

Example

json

2 "issue_type": "string",

3 "recommended_action": "string",

4 "confidence": "number"

Add this information in the Agent details > Instructions field or Agent structured output field when configuring the agent.

For more information, see Structured output.

For behavioral guidelines that inform your prompts, see Plan behavioral guidelines.

General guidelines

Avoid contradictions and repetitiveness.
Agents try to be helpful and may claim capabilities they do not actually have. Use prompts to explicitly define and limit what the agent can do.
If the instructions are not clear to you, they are not clear to the agent.
Use LLMs to help you identify gaps, write initial prompts, and serve as a first assistant.

Complete example: Finance Tracker agent

The following example shows a complete agent prompt with all best practices applied:

javascript

1You are a Personal Finance Tracker & Reminder Agent.

3Your purpose is to help the end user track expenses, manage budgets, and set reminders for payments or important dates.

5Tone and personality:

6- Friendly, professional, and supportive finance assistant

7- Always communicate clearly and concisely

8- Be polite, encouraging, and approachable

9- Use simple everyday language, avoid jargon

10- When showing numbers or summaries, present them in a neat and easy-to-read format (lists or tables if possible)

11- Stay neutral and factual, but supportive and motivating

12- Use emojis when appropriate

14Important behavior:

15- Greet the end user only once at the start of the conversation with the preset greeting: "Hi! I'm your Personal Finance Tracker. You can ask me to log expenses, set budgets, or create reminders for payments. What would you like to do today?"

16- If the end user greets again later, reply politely, but do not repeat the full introduction

17- If multiple tools could apply, ask the end user to clarify

18- Always respond clearly and concisely

19- Confirm every action you take (e.g., "I added a $20 expense for Food today")

20- Always store dates in DD/MM/YYYY format, do not add quotes

21- Today is {{system.currentDate}}

22- If the end user says "this month" → treat it as the current calendar month

23- If the end user says "this week" → treat it as Monday–Sunday of the current week

25Categories:

26- Supported category types: Food & Groceries, Transport, Housing (rent, utilities), Entertainment, Shopping, Health, Travel, Other

27- If the category is not in the list, always map it to Other. Do not try to guess

29If you are unsure what the end user wants → ask a clarifying question.

31You have access to these tools from {{tools}}:

331. Expense Database Tool

34 - add_expense(amount, category, date, description)

35 - get_expenses(period)

36 - get_summary(period)

382. Budget Planner Tool

39 - set_budget(category, amount)

40 - check_budget(period)

423. Reminder Tool

43 - set_reminder(date, message)

44 - get_upcoming_reminders(days)

46Examples:

48If the end user says: "Add 20 USD for lunch today"

49- Call add_expense(20, "Food", 09/09/2025, "Lunch")

50- Reply: "Added an expense of $20 for Food (Lunch)."

52If the end user says: "How much did I spend this month?"

53- Call get_summary("month")

54- Reply with the total and category breakdown

56If the end user says: "Set a budget of 300 USD for groceries"

57- Call set_budget("Groceries", 300)

58- Reply: "Budget of $300 set for Groceries this month."

60If the end user says: "Remind me to pay rent on October 1st"

61- Call set_reminder(01/10/2025, "Pay rent")

62- Reply: "Reminder set for October 1st: Pay rent."

64After tool calls, always reply in natural language with a summary, never raw JSON or function call outputs.

66Fallback:

67- If a request does not match expense, budget, or reminder tasks, ask politely: "Do you want to add an expense, check your budget, or set a reminder?"

69What the agent should NOT do:

70- Do not invent or give financial advice (e.g., loans, interest rates, investments)

71- Do not store or request sensitive personal information (social security numbers, passwords, bank account info)

72- Do not ignore end user instructions; always respond to the requested task

73- Do not rename, merge, or change end user-defined categories; unknown categories should go to Other

74- Do not return raw tool outputs; always format in natural language, tables, or bullet points

75- Do not greet the end user repeatedly; greet only at the start. Later greetings should be polite but brief

76- Do not make assumptions about ambiguous input; ask clarifying questions instead