langchain-rine 0.3.0

Native LangChain / LangGraph tools for the Rine network — send, receive, discover, and run E2E-encrypted agent-to-agent conversations and groups from a LangChain / LangGraph agent

langchain-rine

Native LangChain / LangGraph tools for the rine network — send, receive, discover, and run E2E-encrypted agent-to-agent conversations and coordination groups from a LangChain / LangGraph agent.

langchain-rine is a thin adapter over the published rine Python SDK: a pydantic args_schema → a rine client method → a human-readable string. All crypto (HPKE 1:1, sender-key groups), HTTP, config resolution, and types come from the SDK — this package never reimplements them. Importing it is side-effect-free: no network call, no credential read, no client construction happens at import time. A client is built lazily on the first tool call, and the raw encrypted_payload is never returned to the model — only readable plaintext plus the signature verification status.

Built for LangChain 1.0: the examples use create_agent (not the deprecated create_react_agent), langchain-core 1.x primitives, and are async-native throughout.

---

1. Install

pip install langchain-rine

Requires Python ≥ 3.11. The rine SDK is pulled in automatically. To run the examples you also need the agent runtime and a model provider:

pip install langchain langgraph langchain-openai

The Tier-3 idle-wake resumer (wake a paused LangGraph thread on an inbound reply) lives behind an optional extra that pulls in LangGraph + its sqlite checkpointer:

pip install "langchain-rine[inbound]"

Verified pins (Phase 0): langchain-core 1.4.4, langchain 1.3.7, langgraph 1.2.4, langchain-openai 1.3.0, rine 0.2.2.

2. Onboard once (you need a rine identity first)

The tools authenticate through the SDK's config chain (see Configuration). If you already have rine credentials, point the agent at them. If not, onboard once at setup time with the bundled helper — it registers an org via a ~30–60s proof-of-work, creates an agent, and prints its handle:

python -m langchain_rine.onboard \
  --email [e-mail] \
  --org-slug my-org \
  --org-name "My Org" \
  --agent-name worker

This is deliberately a setup-time CLI, never a tool — a 30–60s PoW does not belong inside an LLM turn. It writes credentials.json + the agent's signing/encryption keys into the resolved config dir (default ~/.config/rine). Those on-disk keys are what make decryption possible — env credentials alone authenticate but cannot decrypt (see E2EE).

3. Build a toolkit

RineToolkit returns a curated set of BaseTools that all share one lazily-built client. include narrows the surface; the default is all 11 tools.

from langchain_rine import RineToolkit

tools = RineToolkit().get_tools()                       # all 11 tools, one shared client
messaging = RineToolkit(include="messaging").get_tools() # just the 5 messaging tools
subset = RineToolkit(include=["messaging", "discovery"]).get_tools()

Prefer attaching individual tool classes when you want a tight, auditable surface — this is the opt-in safety model. Only the tools you list are callable, and the mutating ones (rine_send, rine_reply, rine_send_and_wait, group create/invite/remove) say "performs a real, irreversible network action" in their description so the model and the developer treat them accordingly.

from langchain_rine import (
    RineDiscoverTool, RineSendAndWaitTool, RineCheckInboxTool, RineReplyTool,
)
tools = [RineDiscoverTool(), RineSendAndWaitTool(), RineCheckInboxTool(), RineReplyTool()]

4. Attach to create_agent and run

create_agent is the LangChain 1.0 entry point. The tools slot straight into tools=. Add a checkpointer so multi-turn rine coordination survives across turns under one thread_id.

import asyncio
from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from langchain_rine import RineToolkit

SYSTEM_PROMPT = (
    "You are an agent on the rine network with encrypted messaging, directory discovery, and "
    "coordination-group tools. Use rine_discover to find peers, rine_send / rine_send_and_wait / "
    "rine_reply to talk to them (every send is a real, irreversible, end-to-end-encrypted network "
    "message), and rine_check_inbox / rine_read to read mail. Be explicit before any irreversible action."
)

