Prompt Configuration - Artaios Documentation

Overview

Artaios’s PromptConfig provides sophisticated prompt engineering capabilities through dynamic context control, few-shot examples, and intelligent history management. This enables precise control over what information reaches your LLM.

Core Concepts

Message Ordering

Artaios constructs prompts in an optimal order for LLM attention:

System Prompt

Highest attention - Behavioral instructions and role definition

Few-Shot Examples

Teaching patterns - Static examples showing desired behavior

Conversation History

Dynamic context - Previous messages (configurable)

Current User Input

Highest attention - The current task or question

This ordering leverages the primacy and recency effects in LLM attention, placing the most important information at the beginning and end.

PromptConfig Schema

prompt_config:
  system_prompt: string              # Core behavioral instructions (supports template variables)
  include_user_input: bool           # Include current user message (default: true)
  include_history: bool | int        # History control (default: true)
  include_media_in_history: bool     # Strip media from history (default: false)
  include_internal_messages: bool    # Include internal agent outputs (default: true)
  few_shot_examples: list            # Teaching examples (default: [])

Template Variables

Artaios supports dynamic template variables in your system_prompt using {{ variable }} syntax. Variables are substituted recursively before the prompt is sent to the LLM, enabling powerful dynamic context injection.

Variable Categories

Custom Variables

Dynamic values from the variables system: {{ variables.name }}

Prompt Library

Access stored prompts from database: {{ prompts.name }}

User Input

Current user message content: {{ user_input }}

Conversation History

User-visible message history: {{ history }} / {{ history[N] }}

Full Execution History

Complete trace with internal messages: {{ full_history }}

Structured Outputs

Data from previous agents: {{ agent.output.field }}

Agent Outputs

Non-structured agent responses: {{ agent.output }}

1. Prompt Library Variables

Access reusable prompts stored in the database with automatic user/company scoping.

Variable	Description	Example
`{{ prompts.prompt_name }}`	Latest version of named prompt	`{{ prompts.system_instructions }}`
`{{ prompts.prompt_name.version }}`	Specific version number	`{{ prompts.guidelines.2 }}`

Example:

agents:
  - name: support_agent
    prompt_config:
      system_prompt: |
        {{ prompts.base_instructions }}
        
        ## Company Guidelines
        {{ prompts.support_guidelines.3 }}
        
        ## Tone
        {{ prompts.professional_tone }}

Prompt Reusability: Store common instructions in the prompt library and reference them across multiple agents. Update once, apply everywhere.

Variables in Prompt Library: You can use template variables inside prompt library prompts! For example, a stored prompt can contain {{ user_input }}, {{ history }}, or even other {{ prompts.* }} references. The system resolves them recursively (up to 10 iterations).Example Prompt Library Entry:

Name: "contextual_greeting"
Content: |
  You are a helpful assistant.
  
  The user just said: "{{ user_input }}"
  
  Recent conversation:
  {{ history[3] }}
  
  Respond appropriately based on context.

Usage:

prompt_config:
  system_prompt: "{{ prompts.contextual_greeting }}"

This enables powerful prompt composition and reusability!

2. User Input Variable

Access the current user’s message content.

Variable	Description	Multimodal Handling
`{{ user_input }}`	Latest user message	Extracts only text from images/files

Example:

prompt_config:
  system_prompt: |
    The user asked: "{{ user_input }}"
    
    Analyze this question and provide:
    1. Intent classification
    2. Key entities mentioned
    3. Suggested response approach

3. Conversation History Variables

Access formatted conversation history (user-visible messages only, excludes internal tool calls).

Variable	Description	Format
`{{ history }}`	Full user-visible history	`user: message\nassistant: response\n...`
`{{ history[N] }}`	Last N messages	Same format, limited to N messages

Important: Structured output from agents is NOT included in history variables. Use {{ agent_name.output.field }} template variables to access structured data.

Example:

prompt_config:
  system_prompt: |
    ## Recent Conversation
    {{ history[5] }}
    
    ## Task
    Continue the conversation naturally, maintaining context and tone.
  include_history: false  # Using template variable instead

