Setting Agent Goals

Complete guide to configuring agent objectives through task descriptions, custom instructions, and prompt overrides to achieve desired outcomes.

Overview

Agent goals determine what your agent is trying to achieve and how it approaches tasks. Agent Patterns provides multiple complementary methods for setting and refining agent goals:

1. Task Descriptions: Direct, explicit goals via the input

2. Custom Instructions: Persistent goals across all tasks

3. Prompt Overrides: Fine-tuned goal setting per workflow step

4. Configuration Parameters: Pattern-specific goal constraints

Goal-Setting Methods

1. Via Task Description (Primary Method)

The most direct way to set a goal is through the task description passed to agent.run().

Explicit Goals

from agent_patterns.patterns import ReActAgent

agent = ReActAgent(llm_configs=llm_configs, tools=tools)

# Explicit, specific goal
result = agent.run("Find the current stock price of AAPL and calculate its P/E ratio")

# Multi-part goal
result = agent.run("""
Goal: Create a comprehensive market analysis report

Requirements:
1. Find current stock prices for AAPL, GOOGL, and MSFT
2. Calculate year-over-year growth for each
3. Compare P/E ratios
4. Provide investment insights
""")

Goal Clarity Spectrum

# Vague goal (may produce inconsistent results)
agent.run("Tell me about Python")

# Better: More specific
agent.run("Explain Python's main use cases and why it's popular")

# Best: Clear, measurable goal
agent.run("""
Explain Python programming language:
1. Top 3 use cases with examples
2. Key advantages over other languages
3. Major companies using Python
4. Recommended learning resources

Target audience: Beginners with no programming experience
""")

Success Criteria in Task Description

# Include success criteria
agent.run("""
Task: Research electric vehicle market trends

Success criteria:
- Cover top 5 manufacturers
- Include 2023-2024 sales data
- Identify 3 key trends
- Cite all sources
- Provide executive summary (max 200 words)
""")

2. Via Custom Instructions (Persistent Goals)

Use custom instructions to set goals that apply to all tasks the agent handles.

Persistent Quality Goals

from agent_patterns.patterns import ReflectionAgent

quality_goals = """
QUALITY GOALS:
1. ACCURACY: All facts must be verifiable and cited
2. CLARITY: Use simple language (8th grade reading level)
3. COMPLETENESS: Address all aspects of the question
4. CONCISENESS: No unnecessary verbosity
5. EXAMPLES: Include concrete examples for abstract concepts

SUCCESS CRITERIA:
- Every claim has a source
- No jargon without definitions
- Answers the "what", "why", and "how"
"""

agent = ReflectionAgent(
    llm_configs=llm_configs,
    custom_instructions=quality_goals
)

# These goals apply to every task
result1 = agent.run("Explain quantum computing")
result2 = agent.run("How do vaccines work?")
# Both will follow the quality goals

Domain-Specific Goals

# Medical domain goals
medical_goals = """
PRIMARY GOAL: Provide accurate, evidence-based medical information

Sub-goals:
1. Prioritize patient safety in all responses
2. Cite medical literature and guidelines
3. Acknowledge limitations and uncertainties
4. Recommend professional consultation
5. Use patient-friendly language while maintaining accuracy

CONSTRAINTS:
- Never diagnose specific conditions
- Never recommend specific medications or dosages
- Always include medical disclaimers
"""

agent = SelfDiscoveryAgent(
    llm_configs=llm_configs,
    custom_instructions=medical_goals
)

Performance Goals

# Efficiency goals
efficiency_goals = """
PERFORMANCE GOALS:
1. SPEED: Minimize number of reasoning steps
2. COST: Use cheaper models when possible
3. RELIABILITY: Verify information from multiple sources
4. DETERMINISM: Produce consistent results for same inputs

OPTIMIZATION PRIORITIES:
- Accuracy > Speed > Cost
- Fail gracefully with clear error messages
- Cache repeated computations when possible
"""

