Skip to main content

API Reference

Comprehensive API documentation for the @pressw/threads-langgraph package.

Classes

LangGraphAdapter

The main adapter class that implements the ChatCoreAdapter interface from @pressw/threads.

class LangGraphAdapter extends BaseAdapter implements ChatCoreAdapter

Constructor

constructor(config: LangGraphAdapterConfig)

Creates a new instance of the LangGraph adapter.

Parameters:

ParameterTypeDescription
configLangGraphAdapterConfigConfiguration object for the adapter

Example:

const adapter = new LangGraphAdapter({
apiUrl: 'https://your-deployment.langchain.com',
apiKey: 'lsv2_pt_your_key',
assistantId: 'my-assistant',
});

Methods

create

Creates a new thread in LangGraph Cloud.

create<T extends Record<string, unknown>>(params: {
model: string;
data: T;
select?: string[];
}): Promise<T>

Parameters:

ParameterTypeDescription
params.modelstringModel name (must be 'thread')
params.dataTThread data including metadata
params.selectstring[]Optional fields to select (not used)

Returns: Promise<T> - The created thread object

Example:

const thread = await adapter.create({
model: 'thread',
data: {
title: 'Support Chat',
userId: 'user-123',
metadata: { priority: 'high' },
},
});
findOne

Retrieves a single thread by ID with access control.

findOne<T>(params: {
model: string;
where: Where[];
select?: string[];
}): Promise<T | null>

Parameters:

ParameterTypeDescription
params.modelstringModel name (must be 'thread')
params.whereWhere[]Array of conditions (must include id)
params.selectstring[]Optional fields to select (not used)

Returns: Promise<T | null> - The thread if found and accessible, null otherwise

Example:

const thread = await adapter.findOne({
model: 'thread',
where: [
{ field: 'id', value: 'thread-123' },
{ field: 'userId', value: 'user-123' },
],
});
findMany

Searches for threads matching the given criteria.

findMany<T>(params: {
model: string;
where?: Where[];
limit?: number;
offset?: number;
sortBy?: SortBy;
}): Promise<T[]>

Parameters:

ParameterTypeDescription
params.modelstringModel name (must be 'thread')
params.whereWhere[]Optional filter conditions
params.limitnumberMaximum results (default: 20)
params.offsetnumberPagination offset (default: 0)
params.sortBySortBySort configuration (not supported)

Returns: Promise<T[]> - Array of matching threads

Note: LangGraph doesn't support sorting in the search API. Results are returned in the order provided by LangGraph.

Example:

const threads = await adapter.findMany({
model: 'thread',
where: [{ field: 'userId', value: 'user-123' }],
limit: 10,
offset: 0,
});
update

Updates an existing thread's metadata.

update<T>(params: {
model: string;
where: Where[];
data: Partial<T>;
}): Promise<T | null>

Parameters:

ParameterTypeDescription
params.modelstringModel name (must be 'thread')
params.whereWhere[]Conditions including thread ID
params.dataPartial<T>Fields to update

Returns: Promise<T | null> - Updated thread or null if not found

Example:

const updated = await adapter.update({
model: 'thread',
where: [{ field: 'id', value: 'thread-123' }],
data: {
title: 'Updated Title',
metadata: { status: 'resolved' },
},
});
delete

Deletes a thread from LangGraph Cloud.

delete(params: {
model: string;
where: Where[];
}): Promise<void>

Parameters:

ParameterTypeDescription
params.modelstringModel name (must be 'thread')
params.whereWhere[]Conditions including thread ID

Throws: Error if thread not found or access denied

Example:

await adapter.delete({
model: 'thread',
where: [
{ field: 'id', value: 'thread-123' },
{ field: 'userId', value: 'user-123' },
],
});
count

Returns the number of threads matching the criteria.

count(params: {
model: string;
where?: Where[];
}): Promise<number>

Parameters:

ParameterTypeDescription
params.modelstringModel name (must be 'thread')
params.whereWhere[]Optional filter conditions

Returns: Promise<number> - Count of matching threads

Note: LangGraph doesn't have a native count API. This method fetches up to 1000 threads and returns the count.

getSchema

Returns schema information for the requested model.

getSchema(model: string): any

Parameters:

ParameterTypeDescription
modelstringModel name to get schema for

Returns: Schema object or undefined

Functions

createLangGraphAdapter

