Module: Implement Generative AI and Agentic Solutions

Lesson: Define Agent Roles and Goals in Foundry

Introduction: The Importance of Role-Based Agent Design

In the evolving landscape of artificial intelligence, shifting from simple prompt-based interactions to autonomous agentic workflows is the most significant leap forward. An agent is not merely a chatbot that answers questions; it is a system designed to perceive its environment, reason about its objectives, and execute sequences of actions to achieve a specific outcome. When we talk about building agents within a platform like Foundry, we are essentially defining a "digital employee" with a specific job description, a set of responsibilities, and a clear set of success metrics.

Why does defining roles and goals matter? Without a precise definition, an AI agent tends to suffer from "scope creep" and "hallucination drift." It may try to solve every problem it encounters, leading to inefficient use of computational resources and unreliable outputs. By clearly establishing what an agent is (its persona or role) and what it is trying to achieve (its goals), you provide the necessary constraints that allow the underlying Large Language Model (LLM) to focus its reasoning. This lesson will guide you through the architectural process of defining these parameters to create highly effective, reliable agents.

Understanding the Architecture: Roles vs. Goals

To design an agent effectively, you must distinguish between its identity and its objective. A role defines the who and the how—the persona, the tone, the constraints, and the tools at its disposal. A goal defines the what and the why—the specific state of the world or the output the agent must reach to be considered successful.

Defining the Agent Role

The role is the foundation of the agent's system prompt. It sets the behavioral guardrails. If you are building a data analysis agent, its role might be defined as: "You are a senior data analyst specialized in supply chain logistics. You are analytical, objective, and prioritize data-backed evidence over intuition. You use the provided Python execution tool to validate all numerical claims."

Defining the Agent Goal

The goal is the target state. It should be measurable and time-bound if possible. Using the same data analyst example, the goal might be: "Your objective is to identify the root cause of shipment delays in the Q3 dataset and provide a summary report with three actionable recommendations for the operations team."

Callout: The Distinction Between Persona and Task Think of the role as the "Professional Profile" on a resume—it dictates the knowledge base and the communication style. Think of the goal as the "Project Brief"—it dictates the specific deliverables and the definition of done. A well-defined agent needs both to function autonomously without constant human intervention.

Step-by-Step: Defining Your Agent in Foundry

Building an agent in Foundry requires a structured approach to configuration. You cannot simply "start" an agent; you must engineer its environment. Follow these steps to define your agent’s foundation.

Step 1: Establish the Contextual Domain

Before writing a single line of code, document the domain the agent will inhabit. What data does it have access to? What are the common workflows in this domain? If the agent is meant to assist in software engineering, it needs access to the repository and the issue tracking system. If it is in human resources, it needs access to policy documents.

Step 2: Draft the System Persona

The system persona should be concise but descriptive. Avoid vague instructions like "be helpful." Instead, use specific descriptors. Tell the agent exactly what its perspective is. For example: "You are an expert in regulatory compliance. Your task is to review documents for policy violations. You are highly cautious and always cite the specific section of the policy manual when flagging an issue."

Step 3: Formalize the Objective (Goal)

State the goal as an explicit objective. Use conditional logic if necessary. For instance: "If the data indicates a trend of declining sales for three consecutive months, you are to trigger an alert to the regional manager and request a meeting."

Step 4: Configure Tool Access

An agent’s goal is only as achievable as its tools are functional. If your goal is to "update the database," the agent must have a write_database tool. Map your goals to specific tool capabilities to ensure the agent doesn't attempt a task it lacks the permissions or the technical means to perform.

Practical Examples of Agent Definitions

Let’s look at two distinct examples to see how roles and goals change the agent's behavior.

Example 1: The Customer Support Agent

Role: You are a Level 1 Customer Support Representative for an e-commerce platform. Your tone is empathetic, professional, and concise. You prioritize customer satisfaction while adhering to the company’s return policy.
Goal: Resolve incoming inquiries by troubleshooting common issues. If an issue requires a refund, verify the order status using the OrderLookUp tool before initiating the return process.
Constraint: Never promise a refund without verifying the transaction ID.

Example 2: The Infrastructure Monitoring Agent

Role: You are a Site Reliability Engineer (SRE) assistant. Your tone is technical, direct, and urgent. You focus on system uptime and performance metrics.
Goal: Monitor server logs for error spikes. If an error rate exceeds 5% in any 10-minute window, analyze the logs to identify the culprit service and generate a summary for the on-call engineer.
Constraint: Do not attempt to restart services without explicit approval from the human supervisor.

Technical Implementation: Configuring the Agent Schema

In Foundry, you generally configure these agents through a combination of JSON structures or specialized agent definition files. Below is a conceptual representation of how you might structure an agent definition in code.

