# 框架集成（即将上线）

在 Vercel AI SDK、LangChain、LlamaIndex、OpenAI Agents SDK、Mastra 和 CrewAI 中使用 Mirabase 的工具、记忆和检索。

> **注意：** 以下集成包尚未发布，包名在发布前可能调整，发布时本页会给出安装命令。在此之前，请直接使用 [SDK](https://mirabase.io/zh/developers/sdks.md) 或 [MCP](https://mirabase.io/zh/developers/agents.md)。

每个集成均提供相同的五个工具：`mirabase_search`、`mirabase_answer`、`mirabase_read_file`、`mirabase_write_file` 和 `mirabase_list_files`。引用附带文件路径和版本。将通过 `spaceFor(userId)`（Python 为 `space_for`）固定到某个 Space 的客户端传入集成，即可为每个最终用户使用独立的 Space。各集成基于 SDK 0.3.0-rc.1（Python 为 0.3.0rc1）。

- `mirabase_list_files` 以 `size_bytes` 返回文件大小，TypeScript 与 Python 一致。响应带 `pending_processing` 时，`mirabase_search` 将其一并交给模型。
- 基于对话的消息历史和 Session 默认读取最近 20 个批次，可用 `maxBatches`（Python 为 `max_batches`）调整。
- `mirabaseAnswerModel` 发送最近 10 轮对话，每轮保留开头的 4,000 个字符；超过 4,000 个字符的问题保留末尾部分，并在该次调用中给出警告。检索器和工具对超长的查询、任务或问题同样保留末尾部分。

| 框架 | 语言 | 包名（未发布） | 提供的组件 | 测试版本 |
| --- | --- | --- | --- | --- |
| Vercel AI SDK | TypeScript | `@mirabase/vercel-ai` | 工具、记忆中间件、封装 Mirabase 带引用回答的模型 | `ai` 7.0.173 |
| LangChain.js | TypeScript | `@mirabase/langchain` | 检索器、基于对话的消息历史、文档加载器、工具 | `@langchain/core` 1.4.1 |
| LangChain | Python | `mirabase-langchain` | 检索器、基于对话的消息历史、文档加载器、工具 | `langchain-core` 1.8.1 |
| LlamaIndex | Python | `mirabase-llamaindex` | 检索器、带引用的查询引擎、读取器 | `llama-index-core` 0.14.26 |
| OpenAI Agents SDK | TypeScript | `@mirabase/openai-agents` | 工具、基于对话的 Session | `@openai/agents` 0.22.0 |
| OpenAI Agents SDK | Python | `mirabase-openai-agents` | 工具、基于对话的 Session | `openai-agents` 0.24.0 |
| Mastra | TypeScript | `@mirabase/mastra` | 工具、记忆处理器 | `@mastra/core` 1.83.0 |
| CrewAI | Python | `mirabase-crewai` | 工具、在 Mirabase 中检索的 Knowledge | `crewai` 1.15.41 |

> **说明：** 示例中的 `model` 指你在该框架中使用的模型。

## Vercel AI SDK

`mirabaseTools` 提供五个工具；`mirabaseMemory` 是模型中间件，在调用模型前用最后一条用户消息构建上下文，调用后将本轮对话存为 Mirabase 对话，供服务提炼记忆。在未配置自有模型时，可使用 `mirabaseAnswerModel`，将 Mirabase 的带引用回答作为模型调用。

```ts
import { Mirabase } from "@mirabase/sdk/developer";
import { mirabaseMemory, mirabaseTools } from "@mirabase/vercel-ai";
import { generateText, stepCountIs, wrapLanguageModel } from "ai";

const mb = await new Mirabase().spaceFor("user-42"); // one Space per end user
const { text } = await generateText({
  model: wrapLanguageModel({ model, middleware: mirabaseMemory({ client: mb, sessionId: "chat-1" }) }),
  tools: mirabaseTools({ client: mb }),
  stopWhen: stepCountIs(5),
  prompt: "What did we decide about the launch?",
});
```

## LangChain

`MirabaseRetriever` 返回带引用的文档，`metadata` 中包含路径、版本和引用 id；`MirabaseChatMessageHistory` 将消息历史存为 Mirabase 对话。此外还提供文档加载器和工具。

TypeScript:

```ts
import { Mirabase } from "@mirabase/sdk/developer";
import { MirabaseChatMessageHistory, MirabaseRetriever } from "@mirabase/langchain";

const mb = new Mirabase();
const docs = await new MirabaseRetriever({ client: mb, k: 5 }).invoke("When do we ship?");
console.log(docs[0]?.metadata.path, docs[0]?.metadata.citation_id);
const history = new MirabaseChatMessageHistory({ client: await mb.spaceFor("user-42"), sessionId: "chat-1" });
```

Python:

```python
from mirabase import Mirabase
from mirabase_langchain import MirabaseChatMessageHistory, MirabaseRetriever

mb = Mirabase()
docs = MirabaseRetriever(client=mb, k=5).invoke("When do we ship?")
print(docs[0].metadata["path"], docs[0].metadata["citation_id"])
history = MirabaseChatMessageHistory(mb.space_for("user-42"), "chat-1")
```

## LlamaIndex

`MirabaseQueryEngine` 调用 Mirabase 的回答接口作答，无需自备模型，`source_nodes` 为被引用的片段；`MirabaseRetriever` 则可接入 LlamaIndex 的查询引擎，由你自己的模型作答。

```python
from mirabase import Mirabase
from mirabase_llamaindex import MirabaseQueryEngine, MirabaseRetriever

mb = Mirabase()
response = MirabaseQueryEngine(client=mb).query("When do we ship?")
print(response, [n.node.metadata["path"] for n in response.source_nodes])
nodes = MirabaseRetriever(mb, similarity_top_k=5).retrieve("launch owner")
```

## OpenAI Agents SDK

`mirabaseTools`（Python 为 `mirabase_tools`）提供启用严格模式的五个工具；`MirabaseSession` 将每一轮对话存为 Mirabase 对话。

TypeScript:

```ts
import { Agent, run } from "@openai/agents";
import { Mirabase } from "@mirabase/sdk/developer";
import { MirabaseSession, mirabaseTools } from "@mirabase/openai-agents";

const mb = await new Mirabase().spaceFor("user-42");
const assistant = new Agent({ name: "Assistant", instructions: "Answer from the user's files.", tools: mirabaseTools({ client: mb }) });
const session = new MirabaseSession({ client: mb, sessionId: "chat-1" });
const result = await run(assistant, "What did we decide about the launch?", { session });
```

Python:

```python
from agents import Agent, Runner
from mirabase import Mirabase
from mirabase_openai_agents import MirabaseSession, mirabase_tools

mb = Mirabase().space_for("user-42")
assistant = Agent(name="Assistant", instructions="Answer from the user's files.", tools=mirabase_tools(mb))
result = Runner.run_sync(assistant, "What did we decide?", session=MirabaseSession(mb, "chat-1"))
```

## Mastra

`mirabaseMemory` 是一个处理器：在输入阶段注入 Mirabase 构建的上下文，在输出阶段将本轮对话存为 Mirabase 对话。它可以与 Mastra 自身的线程记忆同时使用。

```ts
import { Agent } from "@mastra/core/agent";
import { Mirabase } from "@mirabase/sdk/developer";
import { mirabaseMemory, mirabaseTools } from "@mirabase/mastra";

const mb = await new Mirabase().spaceFor("user-42");
const memory = mirabaseMemory({ client: mb, sessionId: "chat-1" });
const assistant = new Agent({ id: "assistant", name: "Assistant", instructions: "Be brief.", model,
  tools: mirabaseTools({ client: mb }), inputProcessors: [memory], outputProcessors: [memory] });
const { text } = await assistant.generate("What should I cook tonight?");
```

## CrewAI

`mirabase_knowledge` 是通过 Mirabase 进行检索的 CrewAI `Knowledge` 数据源，无需本地向量库或向量模型的 API Key；`mirabase_tools` 提供五个工具。

```python
from crewai import Agent, Crew, Task
from mirabase import Mirabase
from mirabase_crewai import mirabase_knowledge, mirabase_tools

mb = Mirabase()
planner = Agent(
    role="Planner",
    goal="Answer from the team's notes",
    backstory="Knows the release plan.",
    tools=mirabase_tools(mb, read_only=True),
    knowledge=mirabase_knowledge(mb, path="/notes"),
)
task = Task(description="When do we ship, and who owns it?", expected_output="A day and a name", agent=planner)
print(Crew(agents=[planner], tasks=[task]).kickoff())
```

## 下一步

- [SDK](https://mirabase.io/zh/developers/sdks.md)：集成所基于的客户端。
- [连接 Agent（MCP）](https://mirabase.io/zh/developers/agents.md)：不使用框架时，通过 MCP 接入同样的工具。
- [检索与上下文](https://mirabase.io/zh/developers/retrieval.md)：集成调用的检索接口。
