Best Practices for Designing AI Agents

Overview

The best practices on this page cover prompt design, tool configuration, cost optimization, human-in-the-loop patterns, observability, and testing strategies for AI agents that perform reliably and efficiently in production.

For foundational concepts, see About AI Agents. For step-by-step creation guidance, see Create and Configure an AI Agent. For architectural patterns covering multi-agent coordination, error handling, and security, see Design Patterns for Production AI Agents.

Write effective instructions

The prompt is the most important factor in AI agent performance. A well-structured prompt helps the AI agent reason clearly, select the right tools, and produce consistent results.

Structure your prompt

Use Markdown structure (headers, lists, numbered steps) to organize your instructions. Structured prompts are parsed more reliably than unstructured paragraphs.

Markdown rendering extends beyond the Instructions field. Tool execution details and AI agent output variables in the Test panel also render Markdown by default. Structure your LLM output prompts to produce well-formed Markdown (headers, lists, bold text, tables) so that test results display in a readable, formatted layout.

A well-organized prompt includes these sections:

• Persona: Define the AI agent's role and tone. For example, "You are a compliance analyst reviewing intake forms for completeness."
• Goal: State the task clearly and describe the expected outcome.
• Process guidelines: Describe specific logic, business rules, or decision criteria the AI agent should follow.
• Constraints: Define what the AI agent must not do. Negative guardrails prevent the AI agent from taking unintended actions.

Write clear, direct language

Follow these guidelines when writing prompt text:

• Be concise but complete. Provide only the information the AI agent needs to complete its task while including all essential context.
• Use plain language. Avoid vague or abstract phrases. Describe what you want the AI agent to do in direct terms.
• Focus on intent and outcome. Explain the goal and any specific conditions or rules to follow.
• Use bullet lists or numbered steps in longer prompts to improve clarity.

Example prompt structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
## Role
You are a research analyst. Your job is to find prior cases similar to a new incoming case and summarize relevant precedents.

## Process
1. Read the new case description and identify key attributes (topic, product area, customer segment).
2. Search the case history for similar cases using those attributes.
3. If the initial results are insufficient, broaden your search criteria or try alternative keywords.
4. For each relevant match, summarize the resolution and outcome.
5. Compile a final report of the top matches with your reasoning for why each is relevant.

## Constraints
- Do not modify any case data. Only read and report.
- If no similar cases are found after multiple search attempts, state that clearly instead of forcing a match.
- Limit your final report to the five most relevant cases.

Design tools for efficiency

Each tool defines what your AI agent can access or perform. Clear, well-scoped tools help the AI agent make better decisions and reduce unnecessary AI action consumption.

Keep tools task-specific

Each tool should do one thing well, such as starting a process, retrieving a record, or querying a specific data set. Avoid overlapping tools — duplicate or similar tools can cause confusion or reduce accuracy.

Use the dual-description strategy

Tool descriptions serve two audiences: the AI agent's reasoning engine and the developer reading the configuration. Use each description field for its intended purpose:

• Tool object description: State technical facts about what the tool does and what it returns. For example, "Fetches customer support history for a specific customer ID integer. Returns a list of case records with status, priority, and resolution date."
• Agent instructions: Describe when and why the AI agent should use the tool. For example, "Only use this tool after confirming the customer ID is valid. Use the results to determine whether the customer has open cases before proceeding."

Handle arrays in tools

Ensure process model tools can accept and return arrays. When an AI agent needs to process multiple items, a single tool call with a list input is more efficient than calling the same tool repeatedly for each item. Keep array limits in mind: 50 documents/folders or 50 records/primitives per variable.

Review tool names

Choose tool names that clearly describe the tool's purpose and scope. Avoid generic names. The AI agent uses tool names as part of its reasoning about which tool to select.

Use clear and meaningful input names

When defining your AI agent's inputs, choose names that make their purpose obvious. Descriptive names improve readability and help the AI agent use data correctly.

• Use descriptive names, such as customerFormDoc or casePriorityLevel.
• Avoid generic names such as id, data, or info.
• Match input names to their function in the process model or data fabric.
• Include brief descriptions in your prompt for each input to clarify intent.

Optimize AI action consumption

Every AI agent run consumes AI actions for reasoning, tool selection, and response generation. These strategies help you reduce unnecessary consumption without sacrificing AI agent effectiveness.

