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 large‑language‑model agents on your own computer. It ships a single engine that can be accessed through three front‑ends that share the same state:

• CLI – an interactive terminal (agentica) where each conversation is an autonomous agent.
• Web gateway – a local SPA (agentica‑gateway) at http://127.0.0.1:8881/chat with multi‑user accounts, chat history, and IM bridges (WeChat, Feishu, Telegram, etc.).
• Desktop app – native macOS/Windows/Linux builds that embed the same UI and data directory (~/.agentica).

All three run on the same backend, so you can switch between them without losing context or memory.

---

Core ideas

Idea	How Agentica implements it
One model, many agents	A single LLM (OpenAI, DeepSeek, Claude, ZhipuAI, Qwen, Ollama, etc.) powers every session. Each terminal session is an agent; you can spawn temporary sub‑agents (task) or full‑process delegates (delegate).
Self‑evolution	After a task finishes, Agentica extracts the experience into a Markdown skill (SKILL.md). Future similar tasks automatically reuse that skill, reducing the need to start from scratch.
Persistent memory	Chat history, file workspace, and extracted memories are stored on disk, indexed for relevance, and compressed with a two‑layer context‑compression pipeline.
Tool use	Built‑in tools for file I/O, patching, grep/glob, command execution, and web search. Tools run asynchronously and can be streamed in parallel.
Safety guards	Input, output, and tool‑level guardrails that filter content in real‑time.
Multimodal	Supports text, images, audio, and video inputs where the underlying model allows it.
Collaboration	Agents can talk to each other across terminals (peer messages) and can be composed into workflows, swarms, or debate‑style loops via the Python/TypeScript SDKs.
RAG & integration	Built‑in knowledge‑base management, hybrid retrieval, reranking, and adapters for LangChain / LlamaIndex.
Protocols	Implements Model Context Protocol (MCP) and Agent Communication Protocol (ACP) for standardized data exchange.

---

Quick start (Python‑first)

# Install the core package
pip install -U agentica

# Run the interactive CLI
agentica

In the CLI you can type natural language commands, e.g.:

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

---

Web gateway & Desktop

# Install the gateway extras (includes FastAPI + UI)
pip install -U "agentica[gateway]"
agentica-gateway   # starts the local web UI at http://127.0.0.1:8881/chat

Docker – a ready‑to‑run image is provided; just set OPENAI_API_KEY in .env.docker.example and docker compose up.

Desktop builds are available as signed‑less DMG (macOS), NSIS installer (Windows) and AppImage/DEB (Linux). The first launch auto‑installs a bundled Python 3.12 runtime.

---

SDKs

• Python – create an agent programmatically:

from agentica import DeepAgent
agent = DeepAgent()               # full‑featured agent with tools, memory, skills
agent.run_sync("写一篇关于 Python 3.13 新特性的报告到 report.md")

• TypeScript – talk to a running gateway from Node:

import { Agentica } from "@agentica-ai/sdk";
const client = new Agentica({baseURL: "http://127.0.0.1:8881", apiKey: process.env.AGENTICA_GATEWAY_TOKEN});
for await (const ev of client.chat.stream({message: "ping", session_id: "demo"})) {
  if (ev.event === "content") process.stdout.write(String(ev.data));
}

Both SDKs expose the same async‑first API, allowing agents to be used as tools inside other agents, to run workflows, or to build custom UIs.

---

Why choose Agentica?

1. Model‑agnostic – works with any OpenAI‑compatible or local model; you can switch providers without changing code.
2. Local‑first – all data stays on your machine; no external SaaS required except the LLM API.
3. Team‑style agents – built‑in concepts of sub‑agents, delegates, and peer messaging let you orchestrate complex multi‑step work.
4. Self‑learning – skills are auto‑generated from past runs, making the system faster and cheaper over time.
5. Rich UI options – CLI, browser‑based SPA, and native desktop client share the same history and workspace.

---

Documentation & community

• Full docs: https://shigbing624.github.io/agentica
• Example gallery: https://github.com/shibing624/agentica/tree/main/examples
• Issues & contributions via GitHub.
• Chinese‑language WeChat group for real‑time help (QR code in README).

---

License

Apache License 2.0 – free for commercial and academic use.

---

Bottom line – Agentica is a production‑ready, extensible framework for building, running, and evolving LLM‑powered agents on your own hardware, with a focus on multi‑agent collaboration, persistent memory, and easy integration via CLI, web UI, desktop app, or SDKs.