Developer guide

Language: 简体中文 | 日本語 | 四川话 | English

For contributors and anyone hacking the library. End users should start at the documentation home or Quick start.

Layout

src/pagent/     v1 library
src/pagentv4/   v4 library (core, runtime, sandbox, skills)
src/app/        application layer (REPL, CLI) on top of pagentv4
examples/       runnable demos grouped by category (see examples/pagentv4/)
tests/          pytest
docs/           documentation

Core: agent.py, session.py, llm.py, tool.py, tokens.py, events.py.

Capability map

Module	Notes
Session	OpenAI-shaped messages; SlidingWindowSession trims by tokens; CompactingSession LLM-compresses history
LLM	invoke / invoke_stream; returns RunEnd
Agent	run / arun / arun_events / arun_wire
tokens	count_tokens, count_tokens_detail, format_context
events / wire	UI timeline — events.md, wire.md

中文完整表：开发指南

Out of scope

Parallel tools, RAG, MCP, built-in file/shell tools, multimodal, checkpoints — build in your app.

Planned: Hooks support plan (lifecycle hooks for tool approval, cancel, context injection; distinct from Event/Wire).

Local development

Uses uv for env management. New to uv? See the official docs.

uv sync --group dev --extra search
pip install -e ".[search]"
pre-commit install
pytest -q

Documentation site

Built with VitePress. Config: docs/.vitepress/config.mts, content: docs/*.md. Mermaid diagrams use vitepress-plugin-mermaid (fenced ```mermaid blocks).

For coding agents / LLMs: agent-reference, repo AGENTS.md, llms.txt, llms-full.txt (npm run build:llms in docs/ regenerates the bundle).

cd docs
npm install
npm run dev            # http://localhost:5173/pagent/
npm run build          # output in docs/.vitepress/dist/

Node tooling lives under docs/ (package.json, package-lock.json) so the repo root stays Python-only.

Do not commit docs/.vitepress/dist/ or site/ — they are in .gitignore. Only Markdown sources under docs/ live on main.

On push to main, docs.yml runs npm run build in docs/ and publishes docs/.vitepress/dist/ to the gh-pages branch. Enable in repo Settings → Pages → Deploy from branch → gh-pages / root.

Publishing

.github/workflows/publish.yml — PyPI via Trusted Publishing on release.

See also

• events.md
• reasoning.md