What You Will Learn

AI agents can do more than generate text. An agent can decide what information it needs, call a tool, inspect the result, perform another action, and continue until a task is completed.

• Retrieve information
• Calculate indicator values
• Check programme data
• Use external tools
• Combine results
• Produce a final explanation

Before You Start

This tutorial is intended for people with basic Python knowledge. You do not need to know LangChain, LangGraph, LlamaIndex, or another agent framework.

• Python 3
• An API key for your model provider
• A text editor or IDE
• Basic Python knowledge

1. What Makes Something an AI Agent?

A normal chatbot generally follows:

An agent introduces a decision-making loop:

For example, if you ask:

An agent can:

1. Determine that it needs the current time.
2. Call a time tool.
3. Receive the result.
4. Extract the hour.
5. Call a calculation tool.
6. Return the final answer.

2. The Four Components of an AI Agent

1. Perception

The agent receives information such as user questions, datasets, API responses, documents, or database records.

2. Reasoning

The model determines what should happen next and which action may be required.

3. Tool Use

Tools allow the agent to interact with calculations, data, documents, APIs, and other systems.

4. Memory

The agent maintains information about previous actions, observations, and the current task.

3. Understanding the ReAct Pattern

A simple way to understand an agent is:

The workflow is:

4. Create the Agent’s Data Structures

Start by defining the objects that represent messages, tools, actions, and agent state.

from dataclasses import dataclass, field
from typing import List, Callable, Dict, Any, Optional

@dataclass
class Message:
    role: str
    content: str

@dataclass
class Tool:
    name: str
    description: str
    func: Callable
    parameters: Dict[str, Any]

@dataclass
class Action:
    action_name: Optional[str] = None
    action_input: Optional[str] = None

@dataclass
class AgentState:
    messages: List[Message] = field(default_factory=list)
    step_count: int = 0

5. Connect Python to an LLM

The original source demonstrates a framework-free HTTP approach. For a current OpenAI implementation, a simple example is:

from openai import OpenAI
client = OpenAI()
response = client.responses.create(
    model="gpt-5",
    input="Explain what an AI agent is in two sentences."
)
print(response.output_text)

6. Give the Agent Tools

Tools are controlled functions that allow an agent to perform specific operations.

Tool 1: Current Time

import datetime
def get_current_time():
    return datetime.datetime.now(
        datetime.timezone.utc
    ).isoformat()

Tool 2: Calculator

import re
def calculate(expression: str) -> str:
    if not re.match(
        r'^[\d\s\+\-\*\/\(\)\.]+$',
        expression
    ):
        return "Error: invalid expression."
    try:
        return str(eval(expression))
    except Exception as e:
        return f"Error: {e}"

Register the Tools

time_tool = Tool(
    name="get_current_time",
    description="Returns the current time in UTC.",
    func=get_current_time,
    parameters={}
)
math_tool = Tool(
    name="calculate",
    description="Calculates a basic mathematical expression.",
    func=calculate,
    parameters={"expression": "string"}
)
AVAILABLE_TOOLS = {
    "get_current_time": time_tool,
    "calculate": math_tool
}

7. Build the Agent Execution Loop

The core loop is:

for step in range(max_steps):
    ask the model what to do
    if it wants to finish:
        return final answer
    identify the requested tool
    validate the request
    execute the tool
    store the result
    continue

8. Why a Maximum Step Count Matters

Agents can get stuck in loops:

Use a maximum number of steps:

MAX_STEPS = 5

9. The Agent in Action

Consider:

10. Apply the Architecture to M&E

Imagine building an Indicator Monitoring Agent.

Instead of giving the model unrestricted access to your system, define specific tools:

11. Example: Indicator Achievement Agent

Suppose:

def calculate_achievement(current, target):
    return (current / target) * 100

The result would be:

The AI can then explain the result in natural language while Python handles the calculation.

12. Examples of M&E Agents

Data Quality Agent

read_dataset() → check_missing_values() → check_duplicates() → summarise_quality()

Evidence Agent

search_documents() → retrieve_evidence() → compare_findings() → summarise_evidence()

Reporting Agent

get_results() → identify_variances() → draft_report_section()

Beneficiary Feedback Agent

load_feedback() → classify_feedback() → identify_themes() → summarise_findings()

13. Agent vs. Chatbot

14. When Should You NOT Use an Agent?

Agents add complexity. A normal scripted workflow may be better when:

• The steps are always identical.
• The calculations are deterministic.
• There are few decisions.
• The process does not require model judgment.
• Reliability is more important than flexibility.

15. Memory and Context Management

As an agent runs, its context grows with requests, tool calls, results, and observations.

For longer workflows, consider summarising older information while preserving:

• The original evaluation question
• Important assumptions
• Key evidence
• Important tool results
• Decisions already made
• Unresolved issues

16. Structured Outputs

A basic educational implementation might parse text such as:

Action: calculate
Action Input: {"expression": "9 * 14"}

This can be fragile. Production systems should use structured tool calls and validated schemas wherever supported.

17. Add Guardrails

Tool Allow-List

Only expose tools the agent actually needs.

Parameter Validation

Validate every argument before executing a tool.

Maximum Steps

Prevent the agent from running indefinitely.

Permission Boundaries

Separate read, write, and delete permissions.

Human Review

Keep human review for consequential decisions such as evaluation conclusions, donor reporting, sensitive classifications, and decisions based on incomplete evidence.

18. A Practical M&E Agent Architecture

The agent is therefore a system architecture, not simply a prompt.

19. Production Improvements

• Structured tool calls: Avoid fragile text parsing.
• Logging: Record important actions and results.
• Retries: Handle temporary failures.
• Validation: Check tool results.
• Human approval: Review high-impact actions.
• Evaluation: Test accuracy, tool selection, and failure rates.

Challenge: Add an Evidence Tool

Add a tool such as:

def search_evidence(topic):
    ...

Then ask:

Key Concepts