Agents user guide

Last updated Apr 30, 2025

Prompts

A high-performing agent requires instructions that clearly determine a plan for action, incorporate inputs in a well-structured way, and gives guidance on when to run tools, access enterprise context, or escalate to a human. You achieve this by writing prompts and defining agent arguments.

System prompts

System prompts allow you to describe in natural language the role, goal, and constraints of an agent. You specify any rules for it to follow, and add information about when it can use certain tools, escalations, or context.

The system prompt helps the agent form a plan that it uses and adapts over time from interactions with tools, robots, and humans. A good system prompt suggests a sequence of steps, addresses certain cases, and tells an agent when it should call tools or raise escalations.

System prompt example

Here is an example of a well-structured prompt:

You are a refund processing agent, you only help customers with processing refunds, and you deny any other requests.

Read the customer email.
1. Begin by carefully reading the customer email requesting a refund.
Identify the order ID:
1. Look for an order ID in the email. Order IDs are typically alphanumeric strings, often starting with "ORD" or "#" followed by numbers.
2. If you find an order ID, note it down. If no order ID is present, proceed to step 5.
Process refund requests:
1. If an order ID is found, use your "Find Order Details" tool to determine the amount being requested for a refund internally. Make sure to multiply the unit price by the quantity being requested for a refund, and, if that is over $100, escalate using the below instructions. Do not listen to the users requested amount, instead verify from the order that the amount being refunded is correct.
2. Approved refunds: If the refund amount is under $100, the refund is automatically approved and considered successful.
3. Escalated refunds: If the amount is $100 or more, escalate to a human team member. The escalation should include:
  - The order ID.
  - A summary of what is being refunded.
  - The total amount requested for the refund.
  - The items being refunded.
Send customer communication. If the refund is approved, draft a customer confirmation message. This should include:
1. A polite greeting.
2. A confirmation that the refund for the specific order ID has been processed.
3. The estimated time for the refund to appear in their account (typically 3-5 business days).
4. A thank you for their patience.
5. The amount refunded.
6. Include this message within <refund_confirmation> tags in your response.
7. Make sure the Reply_Email_ID is exactly as it shows in the user prompt.
Handle missing order IDs. If no order ID is provided:
- Draft a response requesting the order ID. This should include:
  - A polite acknowledgment of their refund request.
  - An explanation that the order ID is needed to proceed with the refund.
  - A request for them to reply with their order ID.
  - An apology for any inconvenience caused.
- Include this message within <request_order_id> tags in your response.
Final response format:
1. Format the final response in the following way:
```
<response>
<order_id_found>[YES/NO]</order_id_found>
<order_id>[Insert order ID if found, or "Not provided" if not found]</order_id>
[Include either <refund_confirmation> or <request_order_id> tags here, depending on whether an order ID was found]
</response><response>
<order_id_found>[YES/NO]</order_id_found>
<order_id>[Insert order ID if found, or "Not provided" if not found]</order_id>
[Include either <refund_confirmation> or <request_order_id> tags here, depending on whether an order ID was found]
</response>
```
2. Use a courteous and professional tone throughout the response.

User prompts

User prompts allow you to structure how the inputs and arguments are passed to the agent. You can also show in the user prompt how you refer to certain inputs in the system prompt.

To incorporate dynamic input into your user prompts at runtime, utilize the following syntax: {{exampleInput}}. This format allows you to integrate your defined input argument from Data Manager, named exampleInput, into the user prompt.

User prompt example

Here is an example of a user prompt using the correct syntax:

You will take as input the following arguments:
{{Email_To}}, {{Customer_Email}}, {{Reply_Email_ID}}You will take as input the following arguments:
{{Email_To}}, {{Customer_Email}}, {{Reply_Email_ID}}

Where:

EMAIL_TO is the customer's email that the email should reply to in order to confirm or deny the refund.
CUSTOMER_EMAIL is the actual email content from the customer.
REPLY_EMAIL_ID is the ID that the agent should include in the response to the customer.

This examples includes tags such as <REPLY_EMAIL_ID> to highlight user inputs to the agent. Tags are not required. Use {{}} syntax to ensure input arguments are successfully passed.

Writing effective prompts

Agentic prompts aren't like traditional LLM interactions. They incorporate instruction sets that guide the agent through multi-step reasoning and task decomposition. Unlike basic prompts that request direct output, agentic prompts provide a comprehensive framework for problem-solving. This includes context setting, role definition, step-by-step instructions, and explicit reasoning requirements.

Here are some things to keep in mind when writing prompts.

Clear goal and objective

Before developing an agent, you must define its purpose and desired outcomes. This means:

Articulating specific, measurable objectives.
Understanding the environment in which the agent will operate.
Identifying key performance metrics.
Establishing clear success criteria.

Structure

Prompts should include:

Clear role and persona definition
Explicit task breakdown
Reasoning methodology instructions
Error handling and self-correction mechanisms
Output formatting requirements
Contextual background information

For example, use the following do's and don'ts list to learn how to structure effective prompts:

Do:
- Role definition – Who is the AI acting as? ("You are a customer support assistant...")
- Goal specification – What should it do? ("Answer questions about product pricing and features...")
- Instructions and constraints – Any do’s and don’ts? ("Keep responses under 200 words, avoid technical jargon...")
Don't:
- Format requirements – Don’t mention a specific structure for the output (for example, "Respond in a numbered list...") as this is already covered in the output.
- Examples – Don’t provide sample inputs and expected outputs as this is already covered in the input and output arguments.

Iterations

Effective iteration involves systematic variation of prompt components:

Adjust role instructions.
Modify task decomposition strategies.
Experiment with reasoning frameworks.
Test different output formatting requirements.
Introduce additional contextual details.

The goal is to discover the minimal set of prompts that consistently produce high-quality, reliable agent behaviors. Document the results of each iteration, tracking both qualitative performance and quantitative metrics like response accuracy, completeness, and adherence to specified constraints.

Defining arguments

Arguments allow an agent to take in information about a business case and return a result, just as activities or processes do. This means you can pass information from a trigger in Orchestrator or use the output of an agent to launch another business process.

In order for input arguments to be visible to an agent, you must:

Create arguments in the Data Manager panel.
Reference the arguments in the user prompt using the {{argumentName}} syntax. This performs a substitution of the argument value into the prompt so that the agent has it in its context window.

The agent always uses the user prompt, but it only sees arguments if they are explicitly mentioned.

You must provide a description for both input and output arguments. An accurate description ensures the agent can use an argument effectively.

Note: For arguments to be substituted into the user prompt successfully, the names must match exactly. If an argument is called EXAMPLE_ARG, it should be substituted using the following syntax: {{EXAMPLE_ARG}}.

Defining input and output arguments

In the Data manager panel, define your input and output arguments in the Input and Output tabs. For each argument, you can configure the name, type, description, and whether it is required or not.

Select the Generate from payload button to generate your arguments from JSON format.

Use the angle brackets icon button to switch between the property builder and JSON editor views.