AGENTS.md

ArkAssistant - Hugging Face Agents Course Project

This workspace contains the complete implementation for the Hugging Face Agents Course (Unit 1 & Unit 2) project, featuring a Hierarchical Multi-Agent System built with smolagents.

System Architecture

• ArkAssistant_Manager (app.py): Top-level orchestrator agent that parses complex user inquiries and coordinates specialist sub-agents.
  • web_researcher (research_agent): Specialist agent equipped with web_search, search_wikipedia, and visit_webpage for deep web querying and documentation browsing.
  • local_info_specialist (local_info_agent): Specialist agent equipped with get_weather and get_current_time_in_timezone.
  • final_answer & image_generation_tool: Direct manager tools to conclude inquiries or generate visual images.

Project Structure

• app.py: Main entry point and multi-agent pipeline with Gradio UI.
• test_agent.py: Fast CLI test runner for direct queries and tool verification without launching a browser.
• Gradio_UI.py: Gradio interface with ZeroGPU compatibility and step-by-step agent visualization.
• prompts.yaml: System prompts and agent templates.
• requirements.txt: Package dependencies for the agent and Hugging Face Space.
• README.md: Space card metadata for Gradio on Hugging Face Spaces.
• deploy_space.py: Automated deploy script to upload the workspace to Ark4u/First_agent_template on Hugging Face.
• tools/: Modular tools:
  • web_search.py: DuckDuckGo web search.
  • visit_webpage.py: Webpage scraper and markdown converter (VisitWebpageTool).
  • search_wikipedia.py: Wikipedia REST API lookups.
  • get_weather.py: Live weather via wttr.in.
  • get_current_time_in_timezone.py: IANA timezone local time converter.
  • final_answer.py: Final response delivery tool.

Environment & Commands

Cloud inference only. HF_TOKEN and MODEL_ID are configured in .env; local Ollama execution is intentionally disabled. Hugging Face Inference Providers require available credits or a PRO plan; without them the API returns HTTP 402 before the agent can start.

• Create the project virtual environment:

  uv venv .venv
  uv pip install --python .venv/bin/python -r requirements.txt
  

• Sanity Check All Tools (Fast, No LLM):

  .venv/bin/python test_agent.py --test-tools
  

• Run CLI Agent Query:

  .venv/bin/python test_agent.py "What is the capital of Japan and what is the weather there?"
  

• Run Gradio Web UI Locally:

  .venv/bin/python app.py
  

• Deploy to Hugging Face Spaces:

  .venv/bin/python deploy_space.py