# Semantica agent 接入入门

这是一个可以直接运行的 [Semantica](https://github.com/semantica-agi/semantica) 小项目，专门回答一件事：

**agent 是怎么接到 Semantica 上的？**

结论先说清楚：

- Semantica **不是** agent 框架。
- 它不调度工具、不跑 ReAct、不管理 multi-agent 对话。
- 它是 agent 下面的语义层：记忆、知识图谱、决策审计。
- 任何 agent（自己写的循环、Agno、LangChain、CrewAI、Claude、Cursor）都通过同一组插头接入。

```text
你的 agent（自己写 / Agno / LangChain / CrewAI / Claude）
        │
        ├── memory     AgentContext.store / list
        ├── knowledge  ContextGraph.add_node / query
        ├── decisions  record_decision / 因果链
        └── tools      框架 Toolkit 或 MCP
        ▼
   Semantica
```

五课默认**不需要 LLM**。第 2 课的决策可以额外接本地 runtime 或云端 API key，两者走同一条 OpenAI 兼容插头。

## 0. 环境

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)

Intel macOS 会自动钉住仍提供 x86_64 轮子的 `torch` / `onnxruntime` / `numba`。其它平台由 Semantica 自己解析依赖。

## 1. 安装

```bash
git clone https://github.com/sin3000x/semantica-agent-starter.git
cd semantica-agent-starter
uv sync
```

验证：

```bash
uv run python --version
uv run python -c "import semantica; print(semantica.__version__)"
uv run python main.py doctor
```

第一次创建 `VectorStore` 可能下载 embedding 模型；第一次导入 Semantica 也会比较慢。

## 2. 开始上课

```bash
uv run python main.py
uv run python main.py 1
```

| 课 | 做什么 |
| --- | --- |
| 1 | 插头就是 `AgentContext`：写入记忆 + `record_decision` |
| 2 | 采购 agent：感知 → 查先例 → 决策 → 落盘 |
| 3 | 两个 agent **不发消息**，读写同一张 `ContextGraph` |
| 4 | Agno / LangChain / CrewAI 只是把四个插座包成框架对象 |
| 5 | Claude / Cursor 走 MCP：`python -m semantica.mcp_server` |

```bash
uv run python main.py all
```

## 3. 可选：接 LLM（runtime 或 API key）

第 2 课默认用规则：`延期天数 > 库存天数` 就升级。规则一直可测、可回退。

配置了 LLM 之后，`decide()` 会先问模型；解析失败或连不上就退回规则。Semantica 仍然只负责记住决定。

复制环境文件：

```bash
cp .env.example .env
```

### 本地 runtime（无 key）

**OpenCode** 是一等 runtime：默认调用本机 `opencode run`，用你已经 `opencode auth login` 过的模型，不必再配一份 API key。

```bash
# 先装 OpenCode，并完成登录
# curl -fsSL https://opencode.ai/install | bash
# opencode auth login

SEMANTICA_LLM=opencode
# 可省略，缺省用 OpenCode 当前默认模型
# SEMANTICA_LLM_MODEL=anthropic/claude-sonnet-4-5
```

已经 `opencode serve` 时，让 CLI 挂到现有服务上，避免每次冷启动：

```bash
SEMANTICA_LLM=opencode
OPENCODE_ATTACH=http://127.0.0.1:4096
```

若你跑的是 OpenCode 的 OpenAI 兼容代理（例如 `opencode-llm-proxy` 的 `:4010`），把地址写成 `/v1` 即可：

```bash
SEMANTICA_LLM=opencode
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:4010/v1
```

也适合 Ollama、vLLM、LM Studio，以及任何 OpenAI 兼容服务。

```bash
# Ollama
ollama pull llama3.1
# .env
SEMANTICA_LLM=ollama
SEMANTICA_LLM_MODEL=llama3.1
OLLAMA_HOST=http://127.0.0.1:11434
```

```bash
# LM Studio / vLLM
SEMANTICA_LLM=compat
SEMANTICA_LLM_BASE_URL=http://127.0.0.1:1234/v1
SEMANTICA_LLM_MODEL=local-model
SEMANTICA_LLM_API_KEY=local
```

### 云端 API + key

默认推荐 [SpaceXAI / xAI](https://console.x.ai)（OpenAI 兼容，`XAI_API_KEY`）。

```bash
XAI_API_KEY=xai-...
# 可省略 SEMANTICA_LLM，有 XAI_API_KEY 就会自动选 xai
SEMANTICA_LLM_MODEL=grok-4.6
```

也可以用 `OPENAI_API_KEY` 或 `GROQ_API_KEY`。探测顺序：显式 `SEMANTICA_LLM` → `XAI_API_KEY` → `OPENAI_API_KEY` → `GROQ_API_KEY`。

```bash
uv run python main.py doctor
uv run python main.py 2
```

不要把 `.env` 提交进 git。

## 4. MCP

配置样例在 `mcp/`。把 `/ABS/PATH/TO/semantica-agent-starter` 换成你的克隆路径。

```bash
uv run python -m semantica.mcp_server
```

## 5. 测试

```bash
uv run pytest
```

`tests/test_llm.py` 不访问网络。课程测试第一次大约需要几分钟（Semantica 导入和 `VectorStore` 初始化比较重）。

测试检查的是接入约束：

- agent 写入的记忆和决定都能读回来
- 规则 agent 的第二次决定能追溯到第一次
- 两个 agent 共享同一张图
- 没配 key 时不会误接 LLM；配了坏响应会回退规则

## 6. 官方框架怎么接

| 框架 | 接到哪 |
| --- | --- |
| 自己写循环 | 直接调 `AgentContext` |
| Agno | `AgnoContextStore` + `AgnoDecisionKit` + `AgnoSharedContext.bind_agent` |
| LangChain | `SemanticaKGTool` + `SemanticaDecisionTool` + `SemanticaRetriever` |
| CrewAI | `SemanticaKGTool` + `SemanticaDecisionTool` + `SemanticaKnowledgeSource` |
| Claude / Cursor | MCP |

本项目不安装这些 extra。第四课用一个小适配器把同样的四个插座跑通。

## License

MIT