Output Format:

user: What's the weather today?
assistant: It's sunny with a high of 75°F.
user: Should I bring an umbrella?
assistant: No need for an umbrella today!

Structured Output Exclusion: The history variables only include user-visible text messages. Structured output data from agents with structured_output enabled is excluded from these history arrays and must be accessed via specific template variables.

History vs include_history: You can use {{ history }} template variable for formatted history in your system prompt, or use include_history: true to add messages to the message list. They serve different purposes.

4. Full Execution History Variables

Access complete execution trace including internal messages, tool calls, and tool results.

Variable	Description	Includes
`{{ full_history }}`	Complete execution trace	User + Internal + Tool calls + Results
`{{ full_history[N] }}`	Last N messages (all types)	Same, limited to N messages

Example:

agents:
  - name: execution_analyzer
    prompt_config:
      system_prompt: |
        ## Complete Execution Trace
        {{ full_history[20] }}
        
        ## Analysis Task
        Analyze the tool usage patterns and identify:
        1. Which tools were called
        2. Success/failure rates
        3. Optimization opportunities
      include_history: false
      include_user_input: false

Output Format:

user: Search for Python tutorials
assistant: I'll search for that information.
tool: search_web(query="Python tutorials")
tool_result: Found 10 results: [...]
assistant: Here are the top Python tutorials I found...

Full History vs History: {{ full_history }} includes internal messages and tool execution details. Use it for debugging, analysis, or when agents need to understand the complete execution flow.

5. Structured Output Variables

Access structured data from previous agents in multi-agent workflows.

Pattern	Description	Example
`{{ agent_name.output.field }}`	Access specific field	`{{ analyzer.output.key_topics }}`
`{{ agent_name.output }}`	Full structured output (JSON)	`{{ analyzer.output }}`
`{{ agent_name.output.field.subfield }}`	Nested field access	`{{ analyzer.output.customer.name }}`

Structured outputs are stored internally under the key "agent_name.output". There is no output_name field — the key is always agent_name.output.

Multi-Agent Example:

agents:
  # Agent 1: Analyze input and produce structured output
  - name: input_analyzer
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        Analyze the user input and extract:
        - Key topics discussed
        - Overall sentiment
        - Complexity level
        - Named entities
    structured_output:
      enabled: true
      schema:
        key_topics:
          type: "list[str]"
          description: "Key topics discussed"
        sentiment:
          type: "str"
          description: "Overall sentiment (positive, negative, neutral)"
        complexity:
          type: "str"
          description: "Complexity level (simple, moderate, complex)"
        entities:
          type: "list[str]"
          description: "Named entities mentioned"
  
  # Agent 2: Use analyzer's structured output
  - name: response_generator
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        ## Input Analysis
        **Topics**: {{ input_analyzer.output.key_topics }}
        **Sentiment**: {{ input_analyzer.output.sentiment }}
        **Complexity**: {{ input_analyzer.output.complexity }}
        **Entities**: {{ input_analyzer.output.entities }}
        
        ## Task
        Generate a response that:
        1. Addresses all key topics
        2. Matches the detected sentiment
        3. Adjusts complexity to user's level
        4. References mentioned entities appropriately

edges:
  - from: START
    to: input_analyzer
  - from: input_analyzer
    to: response_generator

Agent Coordination: Structured outputs enable sophisticated multi-agent workflows where downstream agents can access precise, typed data from upstream agents.

Complex types: When a substituted value is a list or dict, it is automatically serialized to JSON in the prompt.

6. Agent Output Variables

Access the last message from a specific agent (non-structured output).

Pattern	Description
`{{ agent_name.output }}`	Last message from specified agent

Example:

agents:
  - name: researcher
    agent_type: llm_agent
    prompt_config:
      system_prompt: Research the topic and provide findings
  
  - name: writer
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        ## Research Findings
        {{ researcher.output }}
        
        ## Task
        Write a comprehensive article based on these findings.
        Cite sources and maintain accuracy.

edges:
  - from: START
    to: researcher
  - from: researcher
    to: writer

7. Custom Variables

Access variables defined in the system’s variables section. These are populated from user inputs, agent variable_assignments, or defaults.

Pattern	Description
`{{ variables.name }}`	Value of a custom variable

Example:

variables:
  customer_name:
    type: "str"
    description: "Customer name"
  priority:
    type: "str"
    default: "medium"

agents:
  - name: support_agent
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        Customer: {{ variables.customer_name }}
        Priority: {{ variables.priority }}
        
        Help the customer with their request.

Variables are the bridge between structured output and prompt substitution. Use variable_assignments on agents to populate variables from structured output, then reference them with {{ variables.name }} in downstream agents. See Variables System for details.

Recursive Variable Substitution

Variables are substituted recursively up to 10 iterations, allowing nested variable references. Example:

# Prompt library contains:
# - "base_role": "You are {{ prompts.role_type }}"
# - "role_type": "a helpful assistant"

prompt_config:
  system_prompt: "{{ prompts.base_role }}"

# Iteration 1: "You are {{ prompts.role_type }}"
# Iteration 2: "You are a helpful assistant"
# Converged ✓

Nested Variables: You can reference prompts that contain other variables. The system will resolve them recursively until no more variables remain.

Variable Substitution Timing

Variables are substituted before building provider messages:

Template Resolution: {{ variables }} → actual values
Message Building: System prompt + examples + history + user input
LLM Call: Final messages sent to provider

This ensures that structured outputs from dependencies are available when constructing prompts.

Complete Variable Example

agents:
  - name: data_analyzer
    agent_type: llm_agent
    structured_output:
      enabled: true
      schema:
        trends:
          type: "list[str]"
          description: "Identified trends"
        anomalies:
          type: "list[str]"
          description: "Detected anomalies"
        recommendations:
          type: "list[str]"
          description: "Recommended actions"
    prompt_config:
      system_prompt: |
        {{ prompts.data_analysis_instructions }}
        
        Analyze this data and extract insights.
  
  - name: report_generator
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        ## Base Instructions
        {{ prompts.report_template }}
        
        ## Data Analysis Results
        **Trends Identified**: {{ data_analyzer.output.trends }}
        **Anomalies Detected**: {{ data_analyzer.output.anomalies }}
        **Recommendations**: {{ data_analyzer.output.recommendations }}
        
        ## Recent Context
        {{ history[3] }}
        
        ## Current Request
        {{ user_input }}
        
        ## Task
        Generate a professional report incorporating:
        1. All identified trends and anomalies
        2. Clear recommendations
        3. Context from recent conversation
        4. Response to current user request

System Prompt

The system prompt defines your agent’s behavior, role, and capabilities.

Basic Example

agents:
  - name: customer_support
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        You are a helpful customer support agent.
        Your goal is to resolve customer issues efficiently and professionally.
        Always be polite and empathetic.

Advanced System Prompt

agents:
  - name: data_analyst
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        # Role
        You are an expert data analyst specializing in financial data.
        
        # Capabilities
        - Analyze trends and patterns
        - Generate statistical insights
        - Create data visualizations
        - Provide actionable recommendations
        
        # Guidelines
        1. Always cite data sources
        2. Use statistical terminology correctly
        3. Provide confidence levels for predictions
        4. Format numbers with appropriate precision
        
        # Output Format
        Structure your analysis with:
        - Executive Summary
        - Key Findings
        - Detailed Analysis
        - Recommendations

Use Markdown formatting in system prompts for better structure. LLMs understand headings, lists, and emphasis.

Few-Shot Examples

Few-shot examples teach your agent desired behavior through concrete examples.

Basic Few-Shot Configuration

agents:
  - name: sentiment_analyzer
    agent_type: llm_agent
    prompt_config:
      system_prompt: Analyze sentiment of customer feedback
      few_shot_examples:
        - input: "The product is amazing! Best purchase ever."
          output: "Sentiment: Positive (0.95)\nReason: Enthusiastic language with strong positive words"
        
        - input: "It's okay, nothing special."
          output: "Sentiment: Neutral (0.50)\nReason: Lukewarm response without strong emotion"
        
        - input: "Terrible quality, waste of money."
          output: "Sentiment: Negative (0.10)\nReason: Strong negative words indicating dissatisfaction"

