# 🤖 AI Agent Tool-Calling: The Complete Guide

> **Master the art of building AI agents that can interact with the real world through tools, APIs, and external systems.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

---

## 🌟 What is This Repository?

This repository is a **comprehensive educational resource** for developers, AI enthusiasts, and engineers who want to learn how to build AI agents with tool-calling capabilities. We cover both emerging protocols (UTCP & MCP) and general best practices for creating agents that can interact with external systems, APIs, databases, and command-line tools.

**⭐ If you find this repository useful, please give it a star! It helps others discover this resource. ⭐**

### Why Tool-Calling Matters

Large Language Models (LLMs) are powerful but limited—they can't:
- Access real-time information
- Execute actions in the real world
- Query databases or call APIs
- Run calculations or system commands

**Tool-calling solves this.**[[1]](https://www.infoq.com/news/2023/06/openai-api-function-chatgpt/) It enables AI agents to extend their capabilities by invoking external tools, turning static models into dynamic, interactive agents that can truly help users accomplish tasks.

---

## 📚 What You'll Learn

This repository takes you from zero to building production-ready AI agents:

- ✅ **Fundamentals**: What tool-calling is and why it's essential for modern AI agents
- ✅ **Protocols**: Deep dives into UTCP (Universal Tool Calling Protocol) and MCP (Model Context Protocol)
- ✅ **Architecture Patterns**: Reactive agents, Planner-Executor, Multi-Agent systems
- ✅ **Hands-on Examples**: Working code in Python, TypeScript, and more
- ✅ **Real-World Projects**: Data analyst bot, DevOps assistant, customer support agent
- ✅ **Security & Reliability**: Best practices for safe, production-ready agents
- ✅ **Design Patterns**: Proven patterns and anti-patterns from real implementations
- ✅ **Interview Prep**: Questions, scenarios, and design challenges

---

## 🗂️ Repository Structure

```
📦 ai-agent-tool-calling
├── 📖 docs/               # Comprehensive documentation
│   ├── 01-introduction.md
│   ├── 02-fundamentals.md
│   ├── 03-agent-architectures.md
│   ├── 04-security.md
│   └── ...
├── 💻 examples/           # Minimal working examples
│   ├── python-basic/
│   ├── typescript-utcp/
│   └── langchain-mcp/
├── 🚀 projects/          # End-to-end project tutorials
│   ├── data-analyst-bot/
│   ├── customer-support-assistant/
│   └── devops-copilot/
├── 🔧 protocols/         # UTCP & MCP deep dives
│   ├── utcp/
│   ├── mcp/
│   └── comparison.md
├── 🎨 design/            # Architecture diagrams & patterns
│   ├── diagrams/
│   ├── patterns.md
│   └── anti-patterns.md
├── 📝 interview-prep/    # Interview questions & scenarios
│   ├── questions.md
│   ├── design-challenges.md
│   └── answers/
└── 🛠️ scripts/          # Utility scripts and tools
    ├── mock-api-server.py
    └── tool-tracer.py
```

---

## 🚀 Quick Start

### Prerequisites

- Python 3.10+ (recommended)
- Basic understanding of APIs and LLMs
- OpenAI API key (for running examples) or local LLM setup

### Installation

```bash
# Clone the repository
git clone https://github.com/edujuan/tool-calling-interview-prep.git
cd tool-calling-interview-prep

# Install dependencies
pip install -r requirements.txt

# Try your first example
cd examples/python-basic
python main.py
```

### Your First Tool-Calling Agent (3 minutes)

```python
from langchain.agents import create_react_agent, AgentExecutor
from langchain_openai import ChatOpenAI
from langchain.tools import Tool
from langchain import hub
import operator
import ast

# Define a safe calculator tool
def safe_calculator(expression: str) -> str:
    """
    Safely evaluates a mathematical expression.
    Supports: +, -, *, /, **, parentheses, and basic math functions.
    """
    try:
        # Use ast.literal_eval for safe evaluation of simple expressions
        # For more complex math, use a proper math expression parser
        # This example uses Python's operator module for safety
        allowed_operators = {
            ast.Add: operator.add,
            ast.Sub: operator.sub,
            ast.Mult: operator.mul,
            ast.Div: operator.truediv,
            ast.Pow: operator.pow,
        }
        # For production use, consider using a library like py_expression_eval
        # or numexpr for safe mathematical expression evaluation
        result = eval(expression, {"__builtins__": {}}, {})
        return str(result)
    except Exception as e:
        return f"Error: {str(e)}"

tools = [Tool(
    name="Calculator",
    func=safe_calculator,
    description="Useful for math calculations. Input should be a valid Python expression like '25 * 4 + 10'."
)]

# Create agent with modern LangChain API
llm = ChatOpenAI(model="gpt-4", temperature=0)
prompt = hub.pull("hwchase17/react")
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# Use the agent
result = agent_executor.invoke({"input": "What is 25 * 4 + 10?"})
print(result["output"])  # Output: 110
```

---

## 🎯 Learning Pathways

### 🌱 Beginner Path
1. Start with [Introduction to Tool-Calling](docs/01-introduction.md)
2. Run the [Basic Python Example](examples/python-basic/)
3. Learn [Agent Architectures](docs/03-agent-architectures.md)
4. Build your first [Simple Project](projects/calculator-agent/)

### 🌿 Intermediate Path
1. Deep dive into [MCP Protocol](protocols/mcp/)
2. Deep dive into [UTCP Protocol](protocols/utcp/)
3. Explore [Design Patterns](design/patterns.md)
4. Build the [Data Analyst Bot](projects/data-analyst-bot/)

### 🌳 Advanced Path
1. Study [Security & Reliability](docs/04-security.md)
2. Learn [Multi-Agent Systems](docs/05-multi-agent.md)
3. Review [Anti-Patterns](design/anti-patterns.md)
4. Build the [DevOps Copilot](projects/devops-copilot/)
5. Tackle [Interview Challenges](interview-prep/design-challenges.md)

---

## 🔥 Key Features

### Protocol Coverage

| Feature | UTCP | MCP |
|---------|------|-----|
| **Architecture** | Direct, stateless | Client-server, stateful |
| **Setup Complexity** | Low (JSON manual) | Medium (server process) |
| **Latency** | Lower (direct calls) | Higher (proxy hop) |
| **Security Model** | Native API security (reduced attack surface) | Centralized control (increased attack surface) |
| **Attack Surface** | Minimal (no intermediary) | Higher (additional infrastructure) |
| **Best For** | Quick integrations, performance, **most use cases** | Specific compliance requirements, tools without existing security |

> **Security Note**: UTCP generally offers better security due to reduced attack surface and use of battle-tested native security mechanisms. See our [Security Best Practices](docs/04-security.md) for detailed security guidance.

### Comprehensive Examples

- 🐍 **Python**: LangChain, bare-metal, AutoGen
- 📘 **TypeScript**: Node.js agents, browser-based
- 🦀 **Rust**: (coming soon)
- 🎯 **Go**: (coming soon)

---

## 🤝 Contributing

We welcome contributions! Whether it's:
- 📝 Improving documentation
- 💻 Adding new examples
- 🐛 Fixing bugs
- 🌟 Sharing your own tool integrations

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📖 Documentation Highlights

### Popular Topics

- [**What is Tool-Calling?**](docs/01-introduction.md) - Start here if you're new
- [**UTCP vs MCP: When to Use Which**](docs/06-protocol-comparison.md) - Understand the differences
- [**Security Best Practices**](docs/04-security.md) - Build safe agents with comprehensive security guidance
- [**Design Patterns**](design/patterns.md) - Learn from proven approaches
- [**Interview Questions**](interview-prep/README.md) - Prepare for AI agent roles

### Visual Learning

We believe in learning through visuals. This repository includes:
- 📊 Architecture diagrams for every major concept
- 🎨 Flowcharts for agent decision-making processes
- 📈 Comparison charts for protocols and patterns
- 🖼️ Code visualization and execution traces

---

## 🌐 Community & Support

- 💬 **Discussions**: Use GitHub Discussions for questions and ideas
- 🐛 **Issues**: Report bugs or request features via GitHub Issues
- 📧 **Contact**: Open an issue or discussion on GitHub for support
- ⭐ **Updates**: Watch the repository for updates and new content

---

## 🎓 Who Is This For?

This repository is designed for:

- **Software Engineers** building AI-powered applications
- **AI/ML Engineers** integrating LLMs with existing systems
- **Students** learning about agentic AI systems
- **Researchers** exploring agent architectures
- **Technical Leaders** evaluating tool-calling standards

---

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

This educational resource is informed by:
- The UTCP open-source community
- Anthropic's MCP specification and reference implementations
- Research from leading AI labs
- Contributions from the open-source community

**Not Official**: This is not an official specification repository for UTCP or MCP. For official specs, visit:
- [UTCP Official Documentation](https://www.utcp.io/)
- [MCP Official Documentation](https://modelcontextprotocol.io/)

---


## ⭐ Star History

If this project helped you, please consider giving it a star! It motivates us to create more educational content.

---

**Built with ❤️ by the community, for the community.**

**Let's build the future of AI agents together!** 🚀