System prompts are the foundation of agent customization, defining your agent’s expertise, personality, behavioral guidelines, and approach to tasks.
Overview
The Prompts primitive allows you to shape how your agent thinks, communicates, and approaches problems. Unlike user messages that describe specific tasks, system prompts establish the agent’s core identity, expertise domain, and operational framework. They act as the agent’s professional background and personality blueprint. System prompts are essential for:- Role Definition: Establish the agent as a domain expert (e.g., data analyst, DevOps engineer, customer support specialist)
- Behavioral Guidance: Define communication style, tone, and interaction patterns
- Expertise Scoping: Focus the agent’s knowledge and approach on specific domains
- Constraint Setting: Establish boundaries, preferences, and operational rules
- Context Injection: Provide company-specific knowledge, policies, or frameworks
Flexible Definition
Define agents as domain experts with specific expertise, communication styles, and behavioral patterns
Context-Aware
Inject company knowledge, policies, and domain-specific frameworks directly into agent behavior
Always Active
System prompts persist throughout the entire session, guiding every agent response
Composable
Combine with rules, tools, and other primitives for sophisticated agent behavior
How System Prompts Work
System prompts are processed before any user messages and establish the agent’s operational context. When you provide a system prompt:- Initialization: The prompt is loaded into the agent’s context at session start
- Persistence: It remains active throughout the entire session
- Influence: Every agent response is shaped by the system prompt’s guidance
- Integration: The prompt works seamlessly with tools, rules, and other primitives
- Override: New sessions can use different prompts for different use cases
Session Scope: System prompts are set per session. Different sessions can have different prompts, enabling multi-tenant applications with specialized agents.
Code Examples
Basic Role Definition
Prompt with Behavioral Guidelines
Prompt with Domain Context
Multi-Line Prompt with Structure
Use Cases and Patterns
1. Domain Expert Agents
Create specialized agents for specific domains:Data Science & Analytics
Data Science & Analytics
Legal & Compliance
Legal & Compliance
Financial Analysis
Financial Analysis
Software Architecture
Software Architecture
2. Customer-Facing Agents
Customize communication style for end users:3. Internal Tools & Automation
Agents for internal workflows and processes:4. Educational & Training Agents
Agents designed to teach and mentor:Best Practices
Crafting Effective Prompts
Be Specific About Role and Expertise
Be Specific About Role and Expertise
Include Behavioral Guidelines
Include Behavioral Guidelines
Provide Relevant Context
Provide Relevant Context
Set Clear Constraints and Boundaries
Set Clear Constraints and Boundaries
Structure Complex Prompts
Structure Complex Prompts
Common Patterns
Dos and Don’ts
Do
- Define clear role and expertise
- Provide relevant context
- Set behavioral guidelines
- Include constraints and boundaries
- Structure complex prompts with sections
- Test prompts with sample tasks
- Iterate based on agent performance
Don't
- Use vague or generic descriptions
- Overload with unnecessary details
- Contradict yourself in the prompt
- Assume implicit knowledge
- Ignore domain-specific requirements
- Forget to set ethical boundaries
- Write unstructured walls of text
Integration with Other Primitives
With Rules
Combine prompts with rules for fine-grained control:With Custom Tools
Guide how agents use custom tools:With Multi-Agent Systems
Define specialized agents for different roles:With Sessions
Different prompts for different session contexts:Performance Considerations
Prompt Length and Latency
- Short prompts (< 100 tokens): Negligible impact on response time
- Medium prompts (100-500 tokens): Minimal impact (~100ms)
- Long prompts (500+ tokens): Moderate impact (~200-500ms)
- Very long prompts (1000+ tokens): Consider if all details are necessary
Token Usage
System prompts consume tokens with every request in a session:Caching and Reusability
Reuse Prompts Across Sessions
Reuse Prompts Across Sessions
Dynamic Prompt Generation
Dynamic Prompt Generation
Advanced Techniques
Dynamic Prompt Injection
Inject user or session-specific context:Prompt Versioning
Track and manage prompt versions:Conditional Prompt Selection
Choose prompts based on request type:Troubleshooting
Agent Not Following Prompt Guidelines
Agent Not Following Prompt Guidelines
Problem: Agent responses don’t align with system prompt instructionsSolutions:
- Make guidelines more explicit and specific
- Use imperative language (“Always…”, “Never…”, “Must…”)
- Add examples of desired behavior in the prompt
- Check for conflicting instructions
- Combine with rules for stricter enforcement
Prompt Too Long or Complex
Prompt Too Long or Complex
Problem: System prompt is becoming unwieldySolutions:
- Extract reference material to custom tools or documents
- Focus on core role and critical guidelines
- Use concise, structured formatting
- Move detailed examples to separate documentation
Inconsistent Agent Behavior
Inconsistent Agent Behavior
Problem: Agent behaves differently across similar requestsSolutions:
- Make prompts more deterministic with clear procedures
- Add structured decision-making frameworks
- Include examples of edge cases
- Use rules for critical constraints
Prompt Context Lost in Long Sessions
Prompt Context Lost in Long Sessions
Problem: Agent seems to forget system prompt guidance in long conversationsSolutions:
- Reinforce critical points in user messages
- Create new sessions for distinct conversation phases
- Use rules to enforce critical constraints
- Periodically remind agent of role in conversation
Testing and Validation
Testing Prompt Effectiveness
Related Primitives
Rules
Add strict constraints and requirements to agent behavior
Custom Tools
Extend agent capabilities with domain-specific tools
Multi-Agent
Create specialized agents for different roles
Sessions
Maintain prompt context across conversations
Additional Resources
API Reference
Complete system prompt parameters
Rules Guide
Combine prompts with rules
Use Cases
Example agent implementations