Complex Few-Shot Examples

agents:
  - name: code_reviewer
    agent_type: llm_agent
    prompt_config:
      system_prompt: Review code for quality and best practices
      few_shot_examples:
        - input: |
            def calculate_total(items):
                total = 0
                for item in items:
                    total += item['price']
                return total
          output: |
            **Issues Found:**
            1. No input validation (items could be None)
            2. Missing type hints
            3. No error handling for missing 'price' key
            
            **Improved Version:**
            ```python
            def calculate_total(items: list[dict]) -> float:
                if not items:
                    return 0.0
                return sum(item.get('price', 0.0) for item in items)

input: | def process_data(data): return [x * 2 for x in data if x > 0] output: | Code Quality: Good Strengths:
- Concise list comprehension
- Clear filtering logic
Suggestions:
- Add type hints: def process_data(data: list[int]) -> list[int]:
- Add docstring explaining the transformation

### Few-Shot Best Practices

<AccordionGroup>
  <Accordion title="Example Selection">
    - **Diversity**: Cover different scenarios and edge cases
    - **Relevance**: Match your actual use cases
    - **Quality**: Show ideal outputs, not just correct ones
    - **Quantity**: 2-5 examples usually sufficient (more isn't always better)
  </Accordion>
  
  <Accordion title="Input/Output Format">
    - **Consistency**: Use same format across all examples
    - **Clarity**: Make inputs and outputs clearly distinguishable
    - **Completeness**: Show full expected output format
    - **Realism**: Use realistic data, not toy examples
  </Accordion>
  
  <Accordion title="Common Patterns">
    - **Classification**: Show examples for each class
    - **Extraction**: Demonstrate different entity types
    - **Transformation**: Show input-output mappings
    - **Reasoning**: Include step-by-step thought process
  </Accordion>
</AccordionGroup>

## History Management

Control how much conversation history is included in prompts.

### Include All History (Default)

```yaml
prompt_config:
  system_prompt: You are a helpful assistant
  include_history: true  # Include all previous messages

Use Case: Long conversations where full context is needed Token Impact: High - all messages included

Exclude All History

prompt_config:
  system_prompt: You are a stateless classifier
  include_history: false  # No history, only current input

Use Case: Stateless operations, classification, single-turn interactions Token Impact: Low - only current message

Sliding Window (Last N Messages)

prompt_config:
  system_prompt: You are a conversational assistant
  include_history: 5  # Only last 5 messages

Use Case: Balance between context and token efficiency Token Impact: Medium - controlled history size

Token Management: Large histories can exceed model context windows. Use sliding windows for long conversations.

History Management Examples

# Include all conversation history
agents:
  - name: therapist_bot
    agent_type: llm_agent
    prompt_config:
      system_prompt: You are a supportive therapist
      include_history: true  # Need full session context

# Include only recent messages
agents:
  - name: quick_responder
    agent_type: llm_agent
    prompt_config:
      system_prompt: Provide quick answers
      include_history: 3  # Last 3 messages only

# Stateless operation
agents:
  - name: classifier
    agent_type: llm_agent
    prompt_config:
      system_prompt: Classify text into categories
      include_history: false  # Each input independent

User Input Control

Control whether the current user message is included in the prompt.

Include User Input (Default)

prompt_config:
  system_prompt: You are a helpful assistant
  include_user_input: true  # Include current user message

Standard Behavior: Current user question/message is included

Exclude User Input

prompt_config:
  system_prompt: Generate a summary of the conversation
  include_user_input: false  # Exclude current user message
  include_history: true       # But include all history

Use Case:

Conversation summarization
Automatic analysis without user prompt
Background processing tasks

When include_user_input: false, the agent processes only the conversation history without the latest user message. This is useful for automated tasks triggered by system events.

Internal Message Control

