🤖 Simulated AI Agent with Tools

This project demonstrates a simple Agentic AI workflow built with Python.

The agent can select and use different tools based on the user's request.

✨ Features

• Tool Registry
• @tool Decorator
• Calculator Tool
• Weather Tool
• Word Count Tool
• Simple Keyword-Based Routing
• Argument Extraction
• JSON Function Calls
• Tool Execution
• Retry Mechanism
• Conversation History
• Execution Logging
• Reason → Act → Observe Workflow

---

🛠️ Tools

Calculator

The calculator tool evaluates mathematical expressions.

Example request:

Calculate 5 + 4

The agent detects the mathematical expression and selects the calculator tool.

---

Weather

The weather tool returns fake weather information for testing purposes.

Example request:

What is the weather in Lahore?

The agent extracts the city name and calls the get_weather tool.

The weather tool also randomly raises a temporary error to demonstrate the retry mechanism.

---

Word Count

The word count tool counts the total number of words in the provided text.

Example request:

How many words are in this text?

The agent selects the words_count tool.

---

🧩 Tool Registry

The project uses a dictionary called tool_registery to store the available tools.

Each tool is registered using the @tool decorator.

The registry maps:

Tool Name → Function

For example:

calculator → calculator()
get_weather → get_weather()
words_count → words_count()

This allows the agent to find and execute tools dynamically.

---

🎯 Tool Selection

The agent uses a simple rule-based router to decide which tool should be used.

Routing Logic

User Message
     ↓
   route()
     ↓
 ┌───────────────┐
 │ Weather?      │ → get_weather
 │ Word count?   │ → words_count
 │ Math expression? │ → calculator
 └───────────────┘

For example:

User Request	Selected Tool
Calculate 5 + 4	calculator
Weather in Lahore	get_weather
How many words?	words_count

---

📦 Argument Extraction

After selecting a tool, the agent extracts the required arguments from the user's message.

Calculator

User:
Calculate 5 + 4

Arguments:
{
    "expression": "5 + 4"
}

Weather

User:
What is the weather in Multan?

Arguments:
{
    "city": "Multan"
}

Word Count

Arguments:
{
    "text": "user message"
}

---

🔗 JSON Function Call

The agent represents the selected tool and its arguments as a JSON-style function call.

Example:

{
    "tool": "calculator",
    "arguments": {
        "expression": "5 + 4"
    }
}

For a weather request:

{
    "tool": "get_weather",
    "arguments": {
        "city": "Multan"
    }
}

This makes the tool decision visible before execution.

---

⚙️ Tool Execution

After creating the function call, the agent executes the selected tool.

The execution flow is:

Tool Name
    ↓
Find Function in Tool Registry
    ↓
Pass Arguments
    ↓
Execute Function
    ↓
Get Result

The selected function receives its arguments and returns a result.

---

🔁 Retry Mechanism

The agent includes a retry mechanism for failed tool executions.

Each tool can be attempted up to 3 times.

Attempt 1
    ↓
  Error
    ↓
Attempt 2
    ↓
  Error
    ↓
Attempt 3
    ↓
Success / Final Failure

The weather tool intentionally generates temporary errors so that this retry system can be tested.

If the tool still fails after 3 attempts, the agent returns a failure message.

---

👀 Observation

After successful tool execution, the returned value becomes the observation.

Example:

Observation:
9

The agent then uses this result to create the final answer.

---

💬 Final Answer

The agent creates a final response from the tool result.

Example:

Final Answer:
Result: 9

For weather:

Final Answer:
Result: 38°C, Sunny

---

🧠 Conversation History

The agent stores each turn in:

self.history

Each history record contains:

• User message
• Tool call
• Result
• Final answer

Example:

{
    "user_message": "Calculate 5 + 4",
    "tool_call": {
        "tool": "calculator",
        "arguments": {
            "expression": "5 + 4"
        }
    },
    "result": 9,
    "final_answer": "Result: 9"
}

---

📝 Execution Logging

Every agent turn is saved to:

agent-log.txt

The log records the execution history of the agent.

It contains:

• User message
• Selected tool
• Tool arguments
• Tool result
• Final answer

---

🔄 Agent Workflow

The complete agent workflow is:

User Message
      ↓
    Reason
      ↓
    route()
      ↓
 Select Tool
      ↓
 arguments()
      ↓
Create JSON Function Call
      ↓
     Act
      ↓
execute_tool()
      ↓
Try / Retry up to 3 times
      ↓
   Observe
      ↓
   Result
      ↓
 Final Answer
      ↓
Conversation History
      ↓
 agent-log.txt

---

🧪 Test Cases

Test 1 — Calculator

Calculate 5 + 4

Expected flow:

User Message
     ↓
calculator
     ↓
5 + 4
     ↓
9

---

Test 2 — Weather

What is the Weather in Multan?

Expected flow:

User Message
     ↓
get_weather
     ↓
Multan
     ↓
Weather Result

If the weather tool fails, the agent retries up to 3 times.

---

🎓 Concepts Demonstrated

This project demonstrates the following Agentic AI concepts:

• Tool Calling
• Tool Registry
• Decorators
• Routing
• Argument Extraction
• JSON Function Calls
• Tool Execution
• Retry Logic
• Reason → Act → Observe
• Conversation History
• Execution Logging

---

📌 Summary

This project is a small simulation of how an AI agent can interact with external tools.

Instead of directly answering every request, the agent:

1. Understands the request using simple rules.
2. Selects an appropriate tool.
3. Extracts the required arguments.
4. Creates a JSON-style function call.
5. Executes the selected tool.
6. Retries if the tool fails.
7. Observes the result.
8. Generates a final answer.
9. Stores the conversation history.
10. Saves the execution log.