Write prompts for AI agents
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 the agent's reasoning, tool selection, and output formatting.
Prompt basics
Clear role definition
The prompt should clearly define the agent's role or persona. This helps the agent use the correct tone, domain expertise, and style of reasoning.
Example:
You are an AI assistant specialized in customer billing and payments.
Without a role, the agent tends to give general, inconsistent answers.
Clear objective or goal
The agent should have a well-defined objective so it can recognize when the task is completed successfully. Define the purpose or expected outcome of the interaction.
Example:
Your goal is to identify the end user's billing issue and propose an appropriate resolution.
This guides the agent's reasoning and keeps responses aligned with the intended task.
Context and inputs
Provide all necessary background information that the agent needs to make an informed decision. Use placeholders to mark dynamic content.
Format: {{variable_name}}.
Example:
Context: end_user_message, account_metadata, billing_history.
Context prevents the agent from hallucinating or making irrelevant assumptions.
Step-by-step instructions
Tell the agent how to think and act by breaking down the reasoning or workflow into logical steps.
Example:
Step-by-step prompts improve reasoning accuracy and consistency.
Tool usage policy
If the agent has access to tools, specify when and how those tools should be used. Include restrictions or preconditions.
Example:
Use billing.lookup before issuing any refund. Only call billing.create_refund if confidence > 0.85.
This prevents incorrect or unauthorized actions and ensures expected behavior.
Tone and constraints
Define how the agent should communicate and the boundaries it must respect. This ensures safety, compliance, and consistent tone of voice.
Example:
Use a professional, concise tone. Do not disclose internal tool data. If unsure, ask for clarification.
Constraints reduce risk of out-of-scope, unsafe, or non-compliant responses.
Example outputs
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
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
Good prompts require continuous improvement. Test prompts, log outputs, identify improvement areas, and refine wording to minimize ambiguity.
Output format and schema
Define the exact output structure, ideally as a JSON schema or clearly formatted template. This enables automatic parsing and integration with other systems.
Example:
Add this information in the Agent details > Instructions field or Agent structured output field when configuring the agent.
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 will not be 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: