Agent Instructions

Overview

Agent instructions (prompts) define how your agent behaves, what it knows, and how it responds to users. Oblien provides a powerful rich-text editor with live preview and AI-assisted editing.

The Instructions Editor

The instructions editor provides three modes:

Rich Text Mode

Edit instructions using a WYSIWYG markdown editor with formatting tools, headings, lists, code blocks, and more.

Diff Mode

When using the AI assistant to update instructions, diff mode highlights changes with accept/reject options.

Live Preview

See exactly how your instructions will appear to the agent in real-time.

Instruction Structure

A well-structured instruction set typically includes:

1. Identity & Role

Define who the agent is and its primary purpose:

# Identity
You are a senior technical support engineer at Acme Corp with 10 years of experience.
You specialize in troubleshooting cloud infrastructure and deployment issues.

2. Capabilities

List what the agent can and should do:

# Capabilities
- Diagnose deployment failures
- Analyze error logs
- Provide step-by-step solutions
- Escalate critical issues to on-call engineers
- Access documentation and knowledge base

3. Guidelines & Behavior

Set behavioral expectations:

# Guidelines
- Always greet users professionally
- Ask clarifying questions before diving into solutions
- Break down complex solutions into simple steps
- If uncertain, say so and escalate
- Follow company tone and voice guidelines

4. Constraints & Limitations

Define boundaries:

# Constraints
- Do not share internal system credentials
- Do not make changes without user confirmation
- Escalate billing or account issues to the billing team
- Stay within the scope of technical support

5. Response Format

Specify how to structure responses:

# Response Format
When providing solutions:
1. Acknowledge the issue
2. Ask any clarifying questions
3. Provide step-by-step instructions
4. Offer to verify the solution
5. Provide next steps or alternatives

Using the AI Assistant

The built-in AI assistant can help you create and refine instructions:

Assistant Mode

Click the Assistant toggle to enable the AI assistant that helps you:

Generate initial instruction sets
Refine existing instructions
Add specific capabilities or constraints
Improve clarity and structure

Testing Mode

Switch to Testing mode to:

Chat with your agent directly
Test instruction changes in real-time
Verify agent behavior
Iterate quickly

Example Interaction

You: "Add guidelines for handling angry customers"

AI Assistant: *Updates instructions in diff mode*

The assistant streams changes directly into your editor, showing:

What's being added (highlighted in green)
What's being removed (highlighted in red)
Options to accept or reject changes

Advanced Instruction Techniques

Context Variables

Reference dynamic information in your instructions:

# Agent Context
- Agent Name: {{agent.name}}
- User Name: {{user.name}}
- Current Date: {{date.now}}
- Session ID: {{session.id}}

Conditional Logic

# Behavior Rules
- If user role is "premium": Provide priority support
- If business hours: Response time target is 5 minutes
- If after hours: Set expectations for next business day

Knowledge References

# Knowledge Base
When answering questions:
1. First check the internal documentation at /docs
2. Reference specific articles when possible
3. If no documentation exists, use general knowledge
4. Always cite sources when applicable

Instruction Best Practices

Be Specific

❌ Bad: "Be helpful" ✅ Good: "When users report errors, ask for the error message, reproduction steps, and environment details"

Use Examples

Include example interactions:

# Example Interaction

User: "My deployment failed"
Agent: "I'll help you troubleshoot that. Could you share:
1. The error message you're seeing
2. Which environment (staging/production)
3. When the deployment was attempted"

Keep It Updated

Review instructions monthly
Update based on user feedback
Add handling for common edge cases
Remove outdated information

Test Thoroughly

Test with various user inputs
Verify tool execution behavior
Check edge cases and error scenarios
Get feedback from team members

// Get instruction history
const history = await request(`ai/agents/${agentId}/prompts/history`, {}, 'GET');

Common Patterns

Customer Support Agent

# Identity
Professional customer support specialist

# Tone
- Empathetic and patient
- Clear and concise
- Professional but friendly

# Process
1. Acknowledge the issue
2. Gather information
3. Provide solution or escalate
4. Confirm resolution

Technical Assistant

# Identity
Senior software engineer assistant

# Expertise
- Full-stack development
- Cloud infrastructure
- DevOps and CI/CD
- Database optimization

# Communication Style
- Technical but accessible
- Provide code examples
- Explain trade-offs
- Suggest best practices

Sales Agent

# Identity
Sales development representative

# Goals
- Qualify leads
- Schedule demos
- Answer product questions
- Overcome objections

# Guidelines
- Listen actively
- Ask discovery questions
- Focus on value, not features
- Know when to involve sales team

Troubleshooting

Agent Not Behaving as Expected

Review Instructions: Ensure they're clear and unambiguous
Check for Conflicts: Look for contradictory guidelines
Test in Isolation: Remove advanced features temporarily
Verify Context: Ensure the agent has necessary context

Instructions Too Long

Split into focused sections
Use bullet points instead of paragraphs
Remove redundant information
Link to external documentation

Inconsistent Responses

Add more specific guidelines
Include example interactions
Define edge case handling
Test with various inputs

Next Steps

Configure Tools - Enable agent actions
Set Up Context - Provide knowledge base
Full-Stack Example - Complete integration guide