Skip to content
AgentForceZone

.systemPrompt()

.systemPrompt()

Section titled “.systemPrompt()”

AgentForceAgent Optional Chainable

Set system instructions that define the agent’s behavior of the model. System prompts establish the foundation how the agent will respond to user inputs.

Signature

Section titled “Signature”
systemPrompt(prompt: string): AgentForceAgent

Parameters

Section titled “Parameters”
Parameter
Type
Default
Description
prompt
string
undefined
The system prompt text or file path (.md, .txt, .hbs files supported)

Returns

Section titled “Returns”

Returns the AgentForceAgent instance for method chaining.

Examples:

Section titled “Examples:”

Basic Usage

Section titled “Basic Usage”
import { AgentForceAgent } from '@agentforce/adk';


const agent = new AgentForceAgent({
  name: "AnalystAgent"
})
  .systemPrompt("You are a data analyst specializing in sales metrics")
  .useLLM("ollama", "gemma3:4b")
  .prompt("Analyze quarterly sales data");


const response = await agent.output("json");

Role-Based System Prompts

Section titled “Role-Based System Prompts”

Define specific roles and behaviors for different use cases:

const techAgent = new AgentForceAgent({ name: "TechExpert" })
  .systemPrompt(`You are a senior software engineer with expertise in:
- TypeScript and JavaScript
- Node.js and modern web frameworks
- Database design and optimization
- Code review and best practices


Always provide practical, actionable advice with code examples.`)
  .useLLM("google", "gemini-1.5-flash");

File-Based System Prompts

Section titled “File-Based System Prompts”
prompts/customer-service.md
const agent = new AgentForceAgent({ name: "SupportAgent" })
  .systemPrompt("./prompts/customer-service.md")
  .prompt("Help customer with billing issue");

customer-service.md:

# Customer Service Agent


You are a professional customer service representative with these qualities:


## Tone and Communication
- Always polite, empathetic, and helpful
- Use clear, jargon-free language
- Acknowledge customer concerns immediately


## Problem Resolution Process
1. Listen and understand the issue completely
2. Acknowledge the customer's frustration
3. Provide clear, step-by-step solutions
4. Follow up to ensure satisfaction


## Escalation Guidelines
- Escalate billing issues over $500
- Escalate technical problems requiring developer intervention
- Always offer alternatives when initial solution isn't possible

Dynamic System Prompts with Context

Section titled “Dynamic System Prompts with Context”
const contextualAgent = new AgentForceAgent({ name: "ContextualAgent" })
  .systemPrompt(`You are assisting a ${process.env.USER_ROLE || 'user'} with ${process.env.PROJECT_TYPE || 'general'} tasks.


Current environment: ${process.env.NODE_ENV || 'development'}
Timestamp: ${new Date().toISOString()}


Adapt your responses to the user's role and project context.`)
  .useLLM("google", "gemini-1.5-pro");

File Path Resolution

Section titled “File Path Resolution”

The method automatically detects and loads files with these extensions:

Extension
Format
UseCase
.md
Markdown
Rich formatted prompts with headers, lists, and structure
.txt
Plain Text
Simple text prompts without formatting
.hbs
Handlebars
Dynamic templates with variables and conditionals

File Resolution Process

Section titled “File Resolution Process”
  1. Path Detection: Checks if the prompt string ends with .md, .txt, or .hbs
  2. File Resolution: Resolves path relative to current working directory
  3. File Reading: Reads file content as UTF-8 text
  4. Fallback: If file doesn’t exist, treats input as literal prompt text with warning

Method Chaining

Section titled “Method Chaining”

The systemPrompt() method supports fluent chaining with other AgentForceAgent methods:

const agent = new AgentForceAgent({ name: "ChainedAgent" })
  .systemPrompt("You are a helpful coding assistant")
  .useLLM("ollama", "gemma3:4b")
  .prompt("Explain async/await in JavaScript")
  .debug();


const response = await agent.output("text");

Use Cases

Section titled “Use Cases”

Code Review Assistant

System Prompt: Define review criteria, coding standards, security checks

Best for: Pull request reviews, code quality assessment, best practices

Customer Support

System Prompt: Set tone, escalation rules, company policies

Best for: Automated support, FAQ responses, issue triage

Content Creator

System Prompt: Define writing style, target audience, content guidelines

Best for: Blog posts, documentation, marketing copy

Data Analyst

System Prompt: Set analytical approach, output format, visualization preferences

Best for: Report generation, data insights, trend analysis

Best Practices

Section titled “Best Practices”

✅ Effective System Prompts

Section titled “✅ Effective System Prompts”
// Clear role definition
.systemPrompt(`You are a TypeScript expert who:
- Writes type-safe, maintainable code
- Follows modern ES6+ conventions
- Provides clear explanations with examples
- Suggests performance optimizations when relevant`)


// Specific behavior guidelines
.systemPrompt(`Guidelines:
1. Always validate inputs
2. Use descriptive variable names
3. Include error handling
4. Add inline comments for complex logic`)


// Context-aware instructions
.systemPrompt(`Project Context:
- React TypeScript application
- Using Tailwind CSS for styling
- Following clean architecture principles
- Target audience: intermediate developers`)

❌ Common Issues

Section titled “❌ Common Issues”
// Too vague
.systemPrompt("Be helpful")


// Too restrictive
.systemPrompt("Only answer with yes or no")


// Conflicting instructions
.systemPrompt("Be creative but stick strictly to facts")


// Missing context
.systemPrompt("Review this code") // What kind of review?

Error Handling

Section titled “Error Handling”
// If file doesn't exist or can't be read, treats as literal text
const agent = new AgentForceAgent({ name: "SafeAgent" })
  .systemPrompt("./nonexistent-file.md") // Shows warning, uses as literal text
  .prompt("Test prompt");


try {
  const response = await agent.output("text");
} catch (error) {
  console.error("Agent Error:", error.message);
}

Console Warnings:

  • Warning: File './prompts/missing.md' not found, treating as regular prompt text
  • Warning: Failed to read file './prompts/locked.md': Permission denied. Treating as regular prompt text.
Section titled “Related Methods”

See Also

Section titled “See Also”