Agentmaker

agentmaker

[](https://github.com/xinhuangcs/agentmaker/actions/workflows/ci.yml) [](https://pypi.org/project/agentmaker/) [](https://pypi.org/project/agentmaker/) [](https://github.com/xinhuangcs/agentmaker/blob/main/LICENSE) [](https://xinhuangcs.github.io/agentmaker/)

A general-purpose Python framework for building LLM agents and multi-agent systems, with tools, memory, retrieval / RAG, context engineering, guardrails, human-in-the-loop, and observability built in. Async-first, fully typed, and easy to debug: a built-in LLM debugger pinpoints a failed run's first bad step, root cause, and fix.

📖 Documentation: English Version · 中文版

Highlights

• One agent, many recipes: a single agent loop for chat and tool use, plus plan-and-execute and reflection workflows, declarative agent specs, and multi-agent orchestration.
• Any LLM provider: native OpenAI, Anthropic, and Gemini, plus DeepSeek, Moonshot, Zhipu, local models (Ollama, vLLM, SGLang), and any OpenAI-compatible endpoint, with function calling, streaming, structured output, multimodal, and prompt caching.
• Tools: turn any typed function into a tool with a one-line decorator, use the built-in tools, connect MCP servers, and auto-select the relevant tools at runtime when there are many.
• Retrieval, RAG, memory: hybrid retrieval (vectors, keywords, and rank fusion) with no external services, a full RAG pipeline with source citations, and long-term memory that extracts and updates facts.
• Batteries included, every backend swappable: local SQLite defaults with no database to run, and every backend (embeddings, vector store, reranker, session and checkpoint stores, trace exporter, chunker) sits behind an interface you can swap, for example to pgvector.
• Context engineering: assembles each prompt under an explicit token budget, with history compaction, relevance-based selection, and pluggable token counting.
• Guardrails & human-in-the-loop: input and output guardrails, an approve-before-run gate for high-risk tools, lifecycle hooks, searchable sessions, checkpoints, run limits, and cancellation.
• Observability & Trace Detective: trace every run to JSONL, SQLite, or OpenTelemetry, then have a built-in LLM debugger pinpoint a failed run's first bad step, root cause, and fix, in your terminal or a local web UI.
• Overridable prompts: list and replace any built-in prompt; English defaults with a Chinese language pack.
• Multi-tenant: a single scope label isolates retrieval, memory, and sessions across users, agents, and apps.
• Test-friendly: a built-in LLM test double runs your agents in CI with no API key and no network.

Installation

pip install agentmaker            # core batteries, works out of the box
pip install "agentmaker[all]"     # every optional extra below

Requires Python 3.12+. The core install already covers multi-provider LLM calls, structured output, tool-argument validation, and local hybrid retrieval (vectors plus CJK-aware keyword search). The optional extras below add the rest:

| Extra | Adds | |---|---| | anthropic | Anthropic native protocol adapter | | gemini | Google Gemini native protocol adapter | | search | SearchTool backends: DuckDuckGo (no key needed), Tavily, Brave, SerpAPI | | rag | Document loading for RAG: PDF / DOCX / HTML to Markdown | | rerank | Cohere multilingual reranker | | mcp | MCP (Model Context Protocol) tool integration | | otel | OpenTelemetry trace export | | devtools | Trace Detective: local web UI for diagnosing agent runs |

Quickstart

Define a tool, hand it to an agent, and the model calls it when it needs to:

from agentmaker import Agent, LLMClient, tool

@tool
def get_weather(city: str) -> str:
    """Return today's weather for a city.

    Args:
        city: The city name.
    """
    return f"{city}: sunny, 24C"

agent = Agent("assistant", LLMClient("deepseek"), tools=[get_weather])
print(agent.run("What's the weather in Copenhagen?").final_output)

Mount more capabilities

Every capability is a few more arguments to the same constructor. Here is that agent given semantic long-term memory, a model-invoked skill library, retrieved context, and an input guardrail:

from agentmaker import (Agent, LLMClient, Memory, MemoryStore, ContextBuilder, CallableSource, SkillLoader, CallableGuardrail)
from agentmaker.retrieval import build_sqlite_hybrid, OpenAIEmbedder

llm = LLMClient("openai")
memory = Memory(build_sqlite_hybrid(OpenAIEmbedder()), MemoryStore())
skills = SkillLoader("./skills")

agent = Agent(
    "assistant", llm,
    tools=[get_weather],  # function calling
    sources=[CallableSource("memory", memory.search)],  # memory pulled into context each turn
    context_builder=ContextBuilder(),  # assemble context under a token budget
    system_prompt=f"You are a helpful assistant.\nSkills:\n{skills.catalog()}",  # model-invoked skills
    input_guardrails=[CallableGuardrail(lambda t: len(t) =0.1,<0.2`.

## License

[MIT](https://github.com/xinhuangcs/agentmaker/blob/main/LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xinhuangcs](https://github.com/xinhuangcs)
- **Source:** [xinhuangcs/agentmaker](https://github.com/xinhuangcs/agentmaker)
- **License:** MIT
- **Homepage:** https://agentmaker.xinhuang.me/

Install and usage instructions live in the source repository linked above.