{"id":51593303,"url":"https://github.com/leestott/agentframework--foundrylocal","last_synced_at":"2026-07-11T16:30:53.619Z","repository":{"id":338083650,"uuid":"1151395507","full_name":"leestott/agentframework--foundrylocal","owner":"leestott","description":"How Microsoft Agent Framework can orchestrate multiple specialised agents locally using Foundry Local How a coding agent can generate and execute a standalone Python application as part of an agent workflow How you can use tool calling with model which support tooling  How planner and reviewer agents can be composed","archived":false,"fork":false,"pushed_at":"2026-02-12T18:34:58.000Z","size":276,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-13T02:08:23.310Z","etag":null,"topics":["agent","agentframework","foundry-local","microsoft","microsoft-foundry","microsoftagentframework","slm","tooling"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leestott.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-06T12:14:29.000Z","updated_at":"2026-02-12T18:35:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/leestott/agentframework--foundrylocal","commit_stats":null,"previous_names":["leestott/agentframework--foundrylocal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/leestott/agentframework--foundrylocal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Fagentframework--foundrylocal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Fagentframework--foundrylocal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Fagentframework--foundrylocal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Fagentframework--foundrylocal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leestott","download_url":"https://codeload.github.com/leestott/agentframework--foundrylocal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leestott%2Fagentframework--foundrylocal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35368766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentframework","foundry-local","microsoft","microsoft-foundry","microsoftagentframework","slm","tooling"],"created_at":"2026-07-11T16:30:52.788Z","updated_at":"2026-07-11T16:30:53.610Z","avatar_url":"https://github.com/leestott.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Local Research \u0026 Synthesis Desk\n\n![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)\n![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-brightgreen.svg)\n![Foundry Local](https://img.shields.io/badge/Foundry_Local-on--device_AI-purple.svg)\n![MAF](https://img.shields.io/badge/Agent_Framework-multi--agent-orange.svg)\n\n**Multi-agent orchestration** demo using [Microsoft Agent Framework (MAF)](https://learn.microsoft.com/en-us/agent-framework/) and [Foundry Local](https://foundrylocal.ai) — everything runs on your machine, no cloud API keys needed.\n\n---\n\n## Quick Start (TL;DR)\n\n```bash\n# 1. Install Foundry Local → https://github.com/microsoft/Foundry-Local\n# 2. Set up Python\npython -m venv .venv \u0026\u0026 .venv\\Scripts\\activate\npip install -r requirements.txt\ncopy .env.example .env\n\n# 3. Run the demo\npython -m src.app \"What are the key features of Foundry Local?\" --docs ./data\n\n# 4. Launch the web UI\npython -m src.app.web\n```\n\n---\n\n## What You'll Learn\n\nThis demo teaches you how to:\n\n- **Bootstrap Foundry Local** from Python using `foundry-local-sdk`\n- **Create specialised agents** (Planner, Retriever, Critic, Writer) with MAF's `ChatAgent`\n- **Wire agents to a local LLM** via MAF's `OpenAIChatClient` (OpenAI-compatible API)\n- **Orchestrate agents sequentially** — a pipeline where each agent builds on the previous output\n- **Orchestrate agents concurrently** — fan-out independent tasks in parallel with `asyncio.gather`\n- **Implement a feedback loop** — the Critic loops back to the Retriever when it flags gaps, iterating until quality is sufficient\n- **Use function/tool calling** — let the LLM invoke Python functions (`word_count`, `extract_keywords`)\n- **Build a web UI** — a browser-based interface that streams agent progress in real time\n\n---\n\n## Screenshots\n\n### Desktop View — Research Workflow\n\n![Desktop Research Workflow](screenshots/desktop-workflow.png)\n\nThe main interface with the research workflow tab, showing the agent pipeline and input form.\n\n### Desktop View — Demos Tab\n\n![Desktop Demos](screenshots/desktop-demos.png)\n\nInteractive demos showcasing different MAF capabilities including weather tools, math calculator, sentiment analyzer, code reviewer, and multi-agent debate.\n\n### Desktop View — Tool Demo\n\n![Desktop Tool Demo](screenshots/desktop-tool-demo.png)\n\nThe tool calling demo showing word count and keyword extraction tools in action.\n\n### Mobile View\n\n![Mobile View](screenshots/mobile-view.png)\n\nResponsive design adapts to mobile screens with touch-friendly controls and optimized layout.\n\n---\n\n## What This Demo Does\n\nYou type a research question. Four AI agents collaborate locally to answer it:\n\n| Agent | Role |\n|-------|------|\n| **Planner** | Breaks your question into sub-tasks |\n| **Retriever** | Reads local files and extracts relevant snippets with citations |\n| **Critic** | Reviews for gaps and contradictions; loops back to Retriever if gaps are found |\n| **Writer** | Produces a final report citing your local documents |\n| **ToolAgent** *(optional)* | Computes word counts and keyword extraction |\n\nThe demo shows **three orchestration patterns** in a single run:\n\n1. **Sequential pipeline** — Planner runs first, then Retriever, Critic, Writer in order (each agent needs the previous agent's output).\n2. **Concurrent fan-out** — Retriever and ToolAgent run *in parallel* (they don't depend on each other), saving time.\n3. **Critic–Retriever feedback loop** — When the Critic finds gaps, it loops back to the Retriever for additional retrieval, then re-evaluates (up to 2 iterations).\n\n```\nUser question\n     │\n     ▼\n  Planner          ← sequential (must run first)\n     │\n     ├──► Retriever ┐\n     │               ├─► merge   ← concurrent (independent tasks)\n     └──► ToolAgent ┘\n              │\n              ▼\n           Critic          ← sequential (needs retriever output)\n              │\n         ┌────┴────┐\n         │ Gaps?   │\n         └────┬────┘\n          YES │ NO\n              │  └──────────┐\n              ▼             │\n        Retriever           │  ← feedback loop (fills gaps)\n         (gap-fill)         │\n              │             │\n              ▼             │\n           Critic           │  ← re-evaluate\n              │             │\n              ▼◄────────────┘\n           Writer          ← sequential (needs everything above)\n              │\n              ▼\n        Final Report\n```\n\n## Prerequisites\n\n| Requirement | Version | Link |\n|---|---|---|\n| Python | 3.10 or higher | [python.org](https://www.python.org/downloads/) |\n| Foundry Local | Latest | [github.com/microsoft/Foundry-Local](https://github.com/microsoft/Foundry-Local) |\n\n## Setup (5 minutes)\n\n### 1. Install Foundry Local\n\nFollow the instructions at [github.com/microsoft/Foundry-Local](https://github.com/microsoft/Foundry-Local) to install the Foundry Local runtime for your OS.\n\nVerify it works:\n\n```bash\nfoundry --help\n```\n\n### 2. Clone this repo and create a virtual environment\n\n```bash\ngit clone \u003cthis-repo-url\u003e\ncd agentframework-foundrylocal\n\npython -m venv .venv\n```\n\nActivate the environment:\n\n```bash\n# Windows\n.venv\\Scripts\\activate\n\n# macOS / Linux\nsource .venv/bin/activate\n```\n\n### 3. Install Python dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n### 4. Set up your configuration\n\n```bash\ncopy .env.example .env\n```\n\nThe default settings use the `qwen2.5-0.5b` model alias. Foundry Local automatically picks the best hardware variant (GPU, NPU, or CPU) for your machine.\n\n\u003e **Tip:** Run `foundry model list` to see all available model aliases. The `qwen2.5` family supports function/tool calling, which the ToolAgent needs. For better quality, try `--model qwen2.5-7b` or `--model qwen2.5-14b`.\n\n### 5. (Optional) Verify Foundry Local with a quick test\n\n```bash\nfoundry model run qwen2.5-0.5b\n```\n\nType a question, see a response, press Ctrl+C to exit.\n\n## Run the Demo\n\n```bash\npython -m src.app \"What are the key features of Foundry Local and how does it compare to cloud inference?\"\n```\n\nWith a custom documents folder:\n\n```bash\npython -m src.app \"Summarise the orchestration patterns\" --docs ./data\n```\n\nSequential-only mode (simpler pipeline, no parallel step):\n\n```bash\npython -m src.app \"Explain multi-agent benefits\" --docs ./data --mode sequential\n```\n\n### Launch the Web UI\n\nRun the browser-based interface for an interactive experience:\n\n```bash\npython -m src.app.web\n```\n\nOpen [http://localhost:5000](http://localhost:5000) in your browser. The web UI provides:\n\n- A text input for your research question\n- Real-time streaming of each agent's progress\n- Visual pipeline showing Sequential and Concurrent orchestration\n- Mode toggle (Full / Sequential)\n- Tool calling demo tab\n\n### Validate Tool/Function Calling\n\nRun the dedicated tool calling demo to verify function calling works:\n\n```bash\npython -m src.app.tool_demo\n```\n\nThis tests:\n- Direct tool function calls (word_count, extract_keywords)\n- LLM-driven tool calling via the ToolAgent\n- Multi-tool requests in a single prompt\n\n### CLI Options\n\n| Flag | Default | Description |\n|---|---|---|\n| `\"question\"` | *(required)* | Your research question |\n| `--docs` | `./data` | Folder of local documents to search |\n| `--model` | `qwen2.5-0.5b` | Foundry Local model alias |\n| `--mode` | `full` | `full` (sequential + concurrent) or `sequential` |\n| `--log-level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |\n\n## Project Structure\n\n```\n├── .env.example          # Config template\n├── pyproject.toml        # Project metadata \u0026 dependencies\n├── requirements.txt      # Pinned dependencies\n├── LICENSE               # MIT License\n├── CONTRIBUTING.md       # Contribution guidelines\n├── SECURITY.md           # Security policy\n├── data/                 # Sample documents for the Retriever\n│   ├── foundry_local_overview.md\n│   ├── agent_framework_guide.md\n│   └── orchestration_patterns.md\n├── src/app/\n│   ├── __init__.py\n│   ├── __main__.py       # CLI entry point\n│   ├── foundry_boot.py   # Foundry Local SDK bootstrapper\n│   ├── agents.py         # Agent definitions (Planner, Retriever, Critic, Writer, ToolAgent)\n│   ├── documents.py      # Local file loader with chunking\n│   ├── orchestrator.py   # Sequential + Concurrent + Feedback loop orchestration engine\n│   ├── tool_demo.py      # Tool/function calling validation demo\n│   ├── web.py            # Flask web UI (browser-based interface)\n│   ├── templates/\n│   │   └── index.html    # Web UI frontend (HTML + CSS + JS)\n│   └── demos/            # Interactive tool calling demos\n│       ├── __init__.py\n│       ├── registry.py       # Demo registry with metadata\n│       ├── weather_tools.py  # Weather info with 4 tools\n│       ├── math_agent.py     # Calculator with 6 math tools\n│       ├── sentiment_analyzer.py  # Text analysis with 5 tools\n│       ├── code_reviewer.py  # Code analysis with 5 tools\n│       └── multi_agent_debate.py  # 3-agent debate system\n└── tests/\n    └── test_smoke.py     # Smoke tests (no GPU/service required)\n```\n\n## How It Works — Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    Your Machine                          │\n│                                                          │\n│  ┌──────────────┐    Control Plane     ┌──────────────┐ │\n│  │  Python App   │───(foundry-local-sdk)──►│Foundry Local │ │\n│  │  (MAF agents) │                     │   Service     │ │\n│  │               │    Data Plane       │              │ │\n│  │  OpenAIChatClient──(OpenAI API)────►│  Model (LLM) │ │\n│  └──────────────┘                     └──────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n**Control plane** — The `FoundryLocalManager` from `foundry-local-sdk` starts the service, downloads models, and returns the endpoint URL. ([SDK reference](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/reference/reference-sdk?view=foundry-classic))\n\n**Data plane** — MAF's `OpenAIChatClient` sends chat completions to Foundry Local's OpenAI-compatible API (typically `http://localhost:\u003cport\u003e/v1` — the port is assigned dynamically). No separate OpenAI key is needed.\n\n**Feedback loop** — The Critic agent is instructed to output `GAPS FOUND` or `NO GAPS` at the start of its response. When gaps are detected, the orchestrator sends them back to the Retriever with the original documents, merges the new snippets, and re-runs the Critic. This iterates up to 2 times before the Writer takes over, ensuring higher quality reports.\n\n## Example Output\n\nWhen you run the demo, you'll see agent-by-agent progress in the terminal:\n\n```\n┌─ Local Research \u0026 Synthesis Desk ─┐\n│ Multi-Agent Orchestration • MAF + Foundry Local │\n│ Mode: full                                       │\n└──────────────────────────────────────────────────┘\n\n  Model : qwen2.5-0.5b-instruct-cuda-gpu:4  (alias: qwen2.5-0.5b)\n  Documents: 3 file(s), 4 chunk(s) from ./data\n\n┌─────────────────────────────────────────┐\n│ 🗂  Planner — breaking the question …   │\n└─────────────────────────────────────────┘\n  1. Identify key features of Foundry Local …\n  2. Compare on-device vs cloud inference …\n  ⏱  2.3s\n\n⚡ Concurrent fan-out — Retriever + ToolAgent running in parallel …\n  Retriever finished in 3.1s\n  ToolAgent finished in 1.4s\n\n┌─────────────────────────────────────────┐\n│ ✍️  Writer — composing the final report │\n└─────────────────────────────────────────┘\n  (Final synthesised report with citations)\n  ⏱  4.2s\n\n✅ Workflow complete — Total: 14.8s, Steps: 5\n```\n\n## Run Tests\n\n```bash\npip install pytest pytest-asyncio\npytest tests/ -v\n```\n\nThe smoke tests check document loading, tool functions, and configuration — they do **not** require a running Foundry Local service.\n\n---\n\n## Interactive Demos\n\nThe web UI includes a **Demos** tab with 5 interactive demos showcasing different MAF capabilities. Each demo has a suggested prompt you can use directly.\n\n| Demo | Category | Description | Suggested Prompt |\n|------|----------|-------------|------------------|\n| **🌤️ Weather Tools** | Tool Calling | Multi-tool agent providing weather info, forecasts, city comparisons, and activity recommendations. Uses 4 different tools. | `What's the weather in Seattle and San Francisco? Compare them and recommend activities for the warmer city.` |\n| **🔢 Math Calculator** | Tool Calling | Precise calculation agent with tools for arithmetic, percentages, unit conversions, compound interest, and statistics. Uses tools instead of mental math for accuracy. | `If I invest $10,000 at 7% annual interest compounded monthly for 15 years, how much will I have? Also convert that to euros assuming 1 USD = 0.92 EUR.` |\n| **💬 Sentiment Analyzer** | Tool Calling | Text analysis agent that detects sentiment, emotions, key phrases, and word frequency. Uses lexicon-based tools for structured analysis. | `Analyze this review: 'The product arrived quickly and the quality exceeded my expectations. However, the packaging was disappointing and customer support was slow to respond.'` |\n| **👨‍💻 Code Reviewer** | Tool Calling | Code analysis agent that checks style, complexity, potential bugs, and suggests improvements. Useful for quick code reviews. | `Review this Python code: def calc(x,y,z): result = x + y; if result == None: return 0; return result / z` |\n| **🎭 Multi-Agent Debate** | Multi-Agent | Three agents debate a topic: one argues FOR, one argues AGAINST, and a moderator declares a winner. Showcases sequential orchestration with interdependent outputs. | `Remote work should become the default for all knowledge workers` |\n\n### Demo Features\n\n- **Tool Calling Demos**: Show how MAF agents invoke Python functions decorated with Pydantic metadata\n- **Multi-Agent Demo**: Demonstrates sequential orchestration where agents receive output from previous agents\n- **Suggested Prompts**: Click \"Use This\" to copy the suggested prompt directly into the input field\n- **Real-time Results**: See agent outputs streamed as they complete\n\nAccess demos at: [http://localhost:5000](http://localhost:5000) → **Demos** tab\n\n---\n\n## Troubleshooting\n\n| Problem | Solution |\n|---|---|\n| `foundry: command not found` | Install Foundry Local: [github.com/microsoft/Foundry-Local](https://github.com/microsoft/Foundry-Local) |\n| `foundry-local-sdk is not installed` | Run `pip install foundry-local-sdk` |\n| Model download is slow | First download can be large. It's cached for future runs. |\n| `No documents found` warning | Add `.txt` or `.md` files to the `--docs` folder |\n| Agent output is low quality | Try a larger model alias, e.g. `--model phi-3.5-mini` |\n| Web UI won't start | Ensure Flask is installed: `pip install flask` |\n| Port 5000 in use | The web UI uses port 5000. Stop other services or set `PORT=8080` env var |\n\n## References\n\n- **Foundry Local**: [foundrylocal.ai](https://foundrylocal.ai)\n- **Foundry Local SDK (Python)**: [Microsoft Learn](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/reference/reference-sdk?view=foundry-classic)\n- **Foundry Local repo**: [github.com/microsoft/Foundry-Local](https://github.com/microsoft/Foundry-Local)\n- **Foundry Local CLI reference**: [Microsoft Learn](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/reference/reference-cli?view=foundry-classic)\n- **Microsoft Agent Framework**: [learn.microsoft.com/en-us/agent-framework](https://learn.microsoft.com/en-us/agent-framework/)\n- **Agent Framework core (PyPI)**: [pypi.org/project/agent-framework-core](https://pypi.org/project/agent-framework-core/)\n- **Agent Framework Samples**: [github.com/microsoft/Agent-Framework-Samples](https://github.com/microsoft/Agent-Framework-Samples)\n- **MAF Orchestrations overview**: [Microsoft Learn](https://learn.microsoft.com/en-us/agent-framework/user-guide/workflows/orchestrations/overview)\n\n## License\n\nThis project is licensed under the MIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleestott%2Fagentframework--foundrylocal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleestott%2Fagentframework--foundrylocal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleestott%2Fagentframework--foundrylocal/lists"}