{
  "agent_name": "LogAnalyzer_01",
  "role": {
    "title": "Junior DevOps Analyst",
    "persona": "Analytical, precise, and cautious. You prioritize system stability.",
    "tone": "Formal and concise."
  },
  "goals": [
    {
      "id": "monitor_logs",
      "description": "Analyze incoming system logs for HTTP 500 errors.",
      "success_criteria": "Identify the source service within 30 seconds of an error spike."
    },
    {
      "id": "report_issues",
      "description": "Draft a summary of the incident for the team.",
      "success_criteria": "Include timestamp, error code, and affected user count."
    }
  ],
  "tools": ["log_reader", "email_sender", "slack_notifier"]
}

Note: Always keep your goal definitions distinct from your role definitions. If you find your "role" section becoming cluttered with procedural instructions (e.g., "First do this, then do that"), move those instructions into a "workflow" or "process" section. This keeps the agent's personality clean and its logic modular.

Best Practices for Defining Effective Agents

Defining roles and goals is an iterative process. You rarely get the prompt perfect on the first try. Here are industry-standard best practices to ensure your agents remain functional and safe.

Iterative Refinement: Start with a broad goal and narrow it down as you test. If the agent makes mistakes, add a constraint to the role. If the agent fails to act, clarify the goal.
Explicit Constraints: Always include what the agent should not do. This is often more important than what it should do. For example, "Do not access PII (Personally Identifiable Information) unless authorized by the system admin."
Modular Tooling: Give the agent the smallest set of tools necessary to achieve its goal. This is known as the "principle of least privilege." An agent that can do too much is an agent that is more likely to cause unintended side effects.
Defined Success States: If an agent doesn't know what "done" looks like, it will loop indefinitely or ask the user for confirmation repeatedly. Define success criteria clearly so the agent knows when to stop.
Human-in-the-Loop (HITL) Integration: For high-stakes tasks, build the requirement for human verification directly into the goal. For example, "Before finalizing the order, output the summary and wait for user confirmation."

Common Pitfalls and How to Avoid Them

Even experienced developers fall into common traps when defining agent roles and goals. Avoiding these will save you significant debugging time.

Pitfall 1: Overloading the System Prompt

Many developers try to cram every possible edge case into the system prompt. This results in "prompt dilution," where the LLM becomes less effective at following the core instructions because it is overwhelmed by secondary ones.

Solution: Keep the system prompt focused on the "Role." Use external knowledge bases or configuration files to store complex procedural logic.

Pitfall 2: Vague Goals

"Help the user as much as possible" is not a goal; it is a sentiment. An agent needs a target.

Solution: Use the SMART criteria (Specific, Measurable, Achievable, Relevant, Time-bound). "Reduce average ticket resolution time by 10% by providing relevant knowledge base links" is a measurable goal.

Pitfall 3: Ignoring Tool Context

If an agent has a tool but doesn't know when to use it, the tool is useless.

Solution: Provide explicit instructions in the role definition for when to trigger specific tools. For example: "Only use the SQL_Query tool if the user asks a question that requires data aggregation from the Sales table."

Callout: The "Reasoning" Gap Many developers assume that simply giving an agent a goal is enough. However, agents often need a "Reasoning Framework." If your agent is failing to reach its goals, it might be because it isn't "thinking" before it acts. You can improve this by adding a directive to its role: "Before executing any tool, outline your plan in a 'thought' block."

Comparison: Role vs. Goal vs. Constraint

Element	Purpose	Example
Role	Defines identity and behavior.	"You are a professional financial advisor."
Goal	Defines the outcome or task.	"Provide a summary of the Q4 portfolio."
Constraint	Defines safety and boundaries.	"Do not provide specific stock tips."
Tool	Defines capability.	"Access to the `market_data` API."

Step-by-Step Implementation: A Practical Exercise

To solidify these concepts, let's walk through building a "Meeting Summarizer" agent.

Step 1: Define the Role "You are a professional Meeting Scribe. Your role is to capture key decisions and action items from meeting transcripts. You are neutral, objective, and you never editorialize the content."

Step 2: Define the Goal "Your goal is to output a structured summary in Markdown format. The summary must include: 1) A list of attendees, 2) A list of decisions made, 3) A table of action items with owners and deadlines."

Step 3: Define Constraints "If a transcript is incomplete or incoherent, do not invent information. Instead, note the missing information in the 'Notes' section of the report."

Step 4: Define Tools "You have access to the text_parser tool to read the transcript and the file_writer tool to save the report to the local directory."

