LangChain 与 LangGraph

BeeOS 为 LangChain 的两种语言分别提供原生集成：Python 使用 langchain-beeos，JavaScript 与 TypeScript 使用 @beeos-ai/langchain。它们将固定的 BeeOS 实例、智能体、计算机和移动设备转换为标准 LangChain 工具。 LangGraph 可以通过 ToolNode 使用同一组工具，因此不需要单独的 LangGraph 包。

langchain-beeos 与 @beeos-ai/langchain 0.1.0 正在准备发布，目前尚未在 PyPI 或 npm 提供。下方安装命令将在首个包版本发布后生效。

选择接入面

需求	推荐接入面	原因
构建 Python LangChain 或 LangGraph 应用	`langchain-beeos`	类型化工具、固定目标、显式修改权限范围和 Python 生命周期管理
构建 Node.js LangChain.js 或 LangGraph.js 应用	`@beeos-ai/langchain`	类型化工具、固定目标、显式修改权限范围和官方 TypeScript SDK
让任何支持 MCP 的框架发现远程工具	MCP	不需要安装框架专用 BeeOS 包
在模型选工具之外构建确定性编排	BeeOS Python SDK 或 OpenAPI	由应用管理重试、任务状态和控制流

当 BeeOS 操作需要进入 LangChain 或 LangGraph 工具循环时，使用 langchain-beeos。协议级连接使用 MCP，确定性的控制面代码则直接使用 BeeOS SDK。

安装和配置

安装包

本示例使用 OpenAI LangChain 集成作为模型提供方，也可以替换为任何兼容的 LangChain 对话模型。

pip install langchain-beeos langchain langgraph langchain-openai

设置凭证

凭证必须保存在源码控制之外。

export BEEOS_API_KEY="your_beeos_api_key"
export BEEOS_API_URL="https://openapi.beeos.ai"
export BEEOS_INSTANCE_ID="inst_example"
export OPENAI_MODEL="your_model_name"

选择固定目标

实例、计算机和移动设备工具需要传入 instance_id，持久智能体任务工具需要传入 agent_id。这些资源 ID 属于应用配置，不会作为模型生成的工具参数公开。

JavaScript 或 TypeScript 需要服务端 Node.js 22.12 或更高版本：

npm install @beeos-ai/langchain @langchain/core

再按应用需要添加 langchain、@langchain/langgraph 和模型提供方包。请把 BEEOS_API_KEY 留在服务端，不要把本集成或凭证打进浏览器 bundle。

创建只读 LangChain 智能体

工具包默认只公开已配置目标的读取操作。以下示例允许模型检查设备状态，但不授予输入控制能力：

import os

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_beeos import BeeOSToolkit


with BeeOSToolkit(
    instance_id=os.environ["BEEOS_INSTANCE_ID"],
    include_tools={"beeos_computer_info", "beeos_mobile_info"},
) as toolkit:
    agent = create_agent(
        model=ChatOpenAI(model=os.environ["OPENAI_MODEL"]),
        tools=toolkit.get_tools(),
    )
    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "Report which configured BeeOS device is online.",
                }
            ]
        }
    )

智能体的构建和调用必须留在 with 块内。采用这种写法时，工具包拥有 BeeOS 客户端，并在退出 with 块时将其关闭。

创建只读 JavaScript 智能体

JavaScript/TypeScript 包使用 camelCase 配置，同时保持与 Python 版一致的安全策略：

import { createAgent } from "langchain";
import { ChatOpenAI } from "@langchain/openai";
import { BeeOSToolkit } from "@beeos-ai/langchain";

const instanceId = process.env.BEEOS_INSTANCE_ID;
if (!instanceId) throw new Error("BEEOS_INSTANCE_ID is required");

const toolkit = new BeeOSToolkit({
  instanceId,
  includeTools: ["beeos_computer_info", "beeos_mobile_info"],
});
const agent = createAgent({
  model: new ChatOpenAI({ model: process.env.OPENAI_MODEL }),
  tools: toolkit.getTools(),
});
const result = await agent.invoke({
  messages: [{ role: "user", content: "Report which configured device is online." }],
});

在 LangGraph 中使用工具

LangGraph 预构建的 ToolNode 可以直接使用同一组标准 LangChain 工具：

import os

from langgraph.prebuilt import ToolNode
from langchain_beeos import BeeOSToolkit


with BeeOSToolkit(
    instance_id=os.environ["BEEOS_INSTANCE_ID"],
    include_tools={"beeos_computer_info", "beeos_mobile_info"},
) as toolkit:
    beeos_node = ToolNode(toolkit.get_tools())
    # Build, compile, and invoke the graph while the toolkit remains open.

JavaScript 版本使用 @langchain/langgraph：

import { ToolNode } from "@langchain/langgraph/prebuilt";
import { createBeeOSTools } from "@beeos-ai/langchain";

const instanceId = process.env.BEEOS_INSTANCE_ID;
if (!instanceId) throw new Error("BEEOS_INSTANCE_ID is required");

const beeosNode = new ToolNode(
  createBeeOSTools({
    instanceId,
    includeTools: ["beeos_computer_info", "beeos_mobile_info"],
  }),
);

有关检查点、长时间运行的 BeeOS 任务、取消和恢复，参见 LangGraph 工作流。

目标与读取权限

设置	默认值	效果
`instance_id`	None	配置后启用固定目标的实例、计算机和移动设备工具
`agent_id`	None	配置后启用固定目标的智能体任务工具
`include_instance_list`	`False`	默认不向模型公开账户级实例发现
`include_tools`	其他条件允许的全部工具	应用最终工具允许列表，只能移除能力