Control whether outputs from internal agents (those with streaming_config.show_output_to_user: false) are included in the conversation history sent to the LLM.

Include Internal Messages (Default)

prompt_config:
  system_prompt: You are a coordinator agent
  include_internal_messages: true  # See all agent outputs

Behavior: Both user-facing messages and internal agent outputs appear in conversation history. Use Case: Agents that need full awareness of the multi-agent workflow state.

Exclude Internal Messages

prompt_config:
  system_prompt: You are a customer-facing assistant
  include_internal_messages: false  # Only see user-visible messages

Behavior: Only messages from agents with show_output_to_user: true and user messages appear in history. Internal agent outputs are filtered out. Use Case: Customer-facing agents that should only see the user conversation, not background processing.

Internal messages are outputs from agents with streaming_config.show_output_to_user: false. These agents run in the background without emitting text to the end user.

Media Handling

Control how images, PDFs, and other media are handled in conversation history.

Strip Media from History

prompt_config:
  system_prompt: You are a document analyzer
  include_history: true
  include_media_in_history: false  # Strip images/files from history

Behavior:

Historical messages: Text only, media stripped
Current user input: Media always included

Use Case:

Reduce token costs (images are expensive)
Focus on text-based context
Process only the latest image

Include Media in History

prompt_config:
  system_prompt: You are a visual conversation assistant
  include_history: 5
  include_media_in_history: true  # Keep images in history

Behavior: All media content preserved in history Use Case:

Visual conversation continuity
Comparing multiple images
Document series analysis

Cost Impact: Images consume significant tokens. A single image can use 1,000-2,000 tokens depending on size and model.

Advanced Patterns

Critical: Tool Execution Results (ReAct Agents)

Important for ReAct Agents: Messages with a run_id in their metadata are ALWAYS included in the prompt, regardless of include_history or include_user_input settings. This ensures tool execution results are visible to the agent in reasoning loops.

When a ReAct agent executes tools, the results are tagged with the current run_id. These messages bypass all filtering to ensure the agent can see:

Tool call requests
Tool execution results
Error messages from failed tools

Example Flow:

agents:
  - name: research_agent
    agent_type: react_agent
    prompt_config:
      system_prompt: Research topics using available tools
      include_history: 3  # Only last 3 messages
      # But tool results and agent reasoning are ALWAYS included regardless
    tools:
      - search_web
      - read_url

# Execution:
# 1. User: "Research AI trends"
# 2. Agent thinks: "I'll search for AI trends"
# 3. Tool call: search_web(query="AI trends")
# 4. Tool result: [10 search results] ← ALWAYS visible
# 5. Agent sees tool result and continues reasoning

Why This Matters:

Without tool results, ReAct agents can’t complete their reasoning loop
Tool results must be visible even if history is limited
This is automatic - no configuration needed

Context-Aware Routing

agents:
  - name: intent_classifier
    agent_type: llm_agent
    prompt_config:
      system_prompt: Classify user intent
      include_history: false  # Stateless classification
      few_shot_examples:
        - input: "I want to cancel my order"
          output: "intent: cancel_order"
        - input: "Where is my package?"
          output: "intent: track_order"
  
  - name: conversation_handler
    agent_type: llm_agent
    prompt_config:
      system_prompt: Handle customer conversations
      include_history: 10  # Need conversation context
      include_media_in_history: false  # Text only in history

Multi-Stage Processing

agents:
  - name: data_extractor
    agent_type: llm_agent
    prompt_config:
      system_prompt: Extract structured data from text
      include_history: false  # Each document independent
      few_shot_examples:
        - input: "John Doe, john@example.com, 555-1234"
          output: |
            {
              "name": "John Doe",
              "email": "john@example.com",
              "phone": "555-1234"
            }
  
  - name: data_validator
    agent_type: llm_agent
    prompt_config:
      system_prompt: Validate extracted data
      include_history: true  # Need extraction context
      include_user_input: false  # Auto-validation

Summarization Pipeline

