LangChain Integration Python

Add Heed human-in-the-loop approval to any LangChain tool with a single decorator. Before your agent executes a consequential action, Heed intercepts it and waits for human approval — no manual polling code required.

Prerequisites

Quick Start

pip install "heed[langchain]" langchain langchain-openai

export HEED_API_KEY="hd_live_your_key_here"
export OPENAI_API_KEY="sk-your-openai-key"

curl -X POST https://heed.run/api/v1/hitl/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $HEED_API_KEY" \
  -d '{
    "name": "gate-emails",
    "description": "Require approval before sending emails",
    "rules": [
      {
        "action": "send_email",
        "requires_approval": true
      }
    ],
    "is_active": true
  }'

Complete Example

This agent can send emails, but every send_email action is gated by Heed. The @heed_gate decorator wraps your LangChain tool and blocks execution until a human approves or rejects. No manual polling code needed.

"""
LangChain + Heed: Gate send_email behind human approval.

The @heed_gate decorator wraps any LangChain @tool. When the agent
calls the tool, Heed checks your policy. If approval is required,
execution blocks until a human decides. If auto-approved by policy,
the tool runs immediately.

Requires: pip install "heed[langchain]" langchain langchain-openai
"""

import os
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate
from heed.langchain import heed_gate, inject_heed_config

# Step 1: Wrap your tool with @heed_gate
@heed_gate(
    action="send_email",
    mode="hitl_gate",             # or "grace_period" for auto-approve after timeout
    summary_template="Send email to {to}: {subject}",
    context_fields=["to", "subject"],
)
@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email to a recipient."""
    # This only executes AFTER human approval
    return f"Email sent to {to}: [{subject}] {body}"

# Step 2: Inject Heed credentials into your agent config
config = inject_heed_config({}, api_key=os.environ["HEED_API_KEY"])

# Step 3: Build your agent normally
llm = ChatOpenAI(model="gpt-4o", temperature=0)

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are an email assistant. Use send_email to send emails."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, [send_email], prompt)
agent_executor = AgentExecutor(agent=agent, tools=[send_email], verbose=True)

# Step 4: Run with Heed config
result = agent_executor.invoke(
    {"input": "Send an email to alice@example.com about the Q3 report"},
    config=config,
)
print(result["output"])

How It Works

1. You add @heed_gate above your @tool — that's the only code change
2. When the agent calls the gated tool, GatedTool submits a HITL request to Heed
3. Heed checks your policy → if the action requires approval, execution blocks until a human decides
4. If auto-approved by policy, the tool runs immediately (zero latency)
5. If approved by human, the tool executes normally
6. If denied or expired, the tool raises HeedError — the agent knows to stop

Callback Handler (LangGraph)

For LangGraph or agents where you can't modify tool definitions, use HeedCallbackHandler to intercept tool calls at the callback level:

from heed.langchain import HeedCallbackHandler

handler = HeedCallbackHandler(
    api_key=os.environ["HEED_API_KEY"],
    gated_tools={
        "delete_record": {"action": "delete_record", "mode": "hitl_gate"},
        "send_email": {
            "action": "send_email",
            "mode": "grace_period",
            "grace_seconds": 30,
            "summary_template": "Send email to {to}: {subject}",
        },
    },
)

# Ungated tools pass through automatically
result = graph.invoke(
    {"messages": [HumanMessage("Delete record 42")]},
    config={"callbacks": [handler]},
)

Approval Modes

API Reference

heed_gate decorator

HeedCallbackHandler

inject_heed_config

Injects Heed credentials into a RunnableConfig so gated tools can find them:

config = inject_heed_config(
    {"configurable": {"thread_id": "user-1"}},
    api_key="hd_live_abc123",
)
# config["configurable"]["heed_api_key"] == "hd_live_abc123"

Next Steps

• Full API documentation — all endpoints, authentication, webhook signing
• Swagger UI — interactive API explorer
• More integration guides — Claude Code / MCP, OpenAI Agents SDK
• SDK source — read the code, open issues