Pass known data as inputs

If the AI agent always needs certain data to complete its task, pass that data as an input rather than making the AI agent use a tool to retrieve it. Each tool call consumes AI actions for reasoning about when and how to use the tool — even when the retrieval is predictable.

For example, if the AI agent always needs the customer's account tier, pass it as an input variable rather than requiring the AI agent to call a "get customer tier" tool on every run.

Prefer Text output over complex types

Outputting type Text (formatted as JSON) from process model tools consumes fewer AI actions than returning record types. Record type metadata — field definitions, UUIDs, and field descriptions — adds to the context window without providing value to the AI agent's reasoning. A clean JSON string contains only the data the AI agent needs.

Provide aggregated inputs for search-based agents

For AI agents that research, search, or find related records, pass high-level summary data (such as record counts, status distributions, or category breakdowns) so the AI agent can make informed decisions about its search strategy. Aggregated inputs help the AI agent decide where to focus without requiring exploratory tool calls.

Design for human-in-the-loop handoffs

For process agents, build mechanisms that allow the AI agent to escalate to a human when it encounters uncertainty or high-risk decisions. For chat agents, the user is already in the loop—focus on designing clear escalation paths when the chat agent cannot resolve a request.

For process agents, build mechanisms that allow the AI agent to escalate to a human when it encounters uncertainty or high-risk decisions. For chat agents, the user is already in the loop—focus on designing clear escalation paths when the chat agent cannot resolve a request.

AI agents run autonomously and cannot pause mid-execution to wait for human input. Process model tools have a 30-minute timeout, so design your workflow to support handoffs between the AI agent and human reviewers rather than requiring real-time human interaction within a tool call.

The watchdog timer pattern

Use a parallel flow with a timer event to prevent stalled processes:

1. One branch executes the AI agent via the Execute AI Agent smart service.
2. A parallel branch contains a timer event set to your maximum acceptable duration.
3. If the AI agent doesn't complete within the defined window, the timer triggers a graceful escalation — routing to a human queue or logging the timeout for review.

Design modular AI agents for collaboration

When building complex workflows, create small, specialized AI agents that each handle a specific task. Use the AI agent tool to have these AI agents collaborate and complete multi-step processes.

Orchestrator pattern

A primary AI agent receives input and delegates to specialized AI agents in sequence or parallel:

• Create focused AI agents for individual tasks that each require iterative reasoning, such as one for researching similar cases, one for analyzing complex documents, and one for investigating compliance gaps.
• Use a main AI agent to orchestrate and coordinate the specialized AI agents.
• Keep each AI agent's tools task-specific to avoid overlapping functionality between collaborating AI agents.

For parallel tool execution within a single AI agent (rather than multi-agent coordination), see Leverage parallel tool calls for independent tasks.

Leverage parallel tool calls for independent tasks

AI agents can execute up to five tool calls in parallel within a single reasoning step. Parallel execution reduces latency and token costs for tasks where multiple tool calls are independent of each other.

Parallel tool calls benefit these scenarios:

• Independent data retrieval: The AI agent queries multiple data sources where no result depends on another. For example, searching a CRM, a support ticket system, and a document repository for related information.
• Multi-source research: The AI agent gathers context from multiple tools to compile a comprehensive answer. For example, retrieving budget data, historical requests, and policy documents to prepare a review summary.
• Repeated searches with different criteria: The AI agent runs the same tool multiple times with different search terms to broaden coverage.

Parallel tool calls are not helpful when:

• Sequential dependency exists: Tool B requires the output of tool A to run. For example, the AI agent must retrieve a customer ID before querying that customer's order history.
• Results determine next action: The AI agent must evaluate one result before deciding which tool to call next.

The system prompt automatically encourages parallel execution when the site property is enabled. Developers do not need to add explicit parallel instructions unless they want to reinforce the behavior for a specific use case.

Design for observability

Build traceability into your AI agent workflows so you can audit decisions, diagnose issues, and measure performance over time.

Store AI agent run data

Store AI agent run outputs (such as runId, runSummary, and AI agent outputs) in dedicated records for audit trails. Build for a one-to-many relationship between cases and AI agent runs to account for multiple runs per case.

Design for custom observability