agents:
  - name: conversation_summarizer
    agent_type: llm_agent
    prompt_config:
      system_prompt: |
        Summarize the conversation into key points.
        Focus on decisions made and action items.
      include_history: true  # Need full conversation
      include_user_input: false  # Triggered automatically
      few_shot_examples:
        - input: |
            User: I need to update my billing info
            Agent: Sure, I can help with that
            User: My new card ends in 1234
            Agent: Updated successfully
          output: |
            **Summary:**
            - Customer requested billing update
            - New card ending in 1234 added
            - Update completed successfully

Validation & Best Practices

Automatic Validation

Artaios automatically validates your prompt configuration:

Empty Configuration Warning

Warning: All components disabled (no system prompt, no examples, no history, no user input)Fix: Enable at least one component

History Without User Input

Warning: History enabled but user input disabledBehavior: Only conversation history sent to LLM, not current questionUse Case: Intentional for summarization/analysis

User Input Without History

Info: User input enabled but history disabledBehavior: Only current question sent (stateless)Use Case: Classification, single-turn tasks

Few-Shot Format Validation

Error: Missing ‘input’ or ‘output’ in examplesFix: Ensure each example has both fields

Best Practices

System Prompt Design

Be specific about role and capabilities
Include output format requirements
Add constraints and guidelines
Use structured formatting (Markdown)

Few-Shot Examples

Use 2-5 high-quality examples
Cover diverse scenarios
Show ideal output format
Keep examples concise

History Management

Use sliding windows for long conversations
Disable for stateless operations
Monitor token usage
Consider media costs

Token Optimization

Strip unnecessary media
Limit history length
Use concise system prompts
Optimize few-shot examples

Complete Example

name: customer_support_system
description: Multi-agent customer support with optimized prompts
architecture: workflow

agents:
  - name: intent_router
    agent_type: llm_agent
    llm_config:
      model: mistral-small-latest
      temperature: 0.2
    prompt_config:
      system_prompt: |
        Classify customer intent into one of these categories:
        - billing: Payment, invoices, refunds
        - technical: Product issues, bugs, errors
        - general: Questions, information requests
      include_history: false  # Stateless classification
      few_shot_examples:
        - input: "I was charged twice for my subscription"
          output: "billing"
        - input: "The app keeps crashing on startup"
          output: "technical"
        - input: "What are your business hours?"
          output: "general"
  
  - name: billing_specialist
    agent_type: llm_agent
    llm_config:
      model: gpt-4o
      temperature: 0.5
    prompt_config:
      system_prompt: |
        You are a billing specialist. Handle payment issues professionally.
        
        **Capabilities:**
        - Check payment history
        - Process refunds
        - Update billing information
        
        **Guidelines:**
        - Always verify customer identity
        - Explain charges clearly
        - Offer solutions proactively
      include_history: 10  # Recent conversation context
      include_media_in_history: false  # Text only
      few_shot_examples:
        - input: "Why was I charged $50?"
          output: |
            I can help you understand this charge. Let me check your account.
            
            The $50 charge is for your monthly premium subscription that renewed on [date].
            This is the standard rate for the premium plan.
            
            Would you like me to review your subscription details?
  
  - name: technical_specialist
    agent_type: llm_agent
    llm_config:
      model: gpt-4o
      temperature: 0.3
    prompt_config:
      system_prompt: |
        You are a technical support specialist. Solve product issues efficiently.
        
        **Troubleshooting Process:**
        1. Understand the issue
        2. Ask clarifying questions
        3. Provide step-by-step solutions
        4. Verify resolution
        
        **Tone:** Patient, clear, technical but accessible
      include_history: 15  # Need full technical context
      include_media_in_history: true  # Screenshots important
      few_shot_examples:
        - input: "The app won't load"
          output: |
            I'll help you resolve this. Let's troubleshoot:
            
            1. First, try force-closing the app and reopening it
            2. If that doesn't work, check your internet connection
            3. Ensure you have the latest app version
            
            Can you try step 1 and let me know if it works?

