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

> Learn how to define roles and instructions for an AI agent using patterns from Awesome-LLM-Apps. Master AI agent behavior with clear role and instruction parameters.

- Repository: [Shubham Saboo/awesome-llm-apps](https://github.com/shubhamsaboo/awesome-llm-apps)
- Tags: how-to-guide
- Published: 2026-02-19

---

**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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/starter_ai_agents/ai_travel_agent/travel_agent.py), the Researcher agent demonstrates this pattern:

```python
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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/travel_agent.py) file shows how the Researcher agent combines a role with tool access:

```python
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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/ai_audio_tour_agent/agent.py) demonstrates this pattern:

```python
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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/travel_agent.py) demonstrates this hybrid approach:

```python
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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/travel_agent.py) to fulfill instructions requiring Google searches
- **WebSearchTool**: Used in [`ai_audio_tour_agent/agent.py`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/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:

```python
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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/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`](https://github.com/Shubhamsaboo/awesome-llm-apps/blob/main/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.