shibing624/agentica

Agentica – A Local, Multi‑Agent LLM Framework

What it is – Agentica is an open‑source, Apache‑2.0‑licensed Python package that lets you run LLM‑powered agents on your own machine. It ships a CLI, a self‑hosted web UI, and a desktop app that all share the same backend, so you can interact with agents from a terminal, a browser, or a native window without any remote service.

Why it matters – The project focuses on three pain points that many LLM‑agent tools ignore:

1. Cost‑effective inference – deep integration with open models such as DeepSeek, Claude, ZhipuAI, Qwen, Ollama, etc., and a benchmark showing higher accuracy and up to ⅔ fewer input tokens compared with OpenAI Codex on coding and data‑analysis tasks.
2. Long‑context handling without LLM summarisation – tool outputs are streamed to disk, only a short preview stays in the prompt, and a deterministic “window‑based eviction” policy discards the oldest data when the context window reaches 80 % capacity. The full session is stored in a JSONL file and can be searched later, guaranteeing loss‑less recall.
3. Self‑evolution – after completing a task the agent automatically extracts a skill card (SKILL.md) that can be reused by future sessions, turning experience into reusable knowledge.

---

Core Features (jargon‑light)

Feature	What it does
Async‑first engine	All tool calls run concurrently with asyncio, giving faster multi‑tool workflows.
Built‑in tools	File read/write, patch application, grep/glob, command execution, web search, and multimodal (image/audio/video) understanding.
Multi‑model support	Plug‑in any chat model via OpenAI, DeepSeek, Claude, ZhipuAI, Qwen, Moonshot, Ollama, LiteLLM, etc.
Safety guardrails	Real‑time input, output, and tool‑level validation to stop harmful or malformed actions.
Memory & compression	Persistent session memory with relevance‑based recall; loss‑less context compression that never relies on LLM‑generated summaries.
Skill system	Markdown‑based skill files are auto‑generated from experience and can be shared across projects or users.
Multi‑agent collaboration	Within a terminal you can spawn a task (sub‑agent), a delegate (separate process), or send peer messages to other terminals.
RAG integration	Built‑in knowledge‑base management, hybrid retrieval, reranking, and optional LangChain/LlamaIndex connectors.
MCP / ACP protocols	Model Context Protocol and Agent Communication Protocol for standardized data exchange (JSON, SSE, etc.).
SDKs	Python SDK (agentica) and TypeScript SDK (@agentica-ai/sdk) for embedding agents in code or building custom front‑ends.
Deploy options	Run locally via uv/pip, Docker compose, or the pre‑built desktop binaries for macOS, Windows, and Linux.

---

Getting Started (quick‑start)

1. Install – The recommended way is the lightweight uv tool:

   curl -LsSf https://astral.sh/uv/install.sh | sh   # install uv
   uv tool install agentica               # CLI only
   uv tool install "agentica[gateway]"   # also install the web/desktop gateway
   

2. Configure a model – Export an API key (OpenAI, DeepSeek, ZhipuAI, etc.) or place it in ~/.agentica/.env.
3. Run the CLI – agentica drops you into an interactive prompt where you can type natural language commands, e.g.:

   > 帮我看下这个仓库的单测为什么挂了
   

4. Web UI – Start the gateway with agentica-gateway and open http://127.0.0.1:8881/chat. The same session history is shared with the CLI and desktop app.
5. Desktop app – Download the appropriate installer from the README and launch; it uses the same backend and stores data under ~/.agentica.

---

Ecosystem & Extensibility

• Python SDK – Create an Agent with a model and a list of tools, then call run_sync or run_async to let the agent perform a task.
• TypeScript SDK – Connect to a running gateway from Node.js and stream chat events.
• Plugins / custom tools – Implement any async function that follows the tool interface and register it with the agent.
• Docker – A ready‑made compose file builds the gateway and UI together; the workspace is persisted in a named volume.
• Community – GitHub issues, a WeChat group, and contribution guidelines are provided.

---

Who Might Use It?

• Developers who want a programmable LLM assistant for coding, data analysis, or research without sending data to the cloud.
• Researchers interested in studying long‑context compression, self‑evolving agents, or multi‑agent collaboration.
• Teams that need a locally hosted, multi‑user chat interface (web or desktop) with per‑user memory isolation.

---

License & Citation

• License: Apache 2.0 (permissive, commercial‑friendly).
• Citation: The README supplies BibTeX entries for both the software and a related research paper on self‑evolution of LLM agents.

---

Bottom line – Agentica is a full‑featured, locally runnable LLM‑agent platform that combines a CLI, web UI, and desktop client, offers sophisticated memory handling, multi‑model flexibility, and a skill‑learning loop, making it a solid choice for anyone who wants to build or experiment with autonomous AI agents on their own hardware.