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:
Parameter | Type | Description |
---|---|---|
config | LangGraphAdapterConfig | Configuration 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:
Parameter | Type | Description |
---|---|---|
params.model | string | Model name (must be 'thread' ) |
params.data | T | Thread data including metadata |
params.select | string[] | 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:
Parameter | Type | Description |
---|---|---|
params.model | string | Model name (must be 'thread' ) |
params.where | Where[] | Array of conditions (must include id ) |
params.select | string[] | 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:
Parameter | Type | Description |
---|---|---|
params.model | string | Model name (must be 'thread' ) |
params.where | Where[] | Optional filter conditions |
params.limit | number | Maximum results (default: 20) |
params.offset | number | Pagination offset (default: 0) |
params.sortBy | SortBy | Sort 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:
Parameter | Type | Description |
---|---|---|
params.model | string | Model name (must be 'thread' ) |
params.where | Where[] | Conditions including thread ID |
params.data | Partial<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:
Parameter | Type | Description |
---|---|---|
params.model | string | Model name (must be 'thread' ) |
params.where | Where[] | 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:
Parameter | Type | Description |
---|---|---|
params.model | string | Model name (must be 'thread' ) |
params.where | Where[] | 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:
Parameter | Type | Description |
---|---|---|
model | string | Model 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:
Parameter | Type | Description |
---|---|---|
config | LangGraphAdapterConfig | Configuration 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:
Property | Type | Required | Description |
---|---|---|---|
apiUrl | string | Yes | LangGraph Cloud API URL |
apiKey | string | Yes | LangSmith API key for authentication |
assistantId | string | No | Optional assistant ID for runs |
defaultHeaders | Record<string, string> | No | Additional headers for API requests |
Inherited from AdapterConfig:
Property | Type | Default | Description |
---|---|---|---|
usePlural | boolean | false | Use plural table names |
debugLogs | boolean | false | Enable debug logging |
mapKeysInput | Record<string, string> | - | Map field names on input |
mapKeysOutput | Record<string, string> | - | Map field names on output |
generateId | () => string | UUID v4 | Custom ID generator |
disableIdGeneration | boolean | false | Disable 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
-
Model Support: Only the
thread
model is supported. Other models likeuser
andfeedback
are not implemented. -
Query Operators: Only basic equality checks are supported. Advanced operators like
contains
,starts_with
, etc. are not implemented. -
Sorting: The LangGraph search API doesn't support sorting, so
sortBy
parameters are ignored. -
Count Performance: The
count
method fetches all matching threads (up to 1000) to calculate the count. -
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' },
});