easy-agentic

An Agent-oriented plugin framework: it provides a unified extension-injection mechanism for agents built on top of LangGraph deepagents + langgraph-cli. Every extension (agent / tool / skill / filesystem / middleware / model, …) is wired in through plugins.

It is not a business agent, and it does not implement a runtime or a serving container — those are handled by deepagents and langgraph-cli respectively. For the detailed positioning and design, see doc/requirement.md and doc/architecture.md.

Tech stack

• Python 3.12 (pinned via uv)
• Package / environment management: uv
• Agent runtime: deepagents; serving / interface: langgraph-cli (agent server)
• LLM direction: Claude (langchain-anthropic)

Quick start

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Sync dependencies (install everything from uv.lock into .venv)
uv sync

# 3. Configure environment variables: copy the .env template and fill in API keys, etc.
#    (.env is git-ignored — never commit real secrets)

# 4. Start the local agent server (LangGraph Studio)
uv run langgraph dev
# Defaults to http://127.0.0.1:2024

Using easy-agentic as a library

easy-agentic is published as an importable library. In a consumer project:

pip install easy-agentic          # core only
pip install easy-agentic[cli]     # + langgraph-cli for `langgraph dev`
pip install easy-agentic[all]     # + Anthropic/OpenAI providers + CLI

Point your own langgraph.json at the built-in global router graph:

{
  "dependencies": ["."],
  "graphs": { "agent": "easy_agentic.graph:main" },
  "env": ".env"
}

Then drop in your own agents/ and plugins/ directories. Prefer to compose the graph yourself? Use the build_graph() factory exported from the top-level package.

Optional extras:

How uv is used

uv is a single tool that handles Python version + virtual environment + dependencies + running: it reads pyproject.toml (declared dependencies) → resolves uv.lock (pinned exact versions) → syncs them into .venv. Day to day you do not need to activate the virtual environment manually — just use uv run.

Most-used commands

90% of the time you'll only use uv add and uv run.

Key points

• Dependencies are managed only through uv add — don't hand-edit the dependencies in pyproject.toml; exact versions are pinned in uv.lock (kept under version control).
• uv run implicitly syncs the environment before executing, so after adding a dependency you can run uv run directly — no need to uv sync first.
• No pip install, no source .venv/bin/activate — uv prepares the environment for the subprocess automatically.
• Python version is pinned to 3.12 by .python-version; uv selects the matching interpreter automatically.

How uv run works internally (in brief)

uv run X ≈ "ensure the environment matches the lock" + "temporarily activate .venv" + "run X". X ultimately resolves to an executable under .venv/bin/ bound to this project's interpreter:

• uv run pytest → runs .venv/bin/pytest (an entry-point script generated at install time, whose shebang points at the project .venv python)
• uv run python foo.py → runs foo.py with .venv/bin/python

Handy flags: --no-sync (skip syncing), --frozen (don't re-resolve), --locked (require the lock to be up to date, good for CI).

Common development commands

uv run langgraph dev          # Start the local agent server (entry graph: easy_agentic.graph:main)
uv run pytest                 # Run tests
uv add <pkg> / uv add --dev <pkg>   # Add dependencies
uv sync                       # Sync the environment

Project documentation

• CLAUDE.md — project constitution (for AI collaborators)
• doc/ — requirements, architecture, conventions, roadmap, decision records (ADRs)

The documents under doc/ are kept in Chinese as the design/working record.