langchain-claude-agent-sdk-adapter

LangChain adapter for Claude Agent SDK with automatic LangSmith tracing and LangGraph integration.

Installation

npm install langchain-claude-agent-sdk-adapter
# or
pnpm add langchain-claude-agent-sdk-adapter

Features

• 8 LangChain Tools: Read, Write, Edit, Bash, Glob, Grep, Task, Agent
• Automatic LangSmith Tracing: All executions traced for observability
• LangGraph Integration: Pre-built state schemas and workflow factories
• Streaming Support: Stream agent responses in real-time
• TypeScript First: Full type safety with Zod schemas

Quick Start

Basic Tools

import { createAgentSDKTools } from "langchain-claude-agent-sdk-adapter";

const tools = createAgentSDKTools({
  permissionMode: "bypassPermissions",
});

// Use individual tools
const content = await tools.read.invoke({ filePath: "/path/to/file.ts" });
const output = await tools.bash.invoke({ command: "ls -la" });
const files = await tools.glob.invoke({ pattern: "**/*.ts" });

// Use all tools with a LangChain agent
const allTools = tools.all;

Agent Executor

import { createAgentExecutor } from "langchain-claude-agent-sdk-adapter";

const executor = createAgentExecutor({
  langsmithProject: "my-project",
  systemPromptPrefix: "You are a helpful coding assistant.",
});

const result = await executor.execute("Read and summarize /src/index.ts");
console.log(result.result);
console.log(`Trace ID: ${result.traceId}`);

LangSmith Tracing

import { withLangSmithTracing, createAgentSDKTools } from "langchain-claude-agent-sdk-adapter";

// Set environment variables:
// LANGSMITH_API_KEY=your-api-key
// LANGSMITH_PROJECT=my-project

const { callbacks, tracer } = withLangSmithTracing({
  projectName: "my-traces",
  tags: ["production"],
});

// All tool calls are automatically traced
const tools = createAgentSDKTools({ enableTracing: true });

LangGraph Workflows

import { createAgentWorkflow, createToolRoutingWorkflow } from "langchain-claude-agent-sdk-adapter";

// Simple agent workflow
const workflow = createAgentWorkflow({
  executor: { langsmithProject: "my-project" },
  checkpointerPath: "./checkpoints.db",
});

const result = await workflow.invoke(
  { input: "Analyze this codebase" },
  { configurable: { thread_id: "session-1" } }
);

// Tool routing workflow (routes based on prefix)
const router = createToolRoutingWorkflow();
await router.invoke({ input: "bash:echo Hello" }); // Routes to bash
await router.invoke({ input: "read:/path/file" }); // Routes to read
await router.invoke({ input: "Complex task" });    // Routes to agent

API Reference

Tools

| Tool | Description | |------|-------------| | read | Read files from the filesystem | | write | Write content to files | | edit | Find and replace in files | | bash | Execute shell commands | | glob | Find files by pattern | | grep | Search files with regex | | task | Spawn sub-agent tasks | | agent | Full agent execution |

Exports

// Tool factory
import { createAgentSDKTools, createToolSubset } from "langchain-claude-agent-sdk-adapter";

// Individual tool factories
import { readTool, writeTool, editTool, bashTool, globTool, grepTool, taskTool, agentTool } from "langchain-claude-agent-sdk-adapter";

// Executor
import { AgentExecutor, createAgentExecutor } from "langchain-claude-agent-sdk-adapter";

// Tracing
import { AgentSDKTracer, AgentSDKCallbackHandler, withLangSmithTracing } from "langchain-claude-agent-sdk-adapter";

// LangGraph
import {
  AgentSDKState,
  createAgentNode,
  createToolNode,
  createAgentWorkflow,
  createToolRoutingWorkflow
} from "langchain-claude-agent-sdk-adapter";

// Types
import type { AgentSDKConfig, ToolConfig, ExecutorConfig, AgentResult } from "langchain-claude-agent-sdk-adapter";

Configuration

ToolConfig

interface ToolConfig {
  permissionMode?: "ask" | "bypassPermissions";
  allowedTools?: string[];
  enableTracing?: boolean;
  metadata?: Record<string, unknown>;
}

ExecutorConfig

interface ExecutorConfig {
  permissionMode?: "ask" | "bypassPermissions";
  langsmithProject?: string;
  streaming?: boolean;
  systemPromptPrefix?: string;
  tags?: string[];
}

TracingConfig

interface TracingConfig {
  apiKey?: string;           // Defaults to LANGSMITH_API_KEY
  projectName?: string;      // Defaults to LANGSMITH_PROJECT
  metadata?: Record<string, unknown>;
  tags?: string[];
}

Examples

See the examples directory for complete usage examples:

• basic-tools.ts - Using individual tools
• agent-executor.ts - High-level agent execution
• with-langsmith.ts - LangSmith tracing integration
• langgraph-workflow.ts - LangGraph workflow patterns

Requirements

• Node.js >= 18
• Claude Agent SDK (@anthropic-ai/claude-agent-sdk)

License

MIT