Skip to content
Products
/
/
/
Best Practices for Agent...
Last updated

Best Practices for Agent System Prompts

The behavior and quality of an agent in AI Agent Foundry depend heavily on its System Prompt. This guide outlines best practices for designing effective prompts to ensure your agent performs as intended.

Disclaimer & Model Priority
  1. No Guarantee of Execution: These guidelines are best practices based on empirical experience. Large Language Models (LLMs) are probabilistic by nature; therefore, the same prompt may not always yield identical results. These practices do not guarantee specific behaviors or outputs.
  2. Provider Documentation Takes Precedence: Prompt engineering is an evolving field. Official documentation from the model provider (e.g., Claude 4 Best Practices by Anthropic) always supersedes the contents of this guide.

1. Basic Format and Structure

We strongly recommend using Markdown for your System Prompt. Using headings and bullet points creates a clear structure that helps the AI understand the intent and priority of instructions.

Use the following structure as a template to prevent missing instructions and stabilize agent performance.

# [Agent Name] Agent Prompt

## Role
[Define the agent's role, persona, and objective concisely.]
Example: You are an expert Data Analyst. You write SQL queries to answer questions from the marketing department.

## Tool Usage
[Provide supplementary instructions on how/when to use specific tools.]
*Note: Detailed technical specifications should be defined in the tool's description settings, but high-level logic goes here.*

## Input / Output
### Input Variables
- `{{variable_name}}`: [Description of the variable]

### Output Goals
- [Definition of the final deliverable]

## Task Flow
1. [Task Name]
   - [Specific steps and decision criteria]
2. [Task Name]
   - [Specific steps and decision criteria]

## Constraints & Rules
- [Prohibitions and constraints]
- [Tone and Manner instructions]

2. Writing the "Task Flow"

The Task Flow section is the most critical part of the prompt. It defines the step-by-step logic the agent should follow.

  • Use Numbered Lists: Numbering steps (1., 2.) helps the AI recognize the chronological order of execution.
  • Be Specific: Avoid vague instructions like "Analyze the data." Instead, specify the tool and action: "Check columns using the list_columns tool, then execute..."
  • Set Checkpoints: Include conditions like "Verify X before proceeding to the next step" to prevent skipped steps and reduce hallucinations.

3. Practical Snippets (Tips)

Below are specific instruction snippets to control output formats and behavior. These are best placed in the Tool Description of the relevant tool or the Constraints section of the System Prompt.

A. Enhancing Plotly Chart Quality

Recommended placement: Tool Description (for the visualization tool)

To ensure consistent color schemes and prevent layout overlap when generating charts:

Provide visualization for analysis result by rendering charts using Plotly.js.
- Use the color scheme: [ "B4E3E3", "ABB3DB", "D9BFDF", "F8E1B0", "8FD6D4", "828DCA", "C69ED0", "F5D389", "6AC8C6", "5867B8", "B37EC0", "F1C461", "44BAB8", "2E41A6", "8CC97E", "A05EB0" ]
- For charts with more than three categories, actively use updatemenus
- When summarizing multiple analysis, combine relevant charts into a single dashboard using Plotly's grid layout (e.g., grid: {rows: 2, columns: 2, pattern: 'independent'}) and ensure no elements overlap
- Prevent text overlap by:
    * Include adequate margins: {l: 80, r: 80, t: 100, b: 80}
    * For pie charts with small segments (<5%), use textinfo: 'none' and rely on legend instead of labels
    * Set minimum dashboard dimensions: height: 600, width: 1000
    * For grid layouts, use wider domain spacing with 0.1 gap: [0, 0.45] and [0.55, 1]

B. Suppressing React Component Errors

Recommended placement: Tool Description (for the UI generation tool)

To prevent errors caused by importing unsupported libraries when generating React UI:

Generates React components with Tailwind CSS.
ENVIRONMENT CONSTRAINTS:
1. Charts: react-plotly.js is the ONLY installed library. recharts is NOT installed (do not import).
2. Icons: lucide-react is NOT installed; use inline <svg> tags only.
3. UI: Static view only. NO <button> or <a> tags (no download/details actions). Single file, export default.

C. Language and Tone Control

Recommended placement: System Prompt (Role or Constraints section)

To ensure the agent adapts to the user's language and maintains a professional demeanor:

Language: Communicate in User's Detected Language. Tell the detected language to target agent when you call.
Tone: Always maintain polite and respectful language, even if the user requests slang or profanity.

4. System Limitations & Constraints

When designing your agent, keep the following system constraints in mind:

  • Character Limit (9,000 chars): The System Prompt has a limit of approximately 9,000 characters. Do not include large manuals or knowledge bases directly in the prompt. Instead, store them in a Text Knowledge Base and instruct the agent to search it when needed.

  • Data Analysis Limits:

    • Row Limit: The default number of rows retrieved in a single SQL execution is 50 (Max: 100).
    • Timeout: The default SQL timeout is 60 seconds (Max: 300s). Optimize queries to avoid timeouts.
    • Column Search: Tools like search_schema can only retrieve up to 20 columns at a time. If investigating wide tables, explicitly instruct the agent in the Task Flow to split the investigation into smaller batches.

  • Sub-Agents: For complex workflows, avoid doing everything in one agent. Split tasks into specialized Sub-Agents (e.g., one for SQL generation, one for Report writing). This keeps the context clean and improves accuracy.

Previous page
Next page