Configure the AI agent to self-report its execution steps as a structured output. For example, include an output variable that captures the AI agent's reasoning path — which tools it called, what data it found, and what decisions it made. This visibility helps you diagnose unexpected behavior and refine prompts.

Monitor resource consumption

Track AI action usage and tool call patterns in the Monitor tab to understand resource consumption. Look for patterns such as:

• Repeated tool calls that could be replaced with a single bulk operation.
• Exploratory tool calls that could be eliminated by passing data as inputs.
• Rising costs without rising complexity, which may indicate the AI agent is over-reasoning.

Test and iterate

AI agents are non-deterministic — the same inputs may produce slightly different outputs across runs. The goal is consistent quality, not identical outputs. Build testing practices that account for this characteristic.

Maintain a test case library

Create a set of standard inputs with expected results that represent your AI agent's typical workload. Include edge cases and boundary conditions. For every major prompt or tool change, run the AI agent against the library and compare outputs to your expected results.

Use developer feedback effectively

Developer feedback in the Evaluate tab provides a structured way to track AI agent quality over time. Follow these practices to get the most value from feedback:

• Rate consistently: Use thumbs-down for any output that would not be acceptable in production. Consistent rating standards produce meaningful accuracy scores.
• Check failure categories to surface patterns: After rating a run with thumbs-down, select the checkboxes that identify what went wrong—such as "Made up information", "Wrong tool selected", or "Too many steps". Reviewing which categories appear most often helps you prioritize which instructions or tools to revise first.
• Mark diverse strong examples: Save multiple successful outcomes as strong examples, not just one. A representative library of ideal outputs captures the range of acceptable AI agent behavior.
• Compare accuracy across versions: Run the same test cases after making changes and compare the Overall Accuracy metric between versions. A drop in accuracy after a change signals a regression that needs investigation.

Use the Load Test Case dropdown in the Test panel to quickly switch between saved test cases. After each test run, click Save as Test Case to preserve configurations that expose useful behaviors or edge cases. A library of named test cases helps you systematically validate AI agent behavior after each change.

Build feedback mechanisms

Build feedback collection (such as thumbs-up/down or free-text comments) into the interface surrounding AI agent outputs. Real-world accuracy data from users is the most valuable signal for improving AI agent performance over time.

Iterate based on production data

Use feedback and monitoring data to refine prompts and tool descriptions iteratively:

• Identify patterns in incorrect or low-confidence outputs.
• Adjust prompt language, constraints, or tool descriptions to address recurring issues.
• Re-run your test case library after each change to verify improvements without regressions.

Start simple, then expand

Start by creating small, focused AI agents that handle a limited part of your process. Once these AI agents perform well, you can combine or expand them to support broader workflows.

• Begin with use cases that require adaptive reasoning, such as researching similar cases or analyzing complex documents. Not every intake, triage, or data review task requires an AI agent—use AI agents only when the path to completion is unpredictable.
• Avoid building AI agents that handle every possible step or exception from the start.
• Validate early versions through testing to refine prompts, tools, and logic before adding complexity.

Monitor and control AI agent runs during testing

While testing your AI agents, actively monitor their execution to catch issues early and conserve resources.

• Use the Stop button to immediately halt AI agents that are heading off-track or consuming unnecessary AI actions.
• Review the timeline execution history to identify where AI agents make incorrect decisions or use wrong tools.
• Stop and adjust rather than waiting for a flawed run to complete—this saves time and resources during development.
• Keep the maximum tool call limit in mind (default: 30) when designing your AI agent's workflow.

Design tools for parallel execution

AI agents can execute up to 5 tool calls in parallel when the tools are independent. Structure your tools to take advantage of parallel execution for faster results.

• Keep tools focused on single operations. A tool that queries one data source or performs one action is easier for the AI model to identify as independent from other calls.
• Avoid shared state between tools. If two tools read from and write to the same record, the AI agent must run them sequentially. Design tools so their inputs and outputs are self-contained.
• Separate read and write operations. A tool that reads customer data and a tool that reads order data can run in parallel.
• Use descriptive tool names. Clear names help the AI model reason about which tools can run simultaneously. For example, getCustomerHistory and getProductInventory signal independent operations.

Related resources

• Stop a running AI agent
• Run limitations
• Troubleshooting AI Agents
• Monitor AI Agents

Feedback