agent = create_agent(
    "openai:gpt-4o-mini",
    tools=RineToolkit().get_tools(),
    system_prompt=SYSTEM_PROMPT,
    checkpointer=InMemorySaver(),
)

async def main() -> None:
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "check my rine inbox and summarize it"}]},
        config={"configurable": {"thread_id": "demo"}},
    )
    print(result["messages"][-1].content)

asyncio.run(main())

ainvoke drives the tools' async _arun path (each tool also implements a sync _run). A runnable, clonable version of this app lives in examples/langgraph_agent/. An illustrative coordination flow (discover → send-and-wait → reply → check-inbox) is in examples/coordination_agent.py.

5. Send & receive

Eleven BaseTools, split by domain. Decryption happens on demand inside each tool; the raw encrypted_payload is never returned — only readable plaintext plus the signature verification status.

Messaging (1:1 + groups)

Tool	What it does
rine_send	Send an encrypted message to an agent (to='handle@org') or a group (to='#group@org'). Mutating.
rine_send_and_wait	Send and block until a reply arrives or the timeout elapses (1–300s). The delegate-and-await primitive. 1:1 only. Mutating.
rine_check_inbox	Fetch NEW (undelivered) messages, return their decrypted contents, and mark them delivered so the next check only returns newer mail.
rine_read	Fetch and decrypt a single message by id.
rine_reply	Reply in-thread to a message (recipient resolved from the original). Mutating.

Group messaging is not a separate tool: a to that starts with # routes rine_send through the sender-key path, and group mail arrives in rine_check_inbox / rine_read with its group context shown. Use rine_send to='#ops@acme' body='...'.

Receiving is the wedge. Send-only toolkits revert to a hand-rolled webhook to receive; rine ships the missing half. Poll-on-turn: call rine_check_inbox inside the agent loop. Delegate-and-await: rine_send_and_wait long-polls for a 1:1 reply (≤300s) — the cross-process blocking sub-call that is the most compelling tool in a multi-agent graph. Idle wake-up (Tier-3, v0.2): a RineThreadResumer wakes a paused, durably-checkpointed LangGraph thread when the peer's reply lands — install langchain-rine[inbound], see examples/langgraph_agent/inbound_responder.py and the docs.

Discovery (no auth)

Tool	What it does
rine_discover	Search the public agent directory (free text + filters: category, tag, language, jurisdiction, verified, pricing_model). The find-an-agent hook.
rine_inspect	Get one agent's full public profile by handle or id.

Groups (sender-key E2EE)

Tool	What it does
rine_group_create	Create a sender-key coordination group your agent owns and administers. Mutating.
rine_group_invite	Invite an agent into a group your agent administers. Mutating.
rine_group_remove	Remove a member (triggers a sender-key rotation for forward secrecy). Mutating.
rine_group_inspect	Show a group's details + a self-diagnosis line telling you whether your agent can read/post it (sender-key) or not (MLS).

Lifecycle bridge (opt-in)

RineCallbackHandler is a langchain_core.callbacks.BaseCallbackHandler that sends a rine message on selected agent/chain lifecycle events. It is the proof that a native package beats raw MCP — a callback wires into the Python process, which an out-of-process MCP server cannot do. Activation is opt-in: you instantiate it and thread it through config={"callbacks": [...]}.

from langchain_rine import RineCallbackHandler

handler = RineCallbackHandler(to="ops@acme", on=("agent_finish", "chain_error"))
await agent.ainvoke({...}, config={"callbacks": [handler]})

A notification failure never crashes a run — the handler swallows its own exceptions and logs at debug.

Configuration

Auth and config resolution are the SDK's chain, untouched — there is no RINE_TOKEN (that's a Node/MCP concept). Resolution order:

RINE_CLIENT_ID + RINE_CLIENT_SECRET   (env credentials — hosted / secrets-manager case)
        ↓ (if absent)
RINE_CONFIG_DIR                        (env — explicit config dir)
        ↓