Step 5: Testing and Refinement Test the agent with a sample transcript. If it misses an action item, update the goal definition to be more specific: "Ensure that every action item identified must have an associated owner; if no owner is named, label it as 'Unassigned'."

Advanced Considerations: Agentic Memory and State

As your agents become more complex, you will need to think about how they remember their goals over long sessions. A well-defined agent should be able to maintain state. If an agent is in the middle of a multi-step goal and the session times out, it should be able to resume where it left off.

When defining your agent’s goals, consider the "state" of the goal. Is it:

Pending: The goal has been assigned but not yet started.
In-Progress: The agent is currently gathering information or using tools.
Blocked: The agent is waiting for external input (e.g., a human response).
Completed: The success criteria have been met.

By building agents that report their state, you create transparency. A user should be able to ask an agent, "What is your current goal?" and the agent should be able to articulate it based on its configuration. This is a hallmark of a robust agentic system.

The Role of Feedback Loops in Goal Achievement

An agent's performance is rarely static. You should implement a feedback loop where the agent evaluates its own performance against its goals. You can achieve this by adding a "Review" step to the agent's workflow.

Self-Correction: After the agent completes a task, have it review its output against its success criteria. If the output doesn't match, the agent should be instructed to revise its work.
Human Feedback: Allow the human user to provide a "thumbs up" or "thumbs down" on the agent's output. This feedback can be used to refine the agent's system prompt or to adjust the weighting of its goals.

Warning: Be careful not to create a "feedback loop of death." If an agent is poorly designed, it might get caught in a cycle of attempting a task, failing, and then repeatedly trying to "self-correct" in a way that consumes excessive tokens or API costs. Always set a maximum number of retries or "thought iterations" for any given task.

FAQ: Common Questions about Agent Definition

Q: How many goals should an agent have? A: It is best to stick to one primary goal per agent. If you have a complex project, create a "Manager Agent" that delegates sub-goals to "Worker Agents." This keeps each agent's scope manageable and reduces error rates.

Q: Should I put the goal in the system prompt or the user message? A: The high-level objective should be in the system prompt. Specific, task-oriented goals that change frequently should be passed in the user message. For example, "Summarize this specific transcript" is a user message, while "You are a professional scribe" is a system prompt.

Q: What if my agent is not following its role? A: Often, this is because the role description is too abstract. Use "few-shot prompting" within the role definition. Provide examples of the role in action. "You are a helpful assistant. Example: User: 'Hello' -> Agent: 'Hello! How can I assist you with your data today?'"

Q: How do I handle conflicting goals? A: Always prioritize goals. If an agent has to choose between "speed" and "accuracy," explicitly state in the instructions: "Accuracy is your primary goal. If you are unsure, prioritize correctness over speed."

Best Practices for Long-Term Maintenance

As your business or project grows, your agents will need to evolve. You should treat your agent definitions as version-controlled code.

Version Control: Store your agent definitions (JSON/YAML files) in a Git repository. This allows you to track changes, revert to previous versions if an update breaks functionality, and collaborate with your team.
Documentation: Maintain a "Registry" of your agents. For each agent, document its purpose, its owner (the human responsible for it), its access levels, and its primary success metrics.
Monitoring: Regularly review the logs. Are the agents achieving their goals? Are they hitting the "blocked" state too often? Use this data to refine the roles and goals.
Security Audits: Periodically review the tools your agents have access to. As the system grows, you might find that an agent has more permissions than it needs. Prune those permissions to keep the system secure.

Key Takeaways

Identity and Purpose: Always separate the "Role" (who the agent is) from the "Goal" (what the agent is trying to achieve). This modularity is essential for clarity and reliability.
Specificity is King: Avoid vague instructions. Use clear, measurable criteria to define success. If an agent doesn't know what "done" looks like, it will not function effectively.
Constraints are Protective: Defining what an agent cannot do is just as important as defining what it should do. Constraints act as the guardrails that prevent the agent from causing unintended consequences.
Iterative Design: You will not get the definition perfect on the first try. Plan for a lifecycle of testing, observing performance, and refining the instructions.
Principle of Least Privilege: Keep the agent’s toolset as lean as possible. Only grant the specific tools required to reach the defined goal.
Human-in-the-Loop: For sensitive operations, make human confirmation an explicit part of the agent’s goal structure.
Version and Monitor: Treat your agent definitions as software. Store them in version control and monitor their performance to ensure they continue to meet your business needs over time.

Building agents is a shift from programming logic to programming behavior. By mastering the definition of roles and goals, you move from being a developer who writes scripts to an architect who designs intelligent systems capable of handling complex, real-world tasks with precision and reliability. Keep your definitions clean, your goals measurable, and your constraints firm, and you will build agents that provide lasting value to your organization.

Define Agent Roles and Goals