agentmaker - GitLite

KO | EN

gitlite — search

#ai #typescript #golang #android #rust #linux #docker #java #awesome #cli #kubernetes #vue #ios #open-source

agentmaker

(★ 123)

A general-purpose Python framework for building LLM agents and multi-agent systems. "Four lines of code, an agent with memory."

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - docs.yml
  - release.yml
- dependabot.yml
- - logo.svg
  - readme-docs-en-button.svg
  - readme-docs-zh-button.svg
  - readme-website-button.svg
- - index.md
  - installation.md
- - extra.js
- - extra.css
- - index.md
  - installation.md
- 01_quickstart.py
- 02_tools_and_registry.py
- 03_structured_output.py
- 04_memory.py
- 05_rag.py
- 06_workflows.py
- 07_guardrails_and_hitl.py
- 08_prompt_packs.py
- 09_async.py
- 10_scope_isolation.py
- 11_multi_agent.py
- 12_sessions.py
- 13_observability.py
- 14_run_policy.py
- 15_declarative_spec.py
- 16_skills.py
- - alternate.html
- main.html
- check_docs_links.py
- check_imports.py
- - __init__.py
  - config.py
  - py.typed
  - testing.py
- conftest.py
- test_abc_improvements.py
- test_agents.py
- test_aio.py
- test_async_seams.py
- test_cli_hardening.py
- test_config.py
- test_context.py
- test_core.py
- test_devtools.py
- test_from_config.py
- test_mcp_integration.py
- test_memory.py
- test_message.py
- test_multimodal.py
- test_notes_integration.py
- test_observability.py
- test_profiles.py
- test_prompts.py
- test_public_api.py
- test_rag.py
- test_rag_loader_extras.py
- test_retrieval.py
- test_run_policy.py
- test_runtime.py
- test_security.py
- test_skills.py
- test_storage_schema.py
- test_streaming_tool_loop.py
- test_testing.py
- test_tool_decorator.py
- test_tool_emulation.py
.gitignore
.python-version
CHANGELOG.md
LICENSE
mkdocs.yml
pyproject.toml
README.md
uv.lock

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/xinhuangcs/agentmaker

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd agentmaker

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. 공식 설치 스크립트

쉬움 추천

사전 준비물

Python 3 pip 명령어를 쓰려면 Python이 필요합니다.

pip install agentmaker

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

pip install "agentmaker[all]" # every optional extra below

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 설치 후 새 터미널을 열고, 프로그램의 버전 확인 명령(예: --version)으로 정상 설치됐는지 확인하세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

3. Python

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Python 3 설치 시 'Add Python to PATH' 옵션을 꼭 체크하세요 (Windows).

pip install agentmaker

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

pip install "agentmaker[all]" # every optional extra below

PyPI에 배포된 패키지를 바로 설치합니다. 소스 클론이 필요 없습니다.

✅ 에러 메시지 없이 실행되고 터미널에 안내 문구가 출력되면 정상입니다.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# agentmaker

[![CI](https://github.com/xinhuangcs/agentmaker/actions/workflows/ci.yml/badge.svg)](https://github.com/xinhuangcs/agentmaker/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agentmaker)](https://pypi.org/project/agentmaker/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/xinhuangcs/agentmaker/blob/main/LICENSE)
[![Changelog](https://img.shields.io/badge/changelog-latest-blue)](https://github.com/xinhuangcs/agentmaker/blob/main/CHANGELOG.md)

"Four lines of code, an agent with memory."

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.

<p>
  <a href="https://xinhuangcs.github.io/agentmaker/"><img src="docs/assets/readme-docs-en-button.svg" alt="English documentation" height="42"></a>
  <a href="https://xinhuangcs.github.io/agentmaker/zh/"><img src="docs/assets/readme-docs-zh-button.svg" alt="Chinese documentation" height="42"></a>
</p>

## 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

```bash
pip install agentmaker
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:

```python
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:

```python
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) < 4000, message="input too long")],  # validate input
)
print(agent.run("Plan a day in Copenhagen, and remember I'm vegetarian.").final_output)
```

Every argument past `llm` is optional, so you add capabilities one at a time, and the same pattern reaches the rest of the framework: RAG retrieval as another `sources=` entry, MCP servers and sub-agents (`AgentTool`) as `tools=`, a `SmartWriter` that extracts and diffs memories instead of storing raw text, structured output and streaming, the `PlanAgent` / `ReflectionAgent` workflow recipes, plus sessions, checkpoints (human-in-the-loop), permissions, and history compaction. See the [Highlights](#highlights) above for the full list.

### Debug it with an agent

For development, attach the trace-based agent debugger. When a run fails, `DoctorHook` prints an LLM-written diagnosis (first bad step, root cause, suggested fix) straight to your terminal:

```python
from agentmaker import Agent, Tracer
from agentmaker.devtools import DoctorHook

tracer = Tracer()
agent = Agent("assistant", llm, tools=[get_weather], tracer=tracer, hooks=[DoctorHook(tracer)])
print(agent.run("What's the weather in Copenhagen?").final_output)
```

`DoctorHook` prints inline; for the full picture, `python -m agentmaker.devtools` opens Trace Detective, a local web page that visualizes a recorded run step by step (its LLM calls, tool calls, and guardrails) and, on demand, has an LLM pinpoint the first bad step, root cause, and fix. Both are themselves agentmaker agents, so the framework debugs its own runs. You debug agents with an agent.

## Learn more

- [`examples/`](https://github.com/xinhuangcs/agentmaker/tree/main/examples): sixteen runnable, numbered examples, from quickstart to skills.
- [`CHANGELOG.md`](https://github.com/xinhuangcs/agentmaker/blob/main/CHANGELOG.md)
- Versioning: pre-1.0, minor versions may introduce breaking changes and patch versions only fix. Pin `agentmaker>=0.2,<0.3`.

## Contributing

Contributions are welcome, whether it's a bug report, a feature idea, a
documentation fix, or a pull request. Open an issue or PR on
[GitHub](https://github.com/xinhuangcs/agentmaker).

To set up a development environment:

```bash
git clone https://github.com/xinhuangcs/agentmaker
cd agentmaker
uv sync --all-extras
uv run pytest
```

Please include tests for any behavior change and keep the public API and docs
in sync. By contributing, you agree that your work is licensed under the
project's MIT license.

## License

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