edges:
  - from: START
    to: intent_router
  - from: intent_router
    condition: "Route to {intent_router.output}"
    condition_type: literal
    possible_outputs: [billing_specialist, technical_specialist]

Troubleshooting

Empty Prompt Warning

Issue: “PromptConfig has no content”Cause: All components disabled or emptySolution: Enable at least one component (system_prompt, examples, history, or user_input)

Few-Shot Validation Error

Issue: “Example missing ‘input’ or ‘output’ field”Cause: Incorrect example formatSolution: Ensure each example has both input and output keys

few_shot_examples:
  - input: "question"
    output: "answer"

Token Limit Exceeded

Issue: “Context too long” or token limit errorsCause: Too much history or large media filesSolution:

Reduce include_history to smaller number
Set include_media_in_history: false
Shorten system prompt
Use fewer few-shot examples

Unexpected Behavior

Issue: Agent not following instructionsCause: Conflicting configuration or unclear promptsSolution:

Make system prompt more specific
Add relevant few-shot examples
Check if history is interfering
Test with include_history: false first

Performance Tips

Start Simple

Begin with basic system prompt and no examples. Add complexity only when needed.

Measure Token Usage

Monitor token consumption and optimize based on actual usage patterns.

Test Incrementally

Add few-shot examples one at a time and measure impact on quality.

Optimize History

Find the minimum history length that maintains quality.

Profile Costs

Track costs per agent and optimize expensive ones first.

Quick Reference

Template Variables Cheat Sheet

Variable	Description	Example
`{{ variables.name }}`	Custom variable value	`{{ variables.customer_name }}`
`{{ prompts.name }}`	Latest prompt from library	`{{ prompts.system_instructions }}`
`{{ prompts.name.version }}`	Specific prompt version	`{{ prompts.guidelines.2 }}`
`{{ user_input }}`	Current user message (text only)	`{{ user_input }}`
`{{ history }}`	Full user-visible conversation history	`{{ history }}`
`{{ history[N] }}`	Last N user-visible messages	`{{ history[5] }}`
`{{ full_history }}`	Complete execution trace (internal + tool calls)	`{{ full_history }}`
`{{ full_history[N] }}`	Last N messages (all types)	`{{ full_history[10] }}`
`{{ agent_name.output.field }}`	Structured output field	`{{ analyzer.output.topics }}`
`{{ agent_name.output }}`	Last agent message (non-structured)	`{{ researcher.output }}`

PromptConfig Settings

Setting	Type	Default	Description
`system_prompt`	string	`""`	Core behavioral instructions (supports template variables)
`include_user_input`	bool	`true`	Include current user message
`include_history`	bool\|int	`true`	History control (true/false/N)
`include_media_in_history`	bool	`false`	Keep images/files in history
`include_internal_messages`	bool	`true`	Include internal agent outputs (`show_to_user=false`) in history
`few_shot_examples`	list	`[]`	Teaching examples (each with `input` and `output` keys)

Message Ordering

Final prompt structure sent to LLM:

System Message - Behavioral instructions (highest attention)
Few-Shot Examples - Teaching patterns (static)
Separator - Optional section marker
Conversation History - Previous messages (filtered)
Run-ID Messages - Tool results (ALWAYS included)
Current User Input - Latest message (highest attention)

Common Patterns

Stateless Agent
Conversational Agent
Multi-Agent Workflow
Summarization

prompt_config:
  system_prompt: Classify user intent
  include_history: false
  include_user_input: true
  few_shot_examples:
    - input: "Cancel my order"
      output: "intent: cancel"

prompt_config:
  system_prompt: You are a helpful assistant
  include_history: 10  # Last 10 messages
  include_user_input: true
  include_media_in_history: false

# Agent 1: Analyzer
prompt_config:
  system_prompt: Analyze the input
structured_output:
  enabled: true
  schema:
    summary:
      type: "str"
      description: "Analysis summary"

# Agent 2: Responder
prompt_config:
  system_prompt: |
    Analysis: {{ analyzer.output.summary }}
    Respond based on this analysis.

