{"id":27966512,"url":"https://github.com/elijas/baml-agents","last_synced_at":"2025-05-07T20:19:12.964Z","repository":{"id":288641679,"uuid":"968767305","full_name":"Elijas/baml-agents","owner":"Elijas","description":"Building Agents with LLM structured generation (BAML), MCP Tools, and 12-Factor Agents principles","archived":false,"fork":false,"pushed_at":"2025-05-07T09:02:25.000Z","size":536,"stargazers_count":8,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-07T20:19:09.706Z","etag":null,"topics":["12-factor","12-factor-agents","ai","ai-agents","ai-agents-framework","baml","context-window","framework","llms","mcp-client","memory","orchestration","rag","structured-generation"],"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/Elijas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-18T17:37:04.000Z","updated_at":"2025-05-07T09:02:29.000Z","dependencies_parsed_at":"2025-04-19T06:36:34.861Z","dependency_job_id":"eff3fe05-cb75-4e17-a418-0ca753b41474","html_url":"https://github.com/Elijas/baml-agents","commit_stats":null,"previous_names":["elijas/baml-agents"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fbaml-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fbaml-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fbaml-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Elijas%2Fbaml-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Elijas","download_url":"https://codeload.github.com/Elijas/baml-agents/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252949325,"owners_count":21830175,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["12-factor","12-factor-agents","ai","ai-agents","ai-agents-framework","baml","context-window","framework","llms","mcp-client","memory","orchestration","rag","structured-generation"],"created_at":"2025-05-07T20:19:12.502Z","updated_at":"2025-05-07T20:19:12.950Z","avatar_url":"https://github.com/Elijas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# baml‑agents\n\n[![Status: Experimental](https://img.shields.io/badge/status-experimental-gold.svg?style=flat)](https://github.com/mkenney/software-guides/blob/master/STABILITY-BADGES.md#experimental)\n[![Maintained: yes](https://img.shields.io/badge/yes-43cd0f.svg?style=flat\u0026label=maintained)](https://github.com/Elijas/baml-agents/issues)\n[![License: MIT](https://img.shields.io/badge/License-MIT-43cd0f.svg?style=flat\u0026label=license)](LICENSE)\n[![PyPI Version](https://img.shields.io/badge/v0.30.0-version?color=43cd0f\u0026style=flat\u0026label=pypi)](https://pypi.org/project/baml-agents)\n[![PyPI Downloads](https://img.shields.io/pypi/dm/baml-agents?color=43cd0f\u0026style=flat\u0026label=downloads)](https://pypistats.org/packages/baml-agents)\n[![Linter: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n**Building Agents with LLM structured generation ([BAML](https://www.boundaryml.com/)), [MCP Tools](https://modelcontextprotocol.io/docs/concepts/tools), and [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) principles**\n\nThis repository shares useful patterns I use when working with BAML. Note: The API may unexpectedly change with future minor versions; therefore, install with specific version constraints:\n\n```bash\npip install \"baml-agents\u003e=0.30.0,\u003c0.31.0\"\n```\n\nFound this useful? Star the repo on GitHub to show support and follow for updates. Also, find me on Discord if you have questions or would like to join a discussion!\n\n![GitHub Repo stars](https://img.shields.io/github/stars/elijas/baml-agents?style=flat\u0026color=f0f0f0\u0026labelColor=white\u0026logo=github\u0026logoColor=black)\n\u0026nbsp;\u003ca href=\"https://discord.gg/hCppPqm6\"\u003e\u003cimg alt=\"Discord server invite\" src=\"https://img.shields.io/discord/1119368998161752075?logo=discord\u0026logoColor=white\u0026style=flat\u0026color=f0f0f0\u0026labelColor=7289da\" height=\"20\"\u003e\u003c/a\u003e\n\n## Disclaimer\n\nThis project is maintained independently by Elijas and is not affiliated with the official BAML project.\n\n## Repository Structure\n\n*   `/notebooks`: **Core Tutorials \u0026 Examples.** Contains curated Jupyter notebooks demonstrating key features and recommended patterns. Start here to learn `baml-agents`.\n*   `/explorations`: **Experimental \u0026 Niche Content.** Holds prototypes, tests, and examples for specific or advanced use cases. Content may be less polished or stable. See the [explorations README](./explorations/README.md).\n*   `/baml_agents/devtools`: **Developer Utilities.** Contains helper scripts for project maintenance, development workflows, and automating tasks (e.g., updating baml generator versions). See the [devtools README](./baml_agents/devtools/README.md).\n\n## Contents (Core Tutorials)\n\nThe primary tutorials are located in the `/notebooks` directory:\n\n1.  [Flexible LLM Client Management in BAML](notebooks/01_baml_llm_client_config.ipynb)\n    - Effortlessly switch between different LLM providers (like OpenAI, Anthropic, Google) at runtime using simple helper functions.\n    - Bridge compatibility gaps: Connect to unsupported LLM backends or tracing systems (e.g., Langfuse, LangSmith) via standard proxy setups.\n    - Solve common configuration issues: Learn alternatives for managing API keys and client settings if environment variables aren't suitable.\n2.  [Introduction to AI Tool Use with BAML](notebooks/02_baml_custom_tools.ipynb)\n    - Learn how to define custom actions (tools) for your AI using Pydantic models, making your agents capable of _doing_ things.\n    - See how to integrate these tools with BAML manually or dynamically using `ActionRunner` for flexible structured outputs.\n    - Understand how BAML translates goals into structured LLM calls that select and utilize the appropriate tool.\n3.  [Integrating Standardized MCP Tools with BAML](notebooks/03_baml_with_mcp_tools.ipynb)\n    - Discover how to leverage the Model Context Protocol (MCP) to easily plug-and-play pre-built 3rd party tools (like calculators, web search) into your BAML agents.\n    - See `ActionRunner` in action, automatically discovering and integrating tools from MCP servers with minimal configuration.\n    - Learn techniques to filter and select specific MCP tools to offer to the LLM, controlling the agent's capabilities precisely.\n4.  [Interactive BAML Development in Jupyter](notebooks/04_interactive_baml_jupyter.ipynb)\n    - See BAML's structured data generation stream _live_ into your Jupyter output cell as the LLM generates it.\n    - Interactively inspect the details: Use collapsible sections to view full LLM prompts and responses, optionally grouped by call or session, directly in the notebook.\n    - Chat with your agent: Interactive chat widget right in the notebook, allowing you to chat with your agent in real-time.\n5.  [Simple Agent Demonstration](notebooks/05_simple_agent_demo.ipynb)\n    - Putting it all together: Build a simple, functional agent capable of tackling a multi-step task.\n    - Learn how to combine custom Python actions (defined as `Action` classes) with standardized MCP tools (like calculators or time servers) managed by `ActionRunner`.\n    - Follow the agent's decision-making loop driven by BAML's structured output generation (`GetNextAction`), see it execute tools, and observe how it uses the results to progress.\n    - Includes demonstration of `JupyterBamlMonitor` for transparent inspection of the underlying LLM interactions.\n\n## Simple example\n\n\u003e [!TIP]\n\u003e The code below is trimmed for brevity to **illustrate the core concepts**. Some function names or setup steps may differ slightly from the full notebook implementation for clarity in this example. The full, runnable code is available in the notebook \u003ca href=\"notebooks/05_simple_agent_demo.ipynb\"\u003eSimple Agent Demonstration (notebooks/05_simple_agent_demo.ipynb)\u003c/a\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eShow code for the example below\u003c/summary\u003e\n\n```python\ndef get_weather_info(city: str):\n    return f\"The weather in {city} is 63 degrees fahrenheit with cloudy conditions.\"\n\ndef stop_execution(final_answer: str):\n    return f\"Final answer: {final_answer}\"\n\nr = ActionRunner() # Doing an action means using a tool\n\n# Adding a tool to allow the agent to do math\nr.add_from_mcp_server(server=\"uvx mcp-server-calculator\")\n\n# Adding a tool to get the current time\nr.add_from_mcp_server(server=\"uvx mcp-timeserver\")  # Note: you can also add URLs\n\n# Adding a tool to get the current weather\nr.add_action(get_weather_info)\n\n# Adding a tool to let the agent stop execution\nr.add_action(stop_execution)\n\nasync def execute_task(llm, task: str) -\u003e str:\n    interactions = []\n    while True:\n        action = await llm.GetNextAction(task, interactions)\n        if result := is_result_available(action):\n            return result\n\n        result = r.run(action)\n        interactions.append(new_interaction(action, result))\n\nllm = LLMClient(\"gpt-4.1-nano\")\ntask = r.execute_task(llm, \"State the current date along with avg temp between LA, NY, and Chicago in Fahrenheit.\")\n```\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n![BAML Agent execution trace in Jupyter showing LLM prompts and completions](https://github.com/user-attachments/assets/ea55c3e7-147d-41aa-99ce-40e4783f7818)\n\nTo try it yourself, check out the notebook [Simple Agent Demonstration (notebooks/05_simple_agent_demo.ipynb)](notebooks/05_simple_agent_demo.ipynb).\n\n## Running the Notebooks\n\nTo run code from the `notebooks/` folder, you'll first need to:\n\n- Install the [`uv` python package manager](https://docs.astral.sh/uv/).\n- Install all dependencies: `uv sync --dev`\n- Generate necessary BAML code: `uv run baml-cli generate`\n  - Alternatively, you can use the [VSCode extension](https://marketplace.visualstudio.com/items?itemName=Boundary.baml-extension) to do it automatically every time you edit a `.baml` file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijas%2Fbaml-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felijas%2Fbaml-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felijas%2Fbaml-agents/lists"}