Agent Inbox

The Agent Inbox uses a specific schema to facilitate human-in-the-loop interactions.

Interrupt Fields (HumanInterrupt)

• action_request: Contains the action (header text) and args (e.g., tool call arguments).
• config: Controls which actions are available to the user via allow_ignore, allow_respond, allow_edit, and allow_accept.
• description: A detailed string (supports Markdown) providing context or instructions.

Response Types (HumanResponse)

When a user interacts with the inbox, the interrupt() function returns a list containing a HumanResponse object. The type determines the payload in args:

• accept: Sends an ActionRequest where all args keys are converted to strings. Matches the original action_request structure.
• edit: Sends an ActionRequest where args values are strings containing the user's edits.
• response: Sends a single string in the args field.
• ignore: Returns null for the args field.

Use the interrupt function from langgraph.types. Pass a HumanInterrupt dictionary to the function. The function returns a list of responses; access the first element to handle the user's input.

from typing import TypedDict, Literal, Optional, Union
from langgraph.types import interrupt

def my_graph_function(state: MyGraphState):
    # Extract the last tool call from the `messages` field in the state
    tool_call = state["messages"][-1].tool_calls[0]
    
    # Create an interrupt
    request: HumanInterrupt = {
        "action_request": {
            "action": tool_call['name'],
            "args": tool_call['args']
        },
        "config": {
            "allow_ignore": True,
            "allow_respond": True,
            "allow_edit": False,
            "allow_accept": False
        },
        "description": _generate_email_markdown(state) # Generate a detailed markdown description.
    }
    
    # Send the interrupt request, and extract the first response.
    # The Agent Inbox will always respond with a list of `HumanResponse` objects.
    response = interrupt(request)[0]
    
    if response['type'] == "response":
        # Do something with the response
        pass
    
    # ...rest of function

Instead of raising exceptions, use the interrupt function from @langchain/langgraph. Pass a HumanInterrupt object to the function. Note that interrupt returns an array of responses; you typically want the first element.

import { interrupt } from "@langchain/langgraph";
import { HumanInterrupt, HumanResponse } from "@langchain/langgraph/prebuilt";

function myGraphFunction(state: MyGraphState) {
  // Extract the last tool call from the `messages` field in the state
  const toolCall = state.messages[state.messages.length - 1].tool_calls[0];
  
  // Create an interrupt
  const request: HumanInterrupt = {
    action_request: {
      action: toolCall.name,
      args: toolCall.args
    },
    config: {
      allow_ignore: true,
      allow_respond: true,
      allow_edit: false,
      allow_accept: false
    },
    description: _generateEmailMarkdown(state) // Generate a detailed markdown description.
  };

  // Send the interrupt request, and extract the first response.
  // The Agent Inbox will always return an array of `HumanResponse` objects.
  const response = interrupt<HumanInterrupt, HumanResponse[]>(request)[0];
  
  if (response.type === "response") {
    // Do something with the response
  }
}

The useInboxes hook provides a complete interface for managing a collection of AgentInbox objects stored in local storage. It synchronizes the inbox state with the browser's URL query parameters and local storage, ensuring that the selected inbox is reflected in the URL.

Key Features:

• Automatic Initialization: On mount, it runs a backfill process (runInboxBackfill) and loads inboxes from local storage.
• Selection Sync: Automatically selects an inbox based on the AGENT_INBOX_PARAM in the URL. If no param is present, it selects the first available inbox or the one marked selected: true.
• Persistence: All additions, deletions, and updates are persisted to local storage using the AGENT_INBOXES_LOCAL_STORAGE_KEY.
• URL Management: Updates query parameters like AGENT_INBOX_PARAM, OFFSET_PARAM, LIMIT_PARAM, and INBOX_PARAM to maintain application state via the URL.

Returned Methods:

• getAgentInboxes(preloadedInboxes?: AgentInbox[]): Loads inboxes from storage and handles selection logic.
• addAgentInbox(agentInbox: AgentInbox): Adds a new inbox and marks it as selected.
• deleteAgentInbox(id: string): Removes an inbox by ID. If the deleted inbox was the selected one, the first remaining inbox is automatically selected.
• changeAgentInbox(id: string, replaceAll?: boolean): Switches the currently selected inbox.
• updateAgentInbox(updatedInbox: AgentInbox): Updates the properties of an existing inbox while preserving its selection state.

Note: The hook uses router.refresh() and router.push() from next/navigation to update the UI and URL without full page reloads.

import { useInboxes } from "@/components/agent-inbox/hooks/use-inboxes";

function MyComponent() {
  const { agentInboxes, addAgentInbox, changeAgentInbox } = useInboxes();

  const handleAdd = () => {
    addAgentInbox({ name: "New Agent Inbox" }); // id is automatically generated if missing
  };

  return (
    <div>
      {agentInboxes.map(inbox => (
        <button key={inbox.id} onClick={() => changeAgentInbox(inbox.id)}>
          {inbox.name} {inbox.selected ? "(Selected)" : ""}
        </button>
      ))}
      <button onClick={handleAdd}>Add Inbox</button>
    </div>
  );
}