Skip to main content
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:
  1. Initialization: The prompt is loaded into the agent’s context at session start
  2. Persistence: It remains active throughout the entire session
  3. Influence: Every agent response is shaped by the system prompt’s guidance
  4. Integration: The prompt works seamlessly with tools, rules, and other primitives
  5. 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:

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

Common Patterns

Template Pattern: Create reusable prompt templates for common agent roles in your organization. Store them as constants or configuration files.

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:
Learn more: Rules Primitive

With Custom Tools

Guide how agents use custom tools:
Learn more: Custom Tools Primitive

With Multi-Agent Systems

Define specialized agents for different roles:
Learn more: Multi-Agent Primitive

With Sessions

Different prompts for different session contexts:
Learn more: Sessions Primitive

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
Optimization: Keep prompts concise and focused. Move lengthy reference material to context documents or custom tools when possible.

Token Usage

System prompts consume tokens with every request in a session:

Caching and Reusability

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

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

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
Remember: Great system prompts are specific, structured, and tested. Start simple, iterate based on results, and refine as you understand your use case better.