LangChain and LangGraph

BeeOS provides native integrations for both LangChain languages: langchain-beeos for Python and @beeos-ai/langchain for JavaScript and TypeScript. They turn fixed BeeOS instances, Agents, computers, and mobile devices into standard LangChain tools. LangGraph accepts the same tools through ToolNode, so separate LangGraph packages are not required.

langchain-beeos and @beeos-ai/langchain 0.1.0 are in release preparation and are not yet available on PyPI or npm. The install commands below become valid with the first package releases.

Choose the integration surface

Need	Recommended surface	Why
Build a Python LangChain or LangGraph application	`langchain-beeos`	Typed tools, fixed targets, explicit mutation scopes, and Python lifecycle management
Build a Node.js LangChain.js or LangGraph.js application	`@beeos-ai/langchain`	Typed tools, fixed targets, explicit mutation scopes, and the official TypeScript SDK
Let any MCP-capable framework discover remote tools	MCP	No framework-specific BeeOS package is required
Build deterministic orchestration outside model tool selection	BeeOS Python SDK or OpenAPI	The application owns retries, task state, and control flow

Use langchain-beeos when BeeOS actions should participate in a LangChain or LangGraph tool loop. Use MCP for a protocol-level connection, and use the BeeOS SDK directly for deterministic control-plane code.

Install and configure

Install the packages

This example uses the OpenAI LangChain integration as its model provider. Replace it with any compatible LangChain chat model.

pip install langchain-beeos langchain langgraph langchain-openai

Set credentials

Keep credentials outside source control.

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"

Choose fixed targets

Pass instance_id for instance, computer, and mobile tools. Pass agent_id for durable Agent task tools. These resource IDs are application configuration and are not exposed as model-generated tool arguments.

For JavaScript or TypeScript on server-side Node.js 22.12 or newer:

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

Add langchain, @langchain/langgraph, and a model-provider package according to your application. Keep BEEOS_API_KEY on the server; do not include this integration or its credentials in a browser bundle.

Create a read-only LangChain agent

The default toolkit exposes only read operations for configured targets. This example lets the model inspect device status without giving it input control:

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.",
                }
            ]
        }
    )

Keep Agent construction and invocation inside the with block. The toolkit owns its BeeOS client in this form and closes it when the block exits.

Create a read-only JavaScript agent

The JavaScript/TypeScript package uses camelCase configuration while preserving the same safety policy:

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." }],
});

Use the tools in LangGraph

LangGraph’s prebuilt ToolNode consumes the same standard LangChain tools:

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.

The JavaScript equivalent uses @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"],
  }),
);

For checkpointing, long-running BeeOS tasks, cancellation, and recovery, see LangGraph workflows.

Targets and read access

Setting	Default	Effect
`instance_id`	None	Enables fixed-target instance, computer, and mobile tools when configured
`agent_id`	None	Enables fixed-target Agent task tools when configured
`include_instance_list`	`False`	Keeps account-wide instance discovery away from the model
`include_tools`	All otherwise permitted tools	Applies a final allowlist that can only remove capabilities

JavaScript and TypeScript use the corresponding camelCase names: instanceId, agentId, includeInstanceList, and includeTools. The model cannot redirect an action to a different instance or Agent because target IDs do not appear in the tool schemas. Enable account-wide discovery only when a workflow genuinely needs it:

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

Enable side effects deliberately

Every write requires allow_mutations=True and at least one matching mutation scope:

Scope	Enabled actions
`device`	Desktop pointer, scrolling, typing and keys; mobile taps, gestures, typing, buttons, and app launch
`tasks`	Create and cancel durable Agent tasks
`instance_lifecycle`	Start, stop, and restart the fixed instance
`deployment`	Create a new, potentially billable managed instance

The following toolkit exposes only mobile status and tap actions:

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 can narrow the available tools, but it cannot grant a missing target or permission. Instance destruction additionally requires allow_destructive=True together with the instance_lifecycle scope. The equivalent JavaScript configuration is:

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"],
});

Permanent destruction additionally requires allowDestructive: true.

Keep human confirmation around purchases, messages, account changes, installation, deletion, and other actions with external consequences. Toolkit flags limit which tools are exposed; the application still owns user authorization and policy enforcement.

Screenshot privacy

The default screenshot_mode="metadata" removes the short-lived download URL before returning a screenshot result to the model. Only the BeeOS file ID, format, width, and height are returned. Explicitly enable multimodal output only when the model must inspect the screen:

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

Multimodal mode sends an authorized screenshot URL and screen content into the model tool loop. The model provider, message history, LangGraph checkpoint store, and tracing system may retain them. Use trusted providers and an appropriate retention policy.

Use a caller-owned BeeOS client

create_beeos_tools accepts an existing beeos.BeeOS client. Keep the client open for the complete lifetime of the returned tools:

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.

Use this form when the application already manages a BeeOS client. Otherwise, prefer BeeOSToolkit as a context manager. JavaScript applications can reuse a caller-owned official SDK client too:

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

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

Failure and retry semantics

The integration does not transparently retry device mutations.
A timeout means the outcome may be unknown; it does not prove that an action did not execute.
Cancelling an async caller cannot stop a synchronous device request that is already running in its worker thread.
Pass a stable idempotency_key when task creation may be retried by the application.
API errors returned to the model omit response bodies, headers, signed URLs, and private diagnostics.

Next steps

LangGraph workflows

Combine graph state and checkpoints with durable BeeOS tasks.

MCP integration

Connect BeeOS to any framework with an MCP client.

Python SDK

Call the BeeOS control plane directly from deterministic application code.

Getting Started

Guides

Architecture

A2A Protocol

MCP

Integrations

SDKs

Reference

LangChain and LangGraph

Choose the integration surface

Install and configure

Create a read-only LangChain agent

Create a read-only JavaScript agent

Use the tools in LangGraph

Targets and read access

Enable side effects deliberately

Screenshot privacy

Use a caller-owned BeeOS client

Failure and retry semantics

Next steps

LangGraph workflows

MCP integration

Python SDK

​Choose the integration surface

​Install and configure

​Create a read-only LangChain agent

​Create a read-only JavaScript agent

​Use the tools in LangGraph

​Targets and read access

​Enable side effects deliberately

​Screenshot privacy

​Use a caller-owned BeeOS client

​Failure and retry semantics

​Next steps

LangGraph workflows

MCP integration

Python SDK

Choose the integration surface

Install and configure

Create a read-only LangChain agent

Create a read-only JavaScript agent

Use the tools in LangGraph

Targets and read access

Enable side effects deliberately

Screenshot privacy

Use a caller-owned BeeOS client

Failure and retry semantics

Next steps