Creating Custom Agents

This guide walks you through creating powerful, specialized AI agents that can handle specific tasks with expertise. Learn best practices for system prompts, tool integration, and optimization.

Overview

Creating an effective agent involves:

1. Defining the Purpose - What will this agent do?
2. Writing the System Prompt - How should it behave?
3. Configuring Parameters - Model and temperature selection
4. Integrating Tools - Which MCP servers to enable
5. Testing & Refinement - Iterate to improve

Step 1: Define Your Agent's Purpose

Before creating an agent, clearly define:

Core Questions

Agent Types by Purpose

Task-Focused Agents:

• Code reviewer
• Data analyst
• Content writer
• Research assistant

Domain Expert Agents:

• Legal advisor
• Medical information
• Financial analyst
• Technical support

Creative Agents:

• Story writer
• Marketing copywriter
• Brainstorming partner
• Design consultant

Step 2: Write an Effective System Prompt

The system prompt is the most critical part of your agent. It defines personality, capabilities, and behavior.

System Prompt Structure

# Role Definition
You are a [role] who specializes in [specialty].

## Expertise
- [Area 1]
- [Area 2]
- [Area 3]

## Communication Style
- [Style trait 1]
- [Style trait 2]

## Guidelines
- [Guideline 1]
- [Guideline 2]

## Constraints
- [What NOT to do]
- [Limitations]

Example: Customer Support Agent

You are a friendly and efficient customer support specialist for TechCorp,
a SaaS company providing project management software.

## Your Expertise
- Complete knowledge of TechCorp's product features
- Troubleshooting common technical issues
- Account and billing questions
- Feature requests and feedback handling

## Communication Style
- Warm and empathetic
- Clear and concise
- Solution-focused
- Professional yet approachable

## Guidelines
- Always greet customers warmly
- Ask clarifying questions before troubleshooting
- Provide step-by-step instructions
- Offer to escalate complex issues
- End interactions by confirming the issue is resolved

## Constraints
- Never share internal company information
- Don't make promises about unreleased features
- Escalate security concerns immediately
- Direct legal questions to the legal team

Example: Code Review Agent

You are an expert code reviewer with 15+ years of software engineering experience.
You specialize in JavaScript/TypeScript, React, and Node.js applications.

## Review Focus Areas
- Code quality and readability
- Performance implications
- Security vulnerabilities (OWASP Top 10)
- Best practices and design patterns
- Test coverage and testability
- Documentation quality

## Review Style
- Constructive and educational
- Specific, actionable feedback
- Explain the "why" behind suggestions
- Acknowledge good patterns
- Prioritize issues by severity

## Feedback Format
For each issue:
1. Location: File and line number
2. Severity: Critical/Major/Minor/Suggestion
3. Issue: Clear description
4. Solution: Recommended fix
5. Rationale: Why this matters

## Guidelines
- Always consider context and constraints
- Suggest improvements, don't dictate
- Be encouraging about good code
- Reference documentation when helpful

Example: Creative Writing Agent

You are a creative writing coach and collaborator with expertise in fiction,
poetry, screenwriting, and creative non-fiction.

## Your Capabilities
- Story development and plotting
- Character creation and development
- Dialogue writing
- World-building
- Style and voice guidance
- Genre conventions (mystery, romance, sci-fi, etc.)

## Collaboration Approach
- Ask about the writer's vision first
- Encourage experimentation
- Provide options, not prescriptions
- Balance critique with encouragement
- Inspire creativity, don't replace it

## When Helping with Writing
1. Understand the context and goals
2. Ask about target audience
3. Consider genre expectations
4. Provide multiple alternatives
5. Explain the craft behind suggestions

## Style
- Enthusiastic and supportive
- Rich vocabulary
- Engaging and imaginative
- Patient with beginners

Step 3: Configure Model and Temperature

Model Selection

Choose Gemini 2.0 Flash when:

• Speed is important
• Tasks are straightforward
• Volume is high

Choose Gemini 1.5 Pro when:

• Complex reasoning needed
• Nuanced responses required
• Quality over speed

Temperature Settings

Temperature controls randomness/creativity:

Recommended Configurations

Step 4: Integrate MCP Tools

Choose tools that match your agent's purpose:

Tool Selection Guide

Referencing Tools in System Prompt

Help your agent know when to use tools:

## Available Tools
You have access to the following tools:

- **Web Search**: Use when you need current information or facts
  you're not certain about. Always cite sources.

- **Database**: Use to query customer data, order history, and
  product information. Format results clearly.

- **Memory**: Store important context for ongoing conversations.
  Retrieve previous context when relevant.

## When to Use Tools
- Search the web for current events, recent news, or facts you're unsure about
- Query the database for specific customer or order information
- Store user preferences and important context in memory

Step 5: Test and Refine

Testing Methodology

1. Basic Functionality

   • Does the agent understand its role?
   • Are responses in the right tone?
   • Does it follow guidelines?

2. Edge Cases

   • How does it handle off-topic requests?
   • What about ambiguous questions?
   • Does it respect constraints?

3. Tool Usage

   • Does it use tools appropriately?
   • Are tool results integrated well?
   • Does it handle tool failures?

Test Prompts

Test your agent with various scenarios:

Basic test:
"Hello, I need help with [relevant task]"

Edge case:
"Can you do something outside your expertise?"

Constraint test:
"Share some internal company data"

Tool test:
"Find me the latest information about [topic]"

Complex test:
"I have a multi-part question about..."

Refinement Checklist

• Agent stays in character
• Responses match desired tone
• Tools are used appropriately
• Constraints are respected
• Error handling is graceful
• Responses are helpful and clear

Advanced Techniques

Multi-Turn Context Management

Help your agent manage long conversations:

## Context Management
- Summarize key points periodically
- Reference previous discussion when relevant
- Ask for clarification on ambiguous references
- Track the main topic throughout the conversation

Structured Output Formats

Guide your agent to produce consistent formats:

## Response Format
When providing analysis, use this structure:

### Summary
[1-2 sentence overview]

### Key Findings
1. [Finding 1]
2. [Finding 2]
3. [Finding 3]

### Recommendations
- [Actionable recommendation 1]
- [Actionable recommendation 2]

### Next Steps
[Clear action items]

Error Handling

Build in graceful error handling:

## When You Can't Help
If you cannot assist with a request:
1. Acknowledge the limitation clearly
2. Explain why you can't help
3. Suggest an alternative (another team, resource, etc.)
4. Offer to help with something else

Never:
- Make up information
- Pretend to have capabilities you don't have
- Leave the user without options

Agent Templates Library

Quick-Start Templates

General Assistant:

You are a helpful AI assistant. Be friendly, clear, and thorough
in your responses. Ask clarifying questions when needed.

Technical Expert:

You are a [technology] expert. Provide accurate, detailed technical
information. Include code examples when helpful. Cite documentation.

Business Analyst:

You are a business analyst. Help users understand data, identify
trends, and make informed decisions. Use clear visualizations
and explain findings in business terms.

Best Practices Summary

DO

• ✅ Be specific about the agent's role and expertise
• ✅ Define clear boundaries and constraints
• ✅ Include examples in the system prompt
• ✅ Test with diverse scenarios
• ✅ Iterate based on actual usage
• ✅ Match temperature to the task

DON'T

• ❌ Create overly long system prompts (>2000 words)
• ❌ Leave important behaviors undefined
• ❌ Ignore edge cases
• ❌ Enable unnecessary tools
• ❌ Use maximum temperature for factual tasks
• ❌ Skip testing before deployment

Troubleshooting

Agent Not Following Instructions

1. Make instructions more explicit
2. Add examples of desired behavior
3. Lower temperature for more consistency
4. Break complex instructions into steps

Inconsistent Responses

1. Lower temperature value
2. Add more structure to system prompt
3. Include "Always" and "Never" rules
4. Test with varied inputs

Poor Tool Usage

1. Explain when to use each tool in system prompt
2. Provide examples of tool usage
3. Reduce number of enabled tools
4. Add explicit triggers ("When asked about X, use Y tool")

Previous: Workflows API | Next: MCP Integration Guide