JavaScript 与 TypeScript 使用对应的 camelCase 名称：instanceId、agentId、 includeInstanceList 和 includeTools。由于目标 ID 不会出现在工具 schema 中，模型不能将操作重定向到其他实例或智能体。只有工作流确实需要时，才启用账户级发现：

with BeeOSToolkit(include_instance_list=True) as toolkit:
    tools = toolkit.get_tools()

显式启用副作用

每个写操作都需要设置 allow_mutations=True，并配置至少一个匹配的修改权限范围：

范围	启用的操作
`device`	桌面指针、滚动、输入和按键；移动端点击、手势、输入、按钮和打开应用
`tasks`	创建和取消持久智能体任务
`instance_lifecycle`	启动、停止和重启固定实例
`deployment`	创建可能产生费用的托管实例

下面的工具包只公开移动设备状态和点击操作：

import os

from langchain_beeos import BeeOSToolkit


with BeeOSToolkit(
    instance_id=os.environ["BEEOS_INSTANCE_ID"],
    allow_mutations=True,
    mutation_scopes={"device"},
    include_tools={"beeos_mobile_info", "beeos_mobile_tap"},
) as toolkit:
    tools = toolkit.get_tools()

include_tools 可以缩小可用工具集合，但不能授予缺失的目标或权限。销毁实例还需要在 instance_lifecycle 范围之外设置 allow_destructive=True。对应的 JavaScript 配置为：

const instanceId = process.env.BEEOS_INSTANCE_ID;
if (!instanceId) throw new Error("BEEOS_INSTANCE_ID is required");

const toolkit = new BeeOSToolkit({
  instanceId,
  allowMutations: true,
  mutationScopes: ["device"],
  includeTools: ["beeos_mobile_info", "beeos_mobile_tap"],
});

永久销毁还需要设置 allowDestructive: true。

购买、发送消息、修改账户、安装、删除和其他会产生外部后果的操作必须保留人工确认。工具包参数限制公开哪些工具，但用户授权和策略执行仍由应用负责。

截图隐私

默认的 screenshot_mode="metadata" 会先移除短期下载 URL，再将截图结果返回给模型。返回内容只有 BeeOS 文件 ID、格式、宽度和高度。只有模型必须查看屏幕时，才显式启用多模态输出：

with BeeOSToolkit(
    instance_id=os.environ["BEEOS_INSTANCE_ID"],
    screenshot_mode="multimodal",
    include_tools={"beeos_computer_screenshot"},
) as toolkit:
    tools = toolkit.get_tools()

多模态模式会把授权截图 URL 和屏幕内容发送到模型工具循环。模型提供方、消息历史、 LangGraph 检查点存储和追踪系统可能保留这些内容。只使用可信提供方，并配置合适的数据保留策略。

使用调用方管理的 BeeOS 客户端

create_beeos_tools 可以接收已有的 beeos.BeeOS 客户端。返回工具的整个生命周期内必须保持客户端开启：

import os

from beeos import BeeOS
from langchain_beeos import create_beeos_tools


with BeeOS() as client:
    tools = create_beeos_tools(
        client=client,
        instance_id=os.environ["BEEOS_INSTANCE_ID"],
    )
    # Build and invoke the Agent or graph inside this block.

应用已经管理 BeeOS 客户端时使用这种方式，否则优先将 BeeOSToolkit 用作上下文管理器。 JavaScript 应用也可以复用调用方管理的官方 SDK 客户端：

import { BeeOSClient } from "@beeos-ai/sdk/facade";
import { createBeeOSTools } from "@beeos-ai/langchain";

const client = new BeeOSClient();
const tools = createBeeOSTools({ client, instanceId: "inst_example" });

失败与重试语义

集成不会自动重试设备修改操作。
超时表示结果可能未知，不代表操作没有执行。
取消异步调用方不能停止已经在线程中运行的同步设备请求。
应用可能重试任务创建时，传入稳定的 idempotency_key。
返回给模型的 API 错误不会包含响应正文、Header、签名 URL 或私有诊断信息。

后续阅读

LangGraph 工作流

将图状态和检查点与持久 BeeOS 任务结合。

MCP 集成

将 BeeOS 连接到任何支持 MCP 客户端的框架。

Python SDK

从确定性的应用代码直接调用 BeeOS 控制面。

快速开始

指南

架构

A2A 协议

MCP

集成

SDK

参考

LangChain 与 LangGraph

选择接入面

安装和配置

创建只读 LangChain 智能体

创建只读 JavaScript 智能体

在 LangGraph 中使用工具

目标与读取权限

显式启用副作用

截图隐私

使用调用方管理的 BeeOS 客户端

失败与重试语义

后续阅读

LangGraph 工作流

MCP 集成

Python SDK

​选择接入面

​安装和配置

​创建只读 LangChain 智能体

​创建只读 JavaScript 智能体

​在 LangGraph 中使用工具

​目标与读取权限

​显式启用副作用

​截图隐私

​使用调用方管理的 BeeOS 客户端

​失败与重试语义

​后续阅读

LangGraph 工作流

MCP 集成

Python SDK

选择接入面

安装和配置

创建只读 LangChain 智能体

创建只读 JavaScript 智能体

在 LangGraph 中使用工具

目标与读取权限

显式启用副作用

截图隐私

使用调用方管理的 BeeOS 客户端

失败与重试语义

后续阅读