agent = ReActAgent(
    llm_configs=llm_configs,
    tools=tools,
    custom_instructions=efficiency_goals,
    max_iterations=3  # Enforces speed goal
)

3. Via Prompt Overrides (Step-Specific Goals)

Use prompt overrides to set different goals for different workflow steps.

Goal-Oriented Overrides

from agent_patterns.patterns import SelfDiscoveryAgent

# Different goals for different steps
goal_overrides = {
    "DiscoverModules": {
        "system": """Your goal: Select reasoning modules that maximize solution quality.

Prioritize modules that:
1. Are proven effective for this problem type
2. Provide complementary perspectives
3. Lead to verifiable conclusions""",
        "user": "Task: {task}\n\nModules:\n{modules}\n\nSelect the {max_modules} best modules:"
    },
    "ExecuteStep": {
        "system": """Your goal: Execute this reasoning step thoroughly and accurately.

Sub-goals:
1. Show your work step-by-step
2. Verify intermediate results
3. Note any assumptions
4. Identify potential errors""",
        "user": "Step: {step_description}\n\nExecute with full reasoning:"
    },
    "SynthesizeOutput": {
        "system": """Your goal: Create a clear, actionable final answer.

Success criteria:
1. Directly answers the original question
2. Is well-structured and easy to follow
3. Highlights key insights
4. Acknowledges any limitations""",
        "user": "Task: {task}\n\nReasoning:\n{reasoning_steps}\n\nSynthesize final answer:"
    }
}

agent = SelfDiscoveryAgent(
    llm_configs=llm_configs,
    prompt_overrides=goal_overrides
)

Outcome-Focused Overrides

# Focus on specific outcome
outcome_overrides = {
    "Generate": {
        "system": """Your goal: Produce actionable recommendations.

Every response must include:
1. Specific actions to take
2. Expected outcomes
3. Potential risks
4. Success metrics

Not theoretical - practical and implementable.""",
        "user": "Situation: {task}\n\nProvide actionable recommendations:"
    }
}

agent = ReflectionAgent(
    llm_configs=llm_configs,
    prompt_overrides=outcome_overrides
)

4. Via Configuration Parameters

Use pattern-specific parameters to constrain goals.

from agent_patterns.patterns import ReActAgent, ReflectionAgent, SelfDiscoveryAgent

# Limit iterations = goal to be efficient
react_agent = ReActAgent(
    llm_configs=llm_configs,
    tools=tools,
    max_iterations=3  # Goal: Solve in max 3 steps
)

# Multiple reflection cycles = goal for high quality
reflection_agent = ReflectionAgent(
    llm_configs=llm_configs,
    max_reflection_cycles=3  # Goal: Refine up to 3 times
)

# Module selection = goal focus
discovery_agent = SelfDiscoveryAgent(
    llm_configs=llm_configs,
    max_selected_modules=2,  # Goal: Use focused approach
    reasoning_modules=domain_specific_modules  # Goal: Use domain expertise
)

Goal Types and Examples

Informational Goals

Goals focused on gathering and presenting information.

# Research goal
agent.run("""
Research goal: Create comprehensive overview of renewable energy

Information requirements:
- Solar, wind, hydro, geothermal technologies
- Current adoption rates globally
- Cost trends over past decade
- Future projections to 2030
- Environmental impact comparison

Format: Executive summary + detailed sections
""")

# Comparison goal
agent.run("""
Compare electric vehicles vs gasoline vehicles across:
1. Total cost of ownership (5 years)
2. Environmental impact
3. Convenience and infrastructure
4. Performance metrics

Goal: Help consumers make informed decisions
""")

Analytical Goals

Goals focused on analysis and insights.

# Root cause analysis goal
agent.run("""
Analyze declining user engagement:

Data provided:
- Daily active users down 25% in Q3
- Session duration decreased from 12min to 8min
- Feature adoption rates unchanged

Goal: Identify top 3 root causes with evidence
""")

