Noxy LangChain Connector

LangChain connector for Noxy human-in-the-loop guardrails. Uses HumanInTheLoopMiddleware to pause agent tool calls, routes encrypted approval prompts to all devices registered for the identity (web, iOS, Android, Telegram), and resumes execution when Noxy fires a webhook.

Flow

sequenceDiagram
    participant A as LangChain Agent
    participant N as Noxy Relay
    participant D as User Devices
    participant S as Your Server

    A->>N: send_decision (tool approval)
    N->>D: Route to registered devices (web, iOS, Android, Telegram)
    A->>A: interrupt() — state saved to checkpointer
    Note over A: Agent suspended

    alt User responds
        D->>N: Approve / Reject
        N->>S: Webhook (outcome)
        S->>A: Command(resume=HITLResponse)
        A->>A: Continue with approved/rejected tool calls
    else Timeout
        N->>S: Webhook (timeout / expired)
        S->>A: Command(resume=reject)
        A->>A: Continue with default behaviour
    end

1. The agent proposes a guarded tool call.
2. NoxyHumanInTheLoopMiddleware routes an encrypted actionable to all devices for the identity.
3. LangChain calls interrupt() — the agent suspends and persists state via a checkpointer.
4. User responds on any registered device or the decision TTL expires.
5. Noxy fires a webhook to your server.
6. Your server calls NoxyAgentResumeHandler.resume_from_webhook() → Command(resume=...).
7. The agent continues with approved, edited, or rejected tool calls.

Requirements

• Python >= 3.10
• A LangChain agent created with create_agent and a checkpointer
• noxy-sdk credentials (NOXY_APP_TOKEN, target identity)

Target identity can be a phone number, email, user id, or wallet address (0x…).

Installation

pip install noxy-langchain

For the FastAPI webhook example:

pip install "noxy-langchain[examples]"

Local development against the monorepo SDK:

pip install -e ../../sdks/python-sdk
pip install -e ".[dev,examples]"

Quick start

import uuid

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
from noxy import NoxyConfig, init_noxy_agent_client

from noxy_langchain import NoxyLangChainBridge

@tool
def transfer_funds(to: str, amount: str) -> str:
    """Transfer funds."""
    return f"Sent {amount} to {to}"

client = init_noxy_agent_client(
    NoxyConfig(
        endpoint="https://relay.noxy.network",
        auth_token="your-app-token",
        decision_ttl_seconds=3600,
    )
)
bridge = NoxyLangChainBridge(client, "user@example.com")

agent = create_agent(
    init_chat_model("openai:gpt-4o-mini"),
    tools=[transfer_funds],
    middleware=[bridge.create_hitl_middleware({"transfer_funds": True})],
    checkpointer=InMemorySaver(),
)
resume_handler = bridge.create_resume_handler(agent)

config = {"configurable": {"thread_id": str(uuid.uuid4())}}
# agent.invoke(...) suspends when transfer_funds is proposed

# Later, in your webhook handler:
final = resume_handler.resume_from_webhook({
    "decisionId": "<decisionId>",
    "identityId": "user@example.com",
    "outcome": "approved",  # or "rejected", "expired"
})

Webhook payload

Noxy outcomes map to LangChain HITL decisions:

• approved → {"type": "approve"}
• rejected / expired / timeout → {"type": "reject", "message": "..."}

API

Examples

• examples/basic.py — middleware + webhook resume demo with a mock Noxy client
• examples/webhook_server.py — FastAPI server with /runs and /webhooks/noxy

python examples/basic.py

Development

make dev
make test
make build

License

MIT