README.md

metadata

title: First Agent Template
emoji: ⚡
colorFrom: pink
colorTo: yellow
sdk: gradio
sdk_version: 5.23.1
app_file: app.py
pinned: false
tags:
  - smolagents
  - agent
  - smolagent
  - tool
  - agent-course

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

🤖 First Agent Project

Welcome to the First Agent Project — an elegant and modular AI agent system powered by SmolAgents, capable of solving complex tasks using structured reasoning, tool use, and code execution. Designed with usability and extensibility in mind, this project features a dynamic Gradio-based interface, plug-and-play tools, and a powerful HuggingFace model backend.

---

✨ Features

• 🔁 Multi-Step Reasoning with an agent that can plan, execute code, and invoke tools.
• 🌐 Web Search Tool via DuckDuckGo for live queries.
• 🧭 Webpage Reader Tool to fetch and parse web pages in Markdown.
• 📅 Time and Weather Tools for real-time timezone and temperature queries.
• 🖼️ Image Generation support using HuggingFace tool hub.
• 🎯 Gradio UI Integration with step-wise conversational tracing.
• 📦 Modular structure — easily extensible with custom tools.

---

🧠 Project Structure

.
├── app.py                  # Main entrypoint - defines tools, loads agent, and launches Gradio UI
├── Gradio_UI.py           # Elegant multi-step UI for interaction using Gradio
├── tools/final_answer.py        # Defines a final answer tool to conclude tasks
├── tools/visit_webpage.py       # Tool to visit a URL and extract readable markdown content
├── tools/web_search.py          # Tool for DuckDuckGo web search queries
├── requirements.txt       # Python dependencies
├── agent.json             # Agent configuration (tools, model, prompts, rules)

---

🧰 Built-in Tools

Tool Name	Description
web_search	Search the web using DuckDuckGo
visit_webpage	Visit and parse the content of a webpage as markdown
get_temperature	Get real-time temperature of a given city
get_current_time_in_timezone	Get local time in a specified timezone
final_answer	Returns the final response to a task
text-to-image	Generates images using HuggingFace image generation API (remote tool)

---

🚀 Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Run the App

python app.py

This will launch a Gradio interface where you can interact with your agent conversationally.

---

🌈 Sample Tasks

Try asking the agent:

• "What is the current temperature in Tokyo?"
• "Find the age of the Pope and raise it to the power of 0.36"
• "Search for latest news on Mars exploration"
• "Generate an image of a futuristic AI-powered city"
• "What’s the current time in New York?"

---

🛠️ Under the Hood

🧠 Agent Model

• Powered by Qwen/Qwen2.5-Coder-32B-Instruct
• HuggingFace API wrapper (HfApiModel) with streaming and code execution.

💬 Prompt Planning Logic

• Configured in agent.json with step-by-step templates, planning logic, and reasoning strategy.
• Structured prompt system encourages:
  • Thought → Code → Observation → Final Answer loops

---

🖼️ UI Highlights

• 💬 Chat-based interface with message tracking
• ⚙️ Shows tool usage logs, execution reasoning, and token statistics
• 📁 Supports file uploads (PDF, DOCX, TXT)
• 🧵 Maintains step context and memory

---

🔧 Customize or Extend

Adding Your Own Tool

You can add custom tools easily by subclassing Tool. Example:

from smolagents.tools import Tool

class MyTool(Tool):
    name = "my_tool"
    description = "Describe what your tool does here."
    inputs = {'input1': {'type': 'string', 'description': 'Your input'}}
    output_type = "string"

    def forward(self, input1: str) -> str:
        # Your logic
        return "Output result"

Then add it in app.py to the agent's tools list.

---

📜 License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

---

🌟 Acknowledgements

Built using:

• 🤖 SmolAgents
• 🌐 DuckDuckGo Search
• 🧾 Markdownify
• 🔥 Gradio
• 🧠 Qwen Model on HuggingFace