prompt_config:
  system_prompt: |
    {{ history }}
    
    Summarize the above conversation.
  include_history: false  # Using template variable
  include_user_input: false  # Auto-triggered

Variable Substitution Flow

1. Template with {{ variables }}
   ↓
2. Recursive substitution (up to 10 iterations)
   ↓
3. Resolved system prompt
   ↓
4. Build messages (system + examples + history + user input)
   ↓
5. Send to LLM provider

Troubleshooting Quick Fixes

Issue	Quick Fix
Empty prompt warning	Enable at least one: `system_prompt`, `few_shot_examples`, `include_history`, or `include_user_input`
Token limit exceeded	Reduce `include_history` to smaller number or set `include_media_in_history: false`
Variable not substituting	Check spelling, ensure prompt exists in library, verify recursive limit not hit
Duplicate user messages	Fixed automatically - deduplication is built-in
Tool results missing (ReAct)	Automatic - run_id messages always included
Agent ignoring instructions	Add few-shot examples or make system prompt more specific

Next Steps

Model Selection

Choose the right models for your use case

Structured Output

Generate structured data with schemas

Agent Capabilities

Explore tools, streaming, and other capabilities

Agent Types

Explore different agent architectures

​Overview

​Core Concepts

​Message Ordering

​PromptConfig Schema

​Template Variables

​Variable Categories

Custom Variables

Prompt Library

User Input

Conversation History

Full Execution History

Structured Outputs

Agent Outputs

​1. Prompt Library Variables

​2. User Input Variable

​3. Conversation History Variables

​4. Full Execution History Variables

​5. Structured Output Variables

​6. Agent Output Variables

​7. Custom Variables

​Recursive Variable Substitution

​Variable Substitution Timing

​Complete Variable Example

​System Prompt

​Basic Example

​Advanced System Prompt

​Few-Shot Examples

​Basic Few-Shot Configuration

​Complex Few-Shot Examples

​Exclude All History

​Sliding Window (Last N Messages)

​History Management Examples

​User Input Control

​Include User Input (Default)

​Exclude User Input

​Internal Message Control

​Include Internal Messages (Default)

​Exclude Internal Messages

​Media Handling

​Strip Media from History

​Include Media in History

​Advanced Patterns

​Critical: Tool Execution Results (ReAct Agents)

​Context-Aware Routing

​Multi-Stage Processing

​Summarization Pipeline

​Validation & Best Practices

​Automatic Validation

​Best Practices

System Prompt Design

Few-Shot Examples

History Management

Token Optimization

​Complete Example

​Troubleshooting

​Performance Tips

​Quick Reference

​Template Variables Cheat Sheet

​PromptConfig Settings

​Message Ordering

​Common Patterns

​Variable Substitution Flow

​Troubleshooting Quick Fixes

​Next Steps

Model Selection

Structured Output

Agent Capabilities

Agent Types

Overview

Core Concepts

Message Ordering

PromptConfig Schema

Template Variables

Variable Categories

1. Prompt Library Variables

2. User Input Variable

3. Conversation History Variables

4. Full Execution History Variables

5. Structured Output Variables

6. Agent Output Variables

7. Custom Variables

Recursive Variable Substitution

Variable Substitution Timing

Complete Variable Example

System Prompt

Basic Example

Advanced System Prompt

Few-Shot Examples

Basic Few-Shot Configuration

Complex Few-Shot Examples

Exclude All History

Sliding Window (Last N Messages)

History Management Examples

User Input Control

Include User Input (Default)

Exclude User Input

Internal Message Control

Include Internal Messages (Default)

Exclude Internal Messages

Media Handling

Strip Media from History

Include Media in History

Advanced Patterns

Critical: Tool Execution Results (ReAct Agents)

Context-Aware Routing

Multi-Stage Processing

Summarization Pipeline

Validation & Best Practices

Automatic Validation

Best Practices

Complete Example

Troubleshooting

Performance Tips

Quick Reference

Template Variables Cheat Sheet

PromptConfig Settings

Message Ordering

Common Patterns

Variable Substitution Flow

Troubleshooting Quick Fixes

Next Steps