How to Define Roles and Instructions for an AI Agent: Patterns from Awesome-LLM-Apps

Define roles and instructions for an AI agent by using the role parameter for high-level purpose descriptions and the instructions parameter for detailed behavioral constraints, as demonstrated in the Shubhamsaboo/awesome-llm-apps repository.

The awesome-llm-apps collection showcases production-ready patterns for building LLM-powered agents using the Agno framework. A critical design decision in these implementations is how to define roles and instructions for an AI agent to ensure consistent, predictable behavior across travel planning, audio tours, and research tasks.

Understanding the Two Mechanisms for Agent Definition

The repository employs two complementary mechanisms when defining agent behavior. Understanding when to use each helps you control agent outputs effectively.

The Role Parameter (High-Level Purpose)

The role argument serves as a concise natural-language label that the framework converts into a system prompt. In starter_ai_agents/ai_travel_agent/travel_agent.py, the Researcher agent demonstrates this pattern:

role="Searches for travel destinations, activities, and accommodations based on user preferences"

This single sentence guides the LLM's tone and scope without overwhelming the context window. It acts as a behavioral anchor, telling the model its primary function before any user interaction begins.

The Instructions Parameter (Detailed Behavior)

The instructions field accepts either a string or list of strings containing granular behavioral rules, constraints, and workflow steps. The voice_ai_agents/ai_audio_tour_agent/agent.py file demonstrates this with multi-line constants like ARCHITECTURE_AGENT_INSTRUCTIONS, which enforce specific constraints:

• Word limits and formatting restrictions (no headings)
• Mandatory web search usage for up-to-date context
• Technical depth requirements balanced with accessible explanations
• Prohibited behaviors (hallucination, unsupported claims)

Implementing Role-Based Agents in Practice

When you define roles and instructions for an AI agent handling travel research, you can start with a concise role definition. The travel_agent.py file shows how the Researcher agent combines a role with tool access:

from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.serpapi import SerpApiTools

researcher = Agent(
    name="Researcher",
    role="Searches for travel destinations, activities, and accommodations based on user preferences",
    model=OpenAIChat(id="gpt-4o", api_key=openai_api_key),
    description="""You are a world-class travel researcher ...""",
    instructions=[
        "Given a travel destination, generate a list of 3 search terms",
        "For each search term, `search_google` and analyze the results.",
        "From the results of all searches, return the 10 most relevant results"
    ],
    tools=[SerpApiTools(api_key=serp_api_key)],
    add_datetime_to_context=True,
)

The role parameter here establishes the agent's identity, while the instructions list provides the specific workflow steps required to fulfill that role.

Crafting Detailed Instruction Blocks for Specialized Agents

For domain-specific agents like the Architecture guide in the audio tour system, you need to define roles and instructions for an AI agent with strict content constraints. The ai_audio_tour_agent/agent.py demonstrates this pattern:

from pydantic import BaseModel
from agents import Agent, WebSearchTool
from agents.model_settings import ModelSettings

class Architecture(BaseModel):
    output: str

ARCHITECTURE_AGENT_INSTRUCTIONS = """
You are the Architecture agent for a self-guided audio tour system.
1. Describe architectural styles, notable buildings, and urban planning features.
2. Provide technical insights balanced with accessible explanations.
7. Make sure the content is strictly between the upper and lower Word Limit.
NOTE: Given a location, use web search to retrieve up-to-date context.
"""

architecture_agent = Agent(
    name="ArchitectureAgent",
    instructions=ARCHITECTURE_AGENT_INSTRUCTIONS,
    model="gpt-4o-mini",
    tools=[WebSearchTool()],
    model_settings=ModelSettings(tool_choice="required"),
    output_type=Architecture,
)

This approach ensures the model receives the entire behavioral specification at the start of the conversation, enabling reliable enforcement of constraints like word limits and mandatory web search usage.

Combining Roles and Instructions for Maximum Control

To define roles and instructions for an AI agent with both clear identity and detailed workflow, combine both parameters. The Planner agent in travel_agent.py demonstrates this hybrid approach:

planner = Agent(
    name="Planner",
    role="Generates a draft itinerary based on user preferences and research results",
    description="""
You are a senior travel planner. Given a travel destination, the number of days the user wants to travel for, and a list of research results,
your goal is to generate a draft itinerary that meets the user's needs and preferences.
""",
    instructions=[
        "Create a well-structured, engaging itinerary.",
        "Quote facts where possible and provide attribution.",
        "Never hallucinate; keep the quality high."
    ],
    model=OpenAIChat(id="gpt-4o", api_key="YOUR_OPENAI_KEY"),
)

Here, the role provides a concise summary for system logs and quick reference, while description and instructions layer in the nuanced behavioral requirements.

Integrating Tools with Role Definitions

When you define roles and instructions for an AI agent that requires external data, you must align the behavioral directives with tool capabilities. The repository consistently pairs instruction blocks with tool arrays:

• SerpApiTools: Used in travel_agent.py to fulfill instructions requiring Google searches
• WebSearchTool: Used in ai_audio_tour_agent/agent.py to satisfy the explicit instruction "use web search to retrieve up-to-date context"

The model_settings=ModelSettings(tool_choice="required") parameter ensures the model cannot ignore instructions that mandate tool usage, effectively enforcing the agent's defined role.

Summary

• Use the role parameter to define roles and instructions for an AI agent when you need a concise, high-level description that establishes the agent's core purpose and identity.
• Use the instructions parameter when you require detailed behavioral constraints, workflow steps, content restrictions, or mandatory tool usage patterns.
• Combine both parameters for complex agents that need clear identity markers alongside granular operational directives, as demonstrated in starter_ai_agents/ai_travel_agent/travel_agent.py.
• Align tools with instructions by attaching specific tool classes (e.g., SerpApiTools, WebSearchTool) and setting tool_choice="required" when instructions mandate external data retrieval.

Frequently Asked Questions

What is the difference between role and instructions in AI agents?

The role parameter provides a high-level natural-language label that describes the agent's purpose, such as "Searches for travel destinations," which becomes a system prompt establishing the model's identity. The instructions parameter contains specific behavioral rules, workflow steps, or constraints—such as word limits, mandatory web searches, or formatting restrictions—that dictate exactly how the agent should execute its role.

How do I define roles and instructions for an AI agent using Python?

To define roles and instructions for an AI agent in Python using the Agno framework (as shown in the awesome-llm-apps repository), instantiate the Agent class with the role and instructions parameters:

from agno.agent import Agent

agent = Agent(
    name="Researcher",
    role="Searches for travel destinations based on user preferences",
    instructions=[
        "Generate 3 search terms for the destination",
        "Use search_google tool for each term",
        "Return the 10 most relevant results"
    ]
)

Can I use both role and instructions together in the same agent?

Yes, combining both parameters is a recommended pattern for complex agents. The role parameter establishes the agent's identity for quick reference and system logs, while the instructions field provides the detailed operational workflow. For example, in starter_ai_agents/ai_travel_agent/travel_agent.py, the Planner agent uses a concise role description alongside a multi-line description and specific instructions list to balance clarity with granular control.

Where can I find real-world examples of AI agent role definitions?

The Shubhamsaboo/awesome-llm-apps repository contains multiple reference implementations. Key files include starter_ai_agents/ai_travel_agent/travel_agent.py, which demonstrates role-based travel researchers and planners with instruction lists, and voice_ai_agents/ai_audio_tour_agent/agent.py, which shows specialized architecture, culinary, and culture agents defined by extensive instruction blocks with strict content constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}