进化智能代理

Clone the repository and install dependencies

git clone https://github.com/agenttoolkit/altk-evolve.git cd altk-evolve uv venv --python=3.12 && source .venv/bin/activate uv sync --package altk-evolve

Installation

Prerequisites: - Python 3.12 or higher - uv (recommended) or pip

From Source ```bash

Build the UI

cd frontend/ui npm ci && npm run build cd ../..

From PyPI

**Choose your installation:**

- `altk-evolve` bundles `altk-evolve-core[server,cli,fastembed,tracing]` at the same version.
- `altk-evolve-core` contains the Python implementation without server/CLI dependencies,
  an embedding runtime, or a Phoenix server. Libraries should depend on core and select the extras they need.
- Add `[server]` for the HTTP/MCP server and its telemetry exporters, or `[cli]`
  for the command-line interface. `[telemetry]` provides the SDK and OTLP exporter
  independently; both `[server]` and `[tracing]` include it. Core retains the OpenTelemetry API so host applications
  can supply their own telemetry providers.
- All extras belong to core. Existing `altk-evolve[pgvector]`, `[pii-semantic]`, and
  other extras forward to core while retaining the convenience defaults.
- Install `altk-evolve-core[phoenix]` (or `altk-evolve[phoenix]`) only to run the
  local Phoenix server. Remote tracing uses the separate `arize-phoenix-otel` package.

Both packages use the same `altk_evolve` imports and `evolve` / `evolve-mcp` commands;
only core owns those files. Core-only filesystem storage works without an embedding
runtime. Features that embed text require `[fastembed]` or `[sentence-transformers]`.

**Embedding migration:** FastEmbed is now the default provider. To retain the
previous runtime, install `altk-evolve-core[sentence-transformers]` and set
`EVOLVE_EMBEDDING_PROVIDER=sentence_transformers`. Validate retrieval quality before
switching an existing vector store to another runtime; changing models requires
re-embedding stored vectors.

**Source development and releases:** The root project is core. Use
`uv sync --package altk-evolve` for the convenience bundle, or select root extras
explicitly. After changing the version or extras, run
`uv run --no-project python scripts/sync_convenience.py` and `uv lock`.
`uv build --all-packages` builds both distributions. Releases publish core first,
then the exactly matching convenience package through the same trusted publisher.

**Optional Backend Dependencies:**

The default filesystem backend uses simple text matching and requires no additional dependencies. For semantic vector similarity search, install one of these backends:

For PostgreSQL with pgvector support (recommended for production):

For Milvus support (optimized for large-scale vector search):

See the Backend Configuration Guide for detailed comparison and setup instructions.

Quick Start (Lite)

IBM Bob →

Claude Code →

Codex →

Hermes →

Quick Start (Evolve MCP Server)

Guideline Provenance

Evolve automatically tracks the origin of every guideline it generates or stores. Every guideline entity contains metadata identifying its source: - creation_mode: Identifies how the guideline was created (auto-phoenix via trace observability, auto-mcp via trajectory saving tools, or manual). - source_task_id: The ID of the original trace or task that inspired the guideline, providing full auditability.

See the Low-Code Tracing Guide for more details.

Configuration

For direct OpenAI usage:

export OPENAI_API_KEY=sk-...

For LiteLLM proxy usage and model selection (including global fallback via EVOLVE_MODEL_NAME), see the configuration guide.

Embedded memory API and scheduling

Hosts can mount the scoped REST router with their own client and authentication dependencies. Evolve owns retention schedules and worker execution, using Kubernetes-compatible cron, timezone, concurrency, deadline, and suspension fields. Use evolve retention schedules to manage schedules and start/stop to enable or suspend them. The Evolve service owns background execution.

The public retention service is available as client.retention(namespace_id, agent_id=...); CLI, REST, MCP, and scheduling share its operations and scope checks.