> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artaios.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Configuration

> Master prompt engineering in AMAS with dynamic context control, few-shot learning, and history management

## Overview

AMAS'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

AMAS constructs prompts in an optimal order for LLM attention:

**1. System Prompt**

**Highest attention** - Behavioral instructions and role definition

**2. Few-Shot Examples**

**Teaching patterns** - Static examples showing desired behavior

**3. Conversation History**

**Dynamic context** - Previous messages (configurable)

**4. Current User Input**

**Highest attention** - The current task or question

> [!NOTE]
>
> This ordering leverages the **primacy and recency effects** in LLM attention, placing the most important information at the beginning and end.

## PromptConfig Schema

```yaml theme={null}
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

AMAS 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:**

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

> [!TIP]
>
> **Prompt Reusability**: Store common instructions in the prompt library and reference them across multiple agents. Update once, apply everywhere.

> [!NOTE]
>
> **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:**
>
> ```yaml theme={null}
> 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:**

```yaml theme={null}
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 |

> [!WARNING]
>
> **Important**: Structured output from agents is **NOT** included in history variables. Use `{{ agent_name.output.field }}` template variables to access structured data.

**Example:**

```yaml theme={null}
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!
```

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **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:**

```yaml theme={null}
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...
```

> [!WARNING]
>
> **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 }}` |

> [!NOTE]
>
> 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:**

```yaml theme={null}
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
```

> [!TIP]
>
> **Agent Coordination**: Structured outputs enable sophisticated multi-agent workflows where downstream agents can access precise, typed data from upstream agents.

> [!TIP]
>
> **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:**

```yaml theme={null}
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:**

```yaml theme={null}
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.
```

> [!NOTE]
>
> 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](https://docs.artaios.ai/amas/advanced/variables-system.md) for details.

### Recursive Variable Substitution

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

**Example:**

```yaml theme={null}
# 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 ✓
```

> [!NOTE]
>
> **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:

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

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

### Complete Variable Example

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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
```

> [!TIP]
>
> 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

```yaml theme={null}
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

````yaml theme={null}
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

```yaml theme={null}
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)

```yaml theme={null}
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

> [!WARNING]
>
> **Token Management**: Large histories can exceed model context windows. Use sliding windows for long conversations.

### History Management Examples

```yaml Full Context theme={null}
# 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
```

```yaml Recent Context theme={null}
# 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
```

```yaml No Context theme={null}
# 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)

```yaml theme={null}
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

```yaml theme={null}
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

> [!NOTE]
>
> 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)

```yaml theme={null}
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

```yaml theme={null}
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.

> [!NOTE]
>
> 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

```yaml theme={null}
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

```yaml theme={null}
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

> [!WARNING]
>
> **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)

> [!WARNING]
>
> **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:**

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

```yaml theme={null}
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

AMAS 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 disabled
>
> **Behavior**: Only conversation history sent to LLM, not current question
>
> **Use Case**: Intentional for summarization/analysis

> **User Input Without History**
>
> **Info**: User input enabled but history disabled
>
> **Behavior**: Only current question sent (stateless)
>
> **Use Case**: Classification, single-turn tasks

> **Few-Shot Format Validation**
>
> **Error**: Missing 'input' or 'output' in examples
>
> **Fix**: 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

```yaml theme={null}
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 empty
>
> **Solution**: 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 format
>
> **Solution**: Ensure each example has both `input` and `output` keys
>
> ```yaml theme={null}
> few_shot_examples:
>   - input: "question"
>     output: "answer"
> ```

> **Token Limit Exceeded**
>
> **Issue**: "Context too long" or token limit errors
>
> **Cause**: Too much history or large media files
>
> **Solution**:
>
> * 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 instructions
>
> **Cause**: Conflicting configuration or unclear prompts
>
> **Solution**:
>
> * Make system prompt more specific
> * Add relevant few-shot examples
> * Check if history is interfering
> * Test with `include_history: false` first

## Performance Tips

**1. Start Simple**

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

**2. Measure Token Usage**

Monitor token consumption and optimize based on actual usage patterns.

**3. Test Incrementally**

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

**4. Optimize History**

Find the minimum history length that maintains quality.

**5. 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:**

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

### Common Patterns

**Stateless Agent**

```yaml theme={null}
prompt_config:
  system_prompt: Classify user intent
  include_history: false
  include_user_input: true
  few_shot_examples:
    - input: "Cancel my order"
      output: "intent: cancel"
```

**Conversational Agent**

```yaml theme={null}
prompt_config:
  system_prompt: You are a helpful assistant
  include_history: 10  # Last 10 messages
  include_user_input: true
  include_media_in_history: false
```

**Multi-Agent Workflow**

```yaml theme={null}
# 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.
```

**Summarization**

```yaml theme={null}
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](https://docs.artaios.ai/amas/agent_config/types_config/model-selection.md)**
>
> Choose the right models for your use case

> **[Structured Output](https://docs.artaios.ai/amas/advanced/structured-output.md)**
>
> Generate structured data with schemas

> **[Agent Capabilities](https://docs.artaios.ai/amas/agent_config/agent-capabilities.md)**
>
> Explore tools, streaming, and other capabilities

> **[Agent Types](https://docs.artaios.ai/amas/agent_config/types_config/agent-types.md)**
>
> Explore different agent architectures


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.