# Trend analysis goal
agent.run("""
Analyze cryptocurrency market trends:

Goal: Identify and explain 3 major trends in 2023-2024
- Use quantitative data where possible
- Explain causal factors
- Project implications for 2025
""")

Creative Goals

Goals focused on generation and ideation.

# Content creation goal
agent.run("""
Create a technical blog post about microservices:

Goals:
- Explain benefits and challenges
- Include code examples
- Target audience: intermediate developers
- Length: 1500-2000 words
- Engaging and practical, not theoretical
""")

# Design goal
agent.run("""
Design a loyalty program for coffee shop:

Goals:
- Increase customer retention by 30%
- Appeal to students and professionals
- Low operational overhead
- Mobile-first experience
- Unique/differentiated from competitors

Deliverables:
- Program structure
- Reward tiers
- Implementation plan
""")

Decision Support Goals

Goals focused on recommendations and choices.

# Recommendation goal
agent.run("""
Recommend database technology for new project:

Context:
- E-commerce platform
- 100K+ products
- 10M+ users expected
- Complex search requirements
- Need for scalability

Goal: Recommend top 3 options with:
- Pros/cons for our use case
- Estimated costs
- Implementation complexity
- Risk assessment
""")

# Evaluation goal
agent.run("""
Evaluate A/B test results:

Test: New checkout flow vs current
- Variant A: 5.2% conversion (current)
- Variant B: 5.7% conversion (new)
- 10,000 users per variant
- 2 week test period

Goals:
1. Determine statistical significance
2. Recommend whether to ship
3. Identify next tests to run
""")

Problem-Solving Goals

Goals focused on finding solutions.

# Debugging goal
agent.run("""
Debug authentication failure:

Symptoms:
- Users can't login via OAuth
- Password login works fine
- Started after deployment yesterday
- Affects ~30% of OAuth users

Goal:
1. Identify root cause
2. Provide fix
3. Suggest prevention measures
""")

# Optimization goal
agent.run("""
Optimize database query performance:

Current: Query takes 5.2 seconds
Target: Under 500ms
Query: Complex join across 4 tables with aggregation

Goals:
1. Analyze query execution plan
2. Identify bottlenecks
3. Propose optimizations (indexes, query rewrite, etc.)
4. Estimate expected improvement
""")

Combining Goal-Setting Methods

The real power comes from combining multiple methods:

Example 1: Research Agent

from agent_patterns.patterns import STORMAgent

# 1. Persistent research goals via custom instructions
research_goals = """
RESEARCH QUALITY GOALS:
1. Multiple perspectives: Seek diverse viewpoints
2. Source credibility: Prioritize authoritative sources
3. Recency: Prefer recent information (last 2 years)
4. Objectivity: Present balanced analysis
5. Depth: Go beyond surface-level information

CITATION REQUIREMENTS:
- Cite all factual claims
- Note publication date
- Assess source credibility
"""

# 2. Step-specific goals via overrides
research_overrides = {
    "GenerateQuestions": {
        "system": "Goal: Generate questions that uncover multiple perspectives and deep insights.",
        "user": "Topic: {topic}\n\nGenerate research questions:"
    }
}

# 3. Create agent
agent = STORMAgent(
    llm_configs=llm_configs,
    retrieval_tools={"search": search_function},
    custom_instructions=research_goals,
    prompt_overrides=research_overrides
)

# 4. Specific task goal
result = agent.run("""
Research topic: Impact of AI on employment

Specific goals:
- Historical perspective (past impacts of automation)
- Current trends and data
- Future projections from credible sources
- Both optimistic and pessimistic viewpoints
- Policy implications

Deliverable: 3000-word balanced analysis
""")

Example 2: Customer Service Agent

from agent_patterns.patterns import ReActAgent

