{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Products","product_name":"AI Agent Foundry","type":"markdown"},"seo":{"title":"Best Practices for Agent System Prompts","description":"Treasure Data Product Documentation · Collect and Unify · Segment and Activate · Experiment and Analyze · Decisioning Automate with AI Scale and Trust.","siteUrl":"https://docs.treasuredata.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"best-practices-for-agent-system-prompts","__idx":0},"children":["Best Practices for Agent System Prompts"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The behavior and quality of an agent in AI Agent Foundry depend heavily on its ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["System Prompt"]},". This guide outlines best practices for designing effective prompts to ensure your agent performs as intended."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Disclaimer & Model Priority"},"children":[{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Provider Documentation Takes Precedence"]},": Prompt engineering is an evolving field. Official documentation from the model provider (e.g., ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices"},"children":["Claude 4 Best Practices"]}," by Anthropic) always supersedes the contents of this guide."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-basic-format-and-structure","__idx":1},"children":["1. Basic Format and Structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We strongly recommend using ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recommended-template","__idx":2},"children":["Recommended Template"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the following structure as a template to prevent missing instructions and stabilize agent performance."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"# [Agent Name] Agent Prompt\n\n## Role\n[Define the agent's role, persona, and objective concisely.]\nExample: You are an expert Data Analyst. You write SQL queries to answer questions from the marketing department.\n\n## Tool Usage\n[Provide supplementary instructions on how/when to use specific tools.]\n*Note: Detailed technical specifications should be defined in the tool's description settings, but high-level logic goes here.*\n\n## Input / Output\n### Input Variables\n- `{{variable_name}}`: [Description of the variable]\n\n### Output Goals\n- [Definition of the final deliverable]\n\n## Task Flow\n1. [Task Name]\n   - [Specific steps and decision criteria]\n2. [Task Name]\n   - [Specific steps and decision criteria]\n\n## Constraints & Rules\n- [Prohibitions and constraints]\n- [Tone and Manner instructions]\n\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-writing-the-task-flow","__idx":3},"children":["2. Writing the \"Task Flow\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Task Flow"]}," section is the most critical part of the prompt. It defines the step-by-step logic the agent should follow."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Use Numbered Lists"]},": Numbering steps (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1."]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2."]},") helps the AI recognize the chronological order of execution."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Be Specific"]},": Avoid vague instructions like \"Analyze the data.\" Instead, specify the tool and action: \"Check columns using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["list_columns"]}," tool, then execute...\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Set Checkpoints"]},": Include conditions like \"Verify X before proceeding to the next step\" to prevent skipped steps and reduce hallucinations."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-practical-snippets-tips","__idx":4},"children":["3. Practical Snippets (Tips)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Below are specific instruction snippets to control output formats and behavior. These are best placed in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tool Description"]}," of the relevant tool or the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Constraints"]}," section of the System Prompt."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"a-enhancing-plotly-chart-quality","__idx":5},"children":["A. Enhancing Plotly Chart Quality"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Recommended placement: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tool Description"]}," (for the visualization tool)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To ensure consistent color schemes and prevent layout overlap when generating charts:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Provide visualization for analysis result by rendering charts using Plotly.js.\n- Use the color scheme: [ \"B4E3E3\", \"ABB3DB\", \"D9BFDF\", \"F8E1B0\", \"8FD6D4\", \"828DCA\", \"C69ED0\", \"F5D389\", \"6AC8C6\", \"5867B8\", \"B37EC0\", \"F1C461\", \"44BAB8\", \"2E41A6\", \"8CC97E\", \"A05EB0\" ]\n- For charts with more than three categories, actively use updatemenus\n- 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\n- Prevent text overlap by:\n    * Include adequate margins: {l: 80, r: 80, t: 100, b: 80}\n    * For pie charts with small segments (<5%), use textinfo: 'none' and rely on legend instead of labels\n    * Set minimum dashboard dimensions: height: 600, width: 1000\n    * For grid layouts, use wider domain spacing with 0.1 gap: [0, 0.45] and [0.55, 1]\n\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"b-suppressing-react-component-errors","__idx":6},"children":["B. Suppressing React Component Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Recommended placement: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Tool Description"]}," (for the UI generation tool)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To prevent errors caused by importing unsupported libraries when generating React UI:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Generates React components with Tailwind CSS.\nENVIRONMENT CONSTRAINTS:\n1. Charts: react-plotly.js is the ONLY installed library. recharts is NOT installed (do not import).\n2. Icons: lucide-react is NOT installed; use inline <svg> tags only.\n3. UI: Static view only. NO <button> or <a> tags (no download/details actions). Single file, export default.\n\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"c-language-and-tone-control","__idx":7},"children":["C. Language and Tone Control"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Recommended placement: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["System Prompt"]}," (Role or Constraints section)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To ensure the agent adapts to the user's language and maintains a professional demeanor:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Language: Communicate in User's Detected Language. Tell the detected language to target agent when you call.\nTone: Always maintain polite and respectful language, even if the user requests slang or profanity.\n\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-system-limitations--constraints","__idx":8},"children":["4. System Limitations & Constraints"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When designing your agent, keep the following system constraints in mind:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Text Knowledge Base"]}," and instruct the agent to search it when needed."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Data Analysis Limits"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Row Limit"]},": The default number of rows retrieved in a single SQL execution is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["50"]}," (Max: 100)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Timeout"]},": The default SQL timeout is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["60 seconds"]}," (Max: 300s). Optimize queries to avoid timeouts."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Column Search"]},": Tools like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search_schema"]}," can only retrieve up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20 columns"]}," at a time. If investigating wide tables, explicitly instruct the agent in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Task Flow"]}," to split the investigation into smaller batches."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sub-Agents"]},": For complex workflows, avoid doing everything in one agent. Split tasks into specialized ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Sub-Agents"]}," (e.g., one for SQL generation, one for Report writing). This keeps the context clean and improves accuracy."]}]}]}]},"headings":[{"value":"Best Practices for Agent System Prompts","id":"best-practices-for-agent-system-prompts","depth":1},{"value":"1. Basic Format and Structure","id":"1-basic-format-and-structure","depth":2},{"value":"Recommended Template","id":"recommended-template","depth":3},{"value":"2. Writing the \"Task Flow\"","id":"2-writing-the-task-flow","depth":2},{"value":"3. Practical Snippets (Tips)","id":"3-practical-snippets-tips","depth":2},{"value":"A. Enhancing Plotly Chart Quality","id":"a-enhancing-plotly-chart-quality","depth":3},{"value":"B. Suppressing React Component Errors","id":"b-suppressing-react-component-errors","depth":3},{"value":"C. Language and Tone Control","id":"c-language-and-tone-control","depth":3},{"value":"4. System Limitations & Constraints","id":"4-system-limitations--constraints","depth":2}],"frontmatter":{"seo":{"title":"Best Practices for Agent System Prompts"}},"lastModified":"2026-02-02T08:58:51.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/customer-data-platform/ai-agent-foundry/ai-agent/system-prompt-best-practices","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}