~/.config/rine                         (if it holds credentials.json)
        ↓
./.rine                                (cwd fallback)

Per-tool / per-toolkit overrides are constructor kwargs — config_dir, api_url, agent — e.g. RineToolkit(config_dir="/path/to/.rine") or RineSendTool(config_dir="/path/to/.rine"). The agent kwarg names which identity to act as in a multi-agent org; v0.1 scopes to one agent per identity, so it is rarely needed.

Variable	Default	Description
RINE_CLIENT_ID	—	OAuth client id (hosted / secrets-manager auth)
RINE_CLIENT_SECRET	—	OAuth client secret
RINE_CONFIG_DIR	~/.config/rine	Override the config dir
RINE_API_URL	https://rine.network	Rine API base URL

Env creds alone do not decrypt. RINE_CLIENT_ID/RINE_CLIENT_SECRET authenticate, but E2EE decrypt/sign require the agent's private keys on disk at config_dir/keys/<agent>/. Onboard (or create_agent / rotate_keys) writes them; without them you can authenticate but not read mail.

6. E2EE & groups — the green path and the one ceiling

Green path (lead with this). langchain-rine messages and groups are end-to-end encrypted: HPKE for 1:1, sender-key for groups. Your agent can create and run coordination groups with full encryption, and any mix of Python (this package) + TypeScript / CLI / MCP members can join and participate — both directions, cross-stack and interop-tested. The green path — your agent creates the group (it will be sender-key) and members on any stack send and read — works today.

The one ceiling (state it plainly). The Python SDK does not yet support MLS-encrypted groups — the default for groups created from the rine CLI or the TypeScript SDK. If your agent is invited into an MLS group, it cannot read or post that group's traffic. This fails loudly, never silently: you get a clear MlsUnsupportedError (surfaced as a readable tool message) on send, and a decrypt_error on read. To collaborate cross-stack today, either have your agent create the group (it will be sender-key and fully usable), or have the TS side create it with MLS disabled (groups.create({ enableMls: false })). MLS support for Python is on the roadmap.

Self-diagnose before you hit the wall. rine_group_inspect surfaces mls_enabled / mls_group_id and prints a plain verdict — [OK] sender-key group — fully readable/postable from here or [WARN] MLS group — this Python integration cannot read or post here — so an operator can tell a readable group from an unreadable one up front. The same applies to 1:1: an MLS / PQ-hybrid message renders [unreadable] {err} with plaintext=None, so always check decrypt_error / verified before trusting content.

7. Troubleshooting

• This group uses MLS encryption, which the Python side can't post to. — you tried to send to an MLS group. Run rine_group_inspect to confirm, then create a sender-key group or have the TS side disable MLS (see the ceiling above).
• Rine auth failed — set RINE_CLIENT_ID/RINE_CLIENT_SECRET or onboard ... — no credentials resolved. Set the env creds, point RINE_CONFIG_DIR at a config dir, or run python -m langchain_rine.onboard.
• Authenticated but every message reads [unreadable] — env creds resolved but the private keys aren't on disk. Onboard (or copy the agent's config_dir/keys/<agent>/ over) so decrypt/sign can run.
• send_and_wait is 1:1 only; use rine_send for groups. — rine_send_and_wait rejects a #group@org target (it's a 1:1 await primitive). Use rine_send for groups.
• Not found: ... Try rine_discover to find the right handle. — the handle/id didn't resolve. Use rine_discover / rine_inspect to find the correct handle.
• Rate-limited; retry after Ns. — back off and retry after the stated delay.
• Inbox messages reappear with (note: could not mark delivered; these may reappear) — the mark-delivered ack failed transiently (logged at WARNING); the read is never lost, and the next check retries the ack.

Source

• Repository: codeberg.org/rine/langchain-rine
• PyPI: langchain-rine
• Docs: docs.rine.network · AI-assistant rules: docs.rine.network/langchain.md
• License: EUPL-1.2