# 1. Service quality goals
service_goals = """
CUSTOMER SERVICE GOALS:
1. RESOLUTION: Solve customer issues completely
2. EFFICIENCY: Minimize resolution time
3. SATISFACTION: Ensure positive experience
4. ACCURACY: Provide correct information
5. EMPATHY: Show understanding and care

SERVICE STANDARDS:
- First response within 1 minute
- Full resolution within 24 hours
- Customer satisfaction score > 4.5/5
- No escalations unless absolutely necessary
"""

# 2. Interaction style override
service_overrides = {
    "ThoughtStep": {
        "system": """Goal: Provide excellent customer service.

For each interaction:
1. Acknowledge the customer's issue
2. Gather necessary information
3. Provide clear solution
4. Confirm customer satisfaction

Be empathetic, clear, and efficient.""",
        "user": "Customer: {input}\n\nHistory: {history}\n\nHow to help:"
    }
}

# 3. Create agent
agent = ReActAgent(
    llm_configs=llm_configs,
    tools=customer_service_tools,
    custom_instructions=service_goals,
    prompt_overrides=service_overrides,
    max_iterations=5  # Efficiency goal
)

# 4. Handle customer issue
result = agent.run("""
Customer Issue: Order #12345 hasn't arrived, tracking shows delivered but customer didn't receive it

Customer info: Premium member, first issue ever
Goal: Resolve immediately and maintain satisfaction
""")

Example 3: Code Review Agent

from agent_patterns.patterns import ReflectionAgent

# 1. Code quality goals
quality_goals = """
CODE REVIEW GOALS:
1. CORRECTNESS: Code works as intended
2. SECURITY: No vulnerabilities
3. PERFORMANCE: No obvious inefficiencies
4. MAINTAINABILITY: Clean, well-documented
5. BEST PRACTICES: Follows language idioms

REVIEW STANDARDS:
- Every finding must include specific line reference
- Provide code examples for suggested improvements
- Categorize issues: Critical, Important, Minor, Nitpick
- Acknowledge good practices
"""

# 2. Review process overrides
review_overrides = {
    "Reflect": {
        "system": """Goal: Provide thorough, constructive code review.

Review checklist:
1. Functionality: Does it work correctly?
2. Security: Any vulnerabilities?
3. Performance: Any bottlenecks?
4. Readability: Is it clear?
5. Tests: Adequate coverage?

Be specific, constructive, and educational.""",
        "user": "Code to review:\n{output}\n\nProvide detailed code review:"
    }
}

# 3. Create agent
agent = ReflectionAgent(
    llm_configs=llm_configs,
    custom_instructions=quality_goals,
    prompt_overrides=review_overrides,
    max_reflection_cycles=2  # Thorough review
)

# 4. Review code
result = agent.run("""
Review this authentication function:

def authenticate(username, password):
    user = db.query(f"SELECT * FROM users WHERE username='{username}'")
    if user and user.password == password:
        return create_session(user)
    return None

Goals:
- Identify security issues
- Suggest improvements
- Provide corrected version
""")

Goal Measurement and Validation

Defining Measurable Goals

# Measurable goals in task description
agent.run("""
Task: Optimize checkout flow

Measurable goals:
- Reduce steps from 5 to 3
- Decrease avg time from 2min to 1min
- Increase conversion rate by 15%
- Maintain form completion accuracy > 95%

Success criteria:
- All goals met in A/B test
- No increase in support tickets
- Positive user feedback (NPS > 70)
""")

Validating Goal Achievement

def validate_agent_goals(agent, task, expected_criteria):
    """Validate that agent output meets specified goals."""
    result = agent.run(task)

    validation_results = {}

    # Check for required elements
    if "citations" in expected_criteria:
        has_citations = bool(re.findall(r'\[\d+\]|\[.*?\]', result))
        validation_results["has_citations"] = has_citations

    # Check length goals
    if "max_words" in expected_criteria:
        word_count = len(result.split())
        validation_results["within_length"] = word_count <= expected_criteria["max_words"]

    # Check for required sections
    if "required_sections" in expected_criteria:
        validation_results["has_sections"] = all(
            section.lower() in result.lower()
            for section in expected_criteria["required_sections"]
        )

    # Check for prohibited content
    if "prohibited_terms" in expected_criteria:
        has_prohibited = any(
            term.lower() in result.lower()
            for term in expected_criteria["prohibited_terms"]
        )
        validation_results["no_prohibited_content"] = not has_prohibited

    return validation_results