Factory function to create a new LangGraph adapter instance.

function createLangGraphAdapter(config: LangGraphAdapterConfig): LangGraphAdapter;

Parameters:

ParameterTypeDescription
configLangGraphAdapterConfigConfiguration for the adapter

Returns: A new LangGraphAdapter instance

Example:

const adapter = createLangGraphAdapter({
apiUrl: process.env.LANGGRAPH_API_URL!,
apiKey: process.env.LANGSMITH_API_KEY!,
assistantId: 'my-assistant',
debugLogs: true,
});

Types

LangGraphAdapterConfig

Configuration interface for the LangGraph adapter.

interface LangGraphAdapterConfig extends AdapterConfig {
apiUrl: string;
apiKey: string;
assistantId?: string;
defaultHeaders?: Record<string, string>;
}

Properties:

PropertyTypeRequiredDescription
apiUrlstringYesLangGraph Cloud API URL
apiKeystringYesLangSmith API key for authentication
assistantIdstringNoOptional assistant ID for runs
defaultHeadersRecord<string, string>NoAdditional headers for API requests

Inherited from AdapterConfig:

PropertyTypeDefaultDescription
usePluralbooleanfalseUse plural table names
debugLogsbooleanfalseEnable debug logging
mapKeysInputRecord<string, string>-Map field names on input
mapKeysOutputRecord<string, string>-Map field names on output
generateId() => stringUUID v4Custom ID generator
disableIdGenerationbooleanfalseDisable automatic ID generation

Thread Data Structure

The adapter maps between LangGraph's thread format and PressW's standard format:

interface Thread {
id: string;
title?: string;
userId: string;
organizationId?: string;
tenantId?: string;
metadata?: Record<string, unknown>;
createdAt: Date;
updatedAt: Date;
}

Where Clause

Filter conditions for queries:

interface Where {
field: string;
value: string | number | boolean | Date | null | string[] | number[];
operator?:
| 'eq'
| 'ne'
| 'gt'
| 'gte'
| 'lt'
| 'lte'
| 'in'
| 'contains'
| 'starts_with'
| 'ends_with';
connector?: 'AND' | 'OR';
}

Note: The LangGraph adapter currently only supports basic equality (eq) operations.

SortBy

Sorting configuration:

interface SortBy {
field: string;
direction: 'asc' | 'desc';
}

Note: Sorting is not currently supported by LangGraph's search API.

Error Handling

The adapter handles several error scenarios:

Not Found Errors

When a thread is not found, findOne and update return null:

const thread = await adapter.findOne({
model: 'thread',
where: [{ field: 'id', value: 'non-existent' }],
});
// thread === null

Access Denied Errors

The adapter enforces access control based on userId, organizationId, and tenantId:

try {
await adapter.delete({
model: 'thread',
where: [
{ field: 'id', value: 'thread-123' },
{ field: 'userId', value: 'wrong-user' },
],
});
} catch (error) {
// Error: Thread not found or access denied
}

Model Not Supported

Operations on unsupported models throw errors:

try {
await adapter.create({
model: 'user', // Only 'thread' is supported
data: { name: 'John' },
});
} catch (error) {
// Error: Model user not supported by LangGraphAdapter
}

Limitations

  1. Model Support: Only the thread model is supported. Other models like user and feedback are not implemented.

  2. Query Operators: Only basic equality checks are supported. Advanced operators like contains, starts_with, etc. are not implemented.

  3. Sorting: The LangGraph search API doesn't support sorting, so sortBy parameters are ignored.

  4. Count Performance: The count method fetches all matching threads (up to 1000) to calculate the count.

  5. Field Selection: The select parameter is not implemented as LangGraph returns complete thread objects.

Usage with ThreadUtilityClient

The adapter is designed to work seamlessly with PressW's ThreadUtilityClient:

import { ThreadUtilityClient } from '@pressw/threads';
import { createLangGraphAdapter } from '@pressw/threads-langgraph';

const adapter = createLangGraphAdapter({
apiUrl: process.env.LANGGRAPH_API_URL!,
apiKey: process.env.LANGSMITH_API_KEY!,
});

const client = new ThreadUtilityClient(adapter, async (request) => ({
userId: getUserId(request),
organizationId: getOrgId(request),
}));

// All ThreadUtilityClient methods work normally
const thread = await client.createThread(request, {
title: 'New Thread',
metadata: { source: 'api' },
});