Building Agents with LLM structured generation (BAML), MCP Tools, and 12-Factor Agents principles
Project description
baml‑agents
Building Agents with LLM structured generation (BAML), MCP Tools, and 12-Factor Agents principles
This repository shares useful patterns I use when working with BAML. Note: the API may unexpectedly change with future minor versions, threfore install with:
pip install "baml-agents>=0.22.0,<0.23.0"
Found 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!
Disclaimer
This project is maintained independently by Elijas and is not affiliated with the official BAML project.
Contents
- Flexible LLM Client Management in BAML
- Effortlessly switch between different LLM providers (like OpenAI, Anthropic, Google) at runtime using simple helper functions.
- Bridge compatibility gaps: Connect to unsupported LLM backends or tracing systems (e.g., Langfuse, LangSmith) via standard proxy setups.
- Solve common configuration issues: Learn alternatives for managing API keys and client settings if environment variables aren't suitable.
- Introduction to AI Tool Use with BAML
- Learn how to define custom actions (tools) for your AI using Pydantic models, making your agents capable of doing things.
- See how to integrate these tools with BAML manually or dynamically using
ActionRunnerfor flexible structured outputs. - Understand how BAML translates goals into structured LLM calls that select and utilize the appropriate tool.
- Integrating Standardized MCP Tools with BAML
- 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.
- See
ActionRunnerin action, automatically discovering and integrating tools from MCP servers with minimal configuration. - Learn techniques to filter and select specific MCP tools to offer to the LLM, controlling the agent's capabilities precisely.
- Interactive BAML Development in Jupyter
- See BAML's structured data generation stream live into your Jupyter output cell as the LLM generates it.
- Interactively inspect the details: Use collapsible sections to view full LLM prompts and responses, optionally grouped by call or session, directly in the notebook.
- Chat with your agent: Interactive chat widget right in the notebook, allowing you to chat with your agent in real-time.
- Simple Agent Demonstration
- Putting it all together: Build a simple, functional agent capable of tackling a multi-step task.
- Learn how to combine custom Python actions (defined as
Actionclasses) with standardized MCP tools (like calculators or time servers) managed byActionRunner. - 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. - Includes demonstration of
JupyterBamlMonitorfor transparent inspection of the underlying LLM interactions.
Simple example
[!TIP] 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 Simple Agent Demonstration (notebooks/05_simple_agent_demo.ipynb)
Show code for the example below
def get_weather_info(city: str):
return f"The weather in {city} is 63 degrees fahrenheit with cloudy conditions."
def stop_execution(final_answer: str):
return f"Final answer: {final_answer}"
r = ActionRunner() # Doing an action means using a tool
# Adding a tool to allow the agent to do math
r.add_from_mcp_server(server="uvx mcp-server-calculator")
# Adding a tool to get the current time
r.add_from_mcp_server(server="uvx mcp-timeserver") # Note: you can also add URLs
# Adding a tool to get the current weather
r.add_action(get_weather_info)
# Adding a tool to let the agent stop execution
r.add_action(stop_execution)
async def execute_task(llm, task: str) -> str:
interactions = []
while True:
action = await llm.GetNextAction(task, interactions)
if result := is_result_available(action):
return result
result = r.run(action)
interactions.append(new_interaction(action, result))
llm = LLMClient("gpt-4.1-nano")
task = r.execute_task(llm, "State the current date along with avg temp between LA, NY, and Chicago in Fahrenheit.")
To try it yourself, check out the notebook Simple Agent Demonstration (notebooks/05_simple_agent_demo.ipynb).
Running the Notebooks
To run code from the notebooks/ folder, you'll first need to:
- Install the
uvpython package manager. - Install all dependencies:
uv sync --dev - Generate necessary BAML code:
uv run baml-cli generate- Alternatively, you can use the VSCode extension to do it automatically every time you edit a
.bamlfile.
- Alternatively, you can use the VSCode extension to do it automatically every time you edit a
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file baml_agents-0.22.0.tar.gz.
File metadata
- Download URL: baml_agents-0.22.0.tar.gz
- Upload date:
- Size: 46.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.6.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e3d0a8658f62b06c113a138facf29e11c642ca987ead791df7e32007c8c79203
|
|
| MD5 |
0e862e87314a85150c56ac933adb33fa
|
|
| BLAKE2b-256 |
05bed3b98aafbd7787ecc58f8a770868a7a8e6e1395e057f0d8a2946dfefc393
|
File details
Details for the file baml_agents-0.22.0-py3-none-any.whl.
File metadata
- Download URL: baml_agents-0.22.0-py3-none-any.whl
- Upload date:
- Size: 58.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: uv/0.6.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
15f8f077f1fd747c1d481c3ca49b8c2eabca777c26478ad729da673144ee6948
|
|
| MD5 |
8f2acc50ba6ebb790eac463c5d96ff14
|
|
| BLAKE2b-256 |
6ec26ad573631a199a4a40195113918f356e7d538d97a016c9cbfd5839017b21
|