# Example usage
criteria = {
    "max_words": 500,
    "required_sections": ["Summary", "Details", "Recommendations"],
    "prohibited_terms": ["I think", "maybe", "probably"]
}

validation = validate_agent_goals(agent, task, criteria)
print(f"Goal achievement: {validation}")

Iterative Goal Refinement

def refine_goals_based_on_results(initial_task, initial_result, feedback):
    """Refine goals based on previous attempt."""

    refined_task = f"""
Previous attempt: {initial_task}

Previous result issues:
{feedback}

Refined goals:
{initial_task}

Additional requirements based on feedback:
- Address the issues noted above
- Maintain quality in other areas
"""
    return refined_task

# Example usage
task_v1 = "Explain machine learning"
result_v1 = agent.run(task_v1)

feedback = """
Issues:
- Too technical for beginners
- Lacks concrete examples
- No practical applications mentioned
"""

task_v2 = refine_goals_based_on_results(task_v1, result_v1, feedback)
result_v2 = agent.run(task_v2)

Advanced Goal Patterns

Hierarchical Goals

hierarchical_goals = """
PRIMARY GOAL: Create actionable business recommendations

SECONDARY GOALS:
1. Data-driven: Base recommendations on quantitative analysis
2. Risk-aware: Identify and quantify risks
3. Practical: Focus on implementable solutions
4. Prioritized: Rank by impact and feasibility

TERTIARY GOALS:
1. Clear communication: Executive summary + details
2. Comprehensive: Cover all major aspects
3. Time-bound: Include implementation timeline
"""

agent = SelfDiscoveryAgent(
    llm_configs=llm_configs,
    custom_instructions=hierarchical_goals
)

Conditional Goals

def get_goals_for_user_type(user_type, task_urgency):
    """Generate goals based on context."""

    if user_type == "executive":
        base_goal = "Provide strategic, high-level insights"
        detail_level = "Executive summary with key takeaways"
    elif user_type == "analyst":
        base_goal = "Provide detailed analysis with data"
        detail_level = "Comprehensive with methodology"
    else:
        base_goal = "Provide balanced overview"
        detail_level = "Moderate detail with examples"

    if task_urgency == "high":
        speed_goal = "Prioritize speed: Quick, actionable answer"
    else:
        speed_goal = "Prioritize thoroughness: Comprehensive analysis"

    return f"""
{base_goal}
Detail level: {detail_level}
Approach: {speed_goal}
"""

# Use conditional goals
goals = get_goals_for_user_type(user_type="executive", task_urgency="high")
agent = ReflectionAgent(
    llm_configs=llm_configs,
    custom_instructions=goals
)

Competing Goals and Trade-offs

tradeoff_goals = """
PRIMARY GOALS (in priority order):
1. ACCURACY: Correct information (non-negotiable)
2. SPEED: Fast response (target < 30 seconds)
3. DETAIL: Comprehensive coverage (target 500+ words)
4. SIMPLICITY: Easy to understand (8th grade level)

TRADE-OFF GUIDANCE:
- Never sacrifice accuracy for speed
- If speed conflicts with detail, prefer speed with option to elaborate
- If detail conflicts with simplicity, provide layered information (simple summary + detailed sections)

When goals conflict, explicitly state the trade-off made and why.
"""

agent = SelfDiscoveryAgent(
    llm_configs=llm_configs,
    custom_instructions=tradeoff_goals
)

Common Pitfalls

1. Vague Goals

❌ Bad: Unclear objectives

agent.run("Tell me about climate change")

✅ Good: Specific, measurable goals

agent.run("""
Explain climate change for high school students:
- What it is and what causes it (2-3 paragraphs)
- 3 major impacts with examples
- 3 actions individuals can take
- Use simple analogies for complex concepts
- Include credible sources
""")

2. Conflicting Goals

❌ Bad: Goals that contradict each other

custom_instructions = """
- Be extremely brief (max 50 words)
- Provide comprehensive, detailed analysis
- Include multiple examples
"""

✅ Good: Aligned, prioritized goals

custom_instructions = """
- Provide comprehensive analysis
- Use layered approach: brief summary (50 words) + detailed sections
- Include 2-3 examples per major point
"""

3. Unmeasurable Goals

❌ Bad: Can’t verify achievement

agent.run("Make the answer good")

✅ Good: Measurable criteria

agent.run("""
Goals (measurable):
- Include exactly 3 main points
- Each point supported by data/example
- Total length: 300-500 words
- Reading level: 10th grade
- At least 2 credible sources cited
""")

4. Too Many Goals

❌ Bad: Overwhelming number of objectives

custom_instructions = """
[30 different goals listed]
"""

✅ Good: Focused, prioritized goals

custom_instructions = """
TOP 5 GOALS (in priority order):
1. Accuracy: All facts verified
2. Clarity: 8th grade reading level
3. Completeness: Address all aspects
4. Conciseness: No unnecessary verbosity
5. Citations: Cite all sources
"""

Best Practices

1. Start with Clear Task Goals

Every task should have explicit goals:

template = """
Task: {task_description}

Goals:
1. {primary_goal}
2. {secondary_goal}
3. {tertiary_goal}

Success criteria:
- {criterion_1}
- {criterion_2}
- {criterion_3}

Target audience: {audience}
Format: {format_preference}
"""

2. Use Hierarchical Goal Structure

goals = """
PRIMARY: {most_important}
SECONDARY: {important}
TERTIARY: {nice_to_have}

If goals conflict, prioritize in this order.
"""

3. Make Goals Measurable

measurable_goals = """
Goals:
1. Response length: 500-750 words
2. Reading level: 8th grade (Flesch-Kincaid score 8-10)
3. Citations: Minimum 3 credible sources
4. Examples: 2-3 concrete examples
5. Structure: Intro + 3 sections + conclusion
"""

4. Provide Context

contextual_goals = """
Goal: Explain blockchain technology

Context:
- Audience: Business executives (non-technical)
- Purpose: Evaluate if blockchain fits our use case
- Current knowledge: Familiar with databases, basic web tech
- Time constraint: 10-minute read

Output goals:
- No technical jargon without explanation
- Focus on business value and trade-offs
- Include real-world examples from Fortune 500
- Clear recommendation on applicability
"""

5. Test Goal Achievement

def test_goal_achievement():
    """Test that agent achieves specified goals."""
    task = """
    Explain photosynthesis.

    Goals:
    - Target: 10th grade students
    - Length: 200-300 words
    - Include: Process diagram description
    - Cite: At least one educational source
    """

    result = agent.run(task)

    # Validate
    word_count = len(result.split())
    assert 200 <= word_count <= 300, f"Length goal not met: {word_count} words"
    assert "source:" in result.lower() or "reference:" in result.lower(), "Citation goal not met"
    # More validations...

Next Steps

• Learn about Prompt Customization methods

• Review Configuration Guide for parameter tuning

• See Best Practices for production usage

• Explore individual pattern docs for pattern-specific goals

Reference

Goal-Setting Method Comparison

Method	Scope	Priority	Best For
Task Description	Single task	Highest	Specific, one-off goals
Custom Instructions	All tasks	Medium	Persistent quality standards
Prompt Overrides	Workflow steps	Highest	Fine-grained control
Config Parameters	Pattern behavior	System	Constraints and limits

Example Goal Templates

See /ai/work/claude-code/agent-patterns/examples/ for:

• Research goals (STORM pattern)

• Quality goals (Reflection pattern)

• Efficiency goals (ReAct pattern)

• Multi-objective goals (Self-Discovery pattern)