内容
# AgentKit
Production-oriented Agent Engineering Platform — stateful workflow orchestration, three-tier evaluation pipelines, LLM observability, and MCP-based tool management.
## Quick Start
```bash
cp .env.example .env # fill in API keys (see Environment Variables below)
docker compose up -d # start postgres + langfuse + mcp server
pip install -e ".[dev]"
python examples/run_code_review.py
```
## Architecture
```
┌──────────────────────────────────────────────────────────────┐
│ Layer 5 — Eval & CI │
│ eval/ benchmark/ scripts/ .github/workflows/ │
├──────────────────────────────────────────────────────────────┤
│ Layer 4 — Workflow (business agents) │
│ workflow/code_review/ workflow/research/ │
├──────────────────────────────────────────────────────────────┤
│ Layer 3 — Runtime Core │
│ runtime/ tracing/ memory/ │
├──────────────────────────────────────────────────────────────┤
│ Layer 2 — Tool Service │
│ mcp/server.py mcp/tools/ tools/ │
├──────────────────────────────────────────────────────────────┤
│ Layer 1 — Infrastructure (external) │
│ PostgreSQL Langfuse LLM API Search API │
└──────────────────────────────────────────────────────────────┘
```
See [`doc/architecture.md`](doc/architecture.md) for full design, and [`doc/modules/`](doc/modules/) for per-module design docs.
## Modules
| Module | Path | Description |
|---|---|---|
| Runtime | `agentkit/runtime/` | LangGraph graph engine, state, checkpoint, streaming, tool dispatch |
| Tracing | `agentkit/tracing/` | Langfuse integration, `@trace_node` decorator, state sanitisation |
| Memory | `agentkit/memory/` | Session window management and cross-session KV summaries |
| Tools (direct) | `agentkit/tools/` | Direct-call tool functions (file I/O, web search, code exec) |
| MCP Server | `agentkit/mcp/` | FastAPI + SSE MCP server wrapping the tool functions |
| Code Review Agent | `agentkit/workflow/code_review/` | Multi-step code review with human-in-the-loop approval |
| Research Agent | `agentkit/workflow/research/` | Multi-iteration search-and-synthesise research report |
| Eval Pipeline | `eval/` | Three-tier evaluation: Run, Trace (LLM-as-Judge), Thread |
| Benchmark | `benchmark/` | 40 test cases (20 code review + 20 research), baselines, thresholds |
| CI/CD | `.github/workflows/` | `ci.yml` (lint+test), `eval-fast.yml` (PR gate), `eval-trace.yml` (nightly) |
## Running the Agents
```bash
# Code review agent
python examples/run_code_review.py
# Research report agent
python examples/run_research.py
```
## Running Evals
```bash
# Fast eval — Run + Thread tiers, deterministic, <3 min (used in PR gate)
python -m eval.runner --tiers run,thread
# Trace eval — LLM-as-Judge, ~20 min (runs nightly via cron)
python -m eval.runner --tiers trace
# Full eval — all three tiers
python -m eval.runner --tiers run,thread,trace --output benchmark/reports/latest.json
# Check thresholds after a run
python scripts/ci_gate.py benchmark/reports/latest.json --tiers run,thread
```
## Calibrating Thresholds (first run)
After the first successful eval run, generate the baseline and thresholds:
```bash
cp benchmark/reports/latest.json benchmark/baselines/v1.0_scores.json
python scripts/update_thresholds.py benchmark/baselines/v1.0_scores.json --margin 0.05
```
## Environment Variables
| Variable | Required | Description |
|---|---|---|
| `ANTHROPIC_API_KEY` | Yes | Claude API key |
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `MCP_API_KEY` | Yes | MCP server auth key |
| `MCP_SERVER_URL` | Yes | MCP server address (default `http://localhost:8001`) |
| `LANGFUSE_SECRET_KEY` | No | Langfuse secret key — tracing disabled if unset |
| `LANGFUSE_PUBLIC_KEY` | No | Langfuse public key |
| `LANGFUSE_HOST` | No | Langfuse host (default Langfuse Cloud) |
| `AGENTKIT_CHECKPOINT_BACKEND` | No | `auto`/`memory`/`postgres` (default `auto`) |
| `SANDBOX_DIR` | No | File tool sandbox dir (default `/tmp/agentkit-sandbox`) |
| `LONGTERM_MEMORY_PATH` | No | SQLite path for long-term memory |
| `REDIS_URL` | No | Redis URL — takes priority over SQLite for long-term memory |
| `SEARCH_PROVIDER` | No | `stub` (default) or `tavily` |
| `TAVILY_API_KEY` | No | Tavily API key (required when `SEARCH_PROVIDER=tavily`) |
See `.env.example` for the full template.
## Docker Compose Services
| Service | Port | Description |
|---|---|---|
| `postgres` | internal | PostgreSQL 15 — Checkpoint + long-term memory storage |
| `langfuse` | 3000 | Langfuse observability dashboard (optional) |
| `agentkit-mcp` | 8001 | MCP tool server |
| `agentkit-runtime` | — | Agent runtime (runs demo on startup) |
## Development
See [`doc/CONTRIBUTING.md`](doc/CONTRIBUTING.md) for setup, lint, testing, and PR guidelines.
## Documentation
| Document | Description |
|---|---|
| [`doc/PRD.md`](doc/PRD.md) | Product requirements |
| [`doc/architecture.md`](doc/architecture.md) | System architecture design |
| [`doc/design-decisions.md`](doc/design-decisions.md) | Key design decision rationale |
| [`doc/modules/`](doc/modules/) | Per-module design docs (8 modules) |
| [`doc/task-breakdown-v1.1.md`](doc/task-breakdown-v1.1.md) | Implementation task breakdown |
MCP 市场