Assistants Management

/**
 * Get an assistant by ID
 * @param assistantId - The ID of the assistant
 * @returns Assistant configuration and metadata
 */
get(assistantId: string): Promise<Assistant>;

interface Assistant {
  /** The ID of the assistant */
  assistant_id: string;
  /** The ID of the graph */
  graph_id: string;
  /** Assistant configuration */
  config: Config;
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at: string;
  /** Optional assistant name */
  name?: string;
  /** Optional assistant description */
  description?: string;
  /** Additional metadata */
  metadata?: Metadata;
}

const assistant = await client.assistants.get("assistant-123");
console.log(`Assistant: ${assistant.name}`);
console.log(`Graph ID: ${assistant.graph_id}`);
console.log(`Created: ${assistant.created_at}`);

/**
 * Create a new assistant
 * @param payload - Assistant creation configuration
 * @returns The created assistant
 */
create(payload: CreateAssistantPayload): Promise<Assistant>;

interface CreateAssistantPayload {
  /** ID of the graph to use for this assistant */
  graphId: string;
  /** Optional assistant configuration */
  config?: Config;
  /** Optional metadata for the assistant */
  metadata?: Metadata;
  /** Optional specific assistant ID (if not provided, will be generated) */
  assistantId?: string;
  /** Behavior when assistant with same ID already exists */
  ifExists?: OnConflictBehavior;
  /** Optional name for the assistant */
  name?: string;
  /** Optional description */
  description?: string;
}

type OnConflictBehavior = "raise" | "do_nothing";

// Create assistant with minimal configuration
const assistant = await client.assistants.create({
  graphId: "my-graph-id",
  name: "My Assistant",
  description: "Helpful AI assistant"
});

// Create assistant with custom configuration
const assistant = await client.assistants.create({
  graphId: "my-graph-id",
  assistantId: "custom-assistant-id",
  config: {
    recursion_limit: 50,
    configurable: {
      model: "gpt-4",
      temperature: 0.7
    }
  },
  metadata: {
    team: "ai-team",
    version: "1.0"
  },
  ifExists: "do_nothing"
});

/**
 * Update an assistant
 * @param assistantId - ID of the assistant to update
 * @param payload - Update configuration
 * @returns The updated assistant
 */
update(assistantId: string, payload: UpdateAssistantPayload): Promise<Assistant>;

interface UpdateAssistantPayload {
  /** New graph ID (optional) */
  graphId?: string;
  /** Updated configuration (optional) */
  config?: Config;
  /** Updated metadata (optional) */
  metadata?: Metadata;
  /** Updated name (optional) */
  name?: string;
  /** Updated description (optional) */
  description?: string;
}

// Update assistant name and description
const updated = await client.assistants.update("assistant-123", {
  name: "Updated Assistant Name",
  description: "Updated description"
});

// Update configuration
const updated = await client.assistants.update("assistant-123", {
  config: {
    recursion_limit: 100,
    configurable: {
      model: "gpt-4-turbo",
      temperature: 0.8
    }
  }
});

/**
 * Delete an assistant
 * @param assistantId - ID of the assistant to delete
 */
delete(assistantId: string): Promise<void>;

await client.assistants.delete("assistant-123");
console.log("Assistant deleted successfully");

/**
 * Search assistants with optional filtering
 * @param query - Search criteria and pagination options
 * @returns List of matching assistants
 */
search(query?: AssistantSearchQuery): Promise<Assistant[]>;

interface AssistantSearchQuery {
  /** Filter by graph ID */
  graphId?: string;
  /** Filter by metadata */
  metadata?: Metadata;
  /** Maximum number of results (default: 10) */
  limit?: number;
  /** Number of results to skip (default: 0) */
  offset?: number;
  /** Sort field */
  sortBy?: AssistantSortBy;
  /** Sort order */
  sortOrder?: SortOrder;
}

type AssistantSortBy = "created_at" | "updated_at" | "name";
type SortOrder = "asc" | "desc";

// Get all assistants
const allAssistants = await client.assistants.search();

// Search with filters
const assistants = await client.assistants.search({
  graphId: "my-graph-id",
  limit: 20,
  sortBy: "created_at",
  sortOrder: "desc"
});

// Search by metadata
const teamAssistants = await client.assistants.search({
  metadata: { team: "ai-team" },
  limit: 50
});

/**
 * Get the JSON representation of the graph assigned to an assistant
 * @param assistantId - The ID of the assistant
 * @param options - Graph retrieval options
 * @returns Serialized graph representation
 */
getGraph(assistantId: string, options?: GraphOptions): Promise<AssistantGraph>;

interface GraphOptions {
  /** Whether to include subgraphs in the serialized representation.
   * If a number, only subgraphs with depth <= value are included */
  xray?: boolean | number;
}

interface AssistantGraph {
  /** Graph nodes and their connections */
  nodes: GraphNode[];
  /** Graph edges defining flow */
  edges: GraphEdge[];
  /** Graph metadata */
  metadata?: Record<string, any>;
}

// Get basic graph structure
const graph = await client.assistants.getGraph("assistant-123");
console.log(`Graph has ${graph.nodes.length} nodes`);

// Get graph with subgraph details
const detailedGraph = await client.assistants.getGraph("assistant-123", {
  xray: true
});

// Get graph with limited subgraph depth
const limitedGraph = await client.assistants.getGraph("assistant-123", {
  xray: 2 // Only include subgraphs up to depth 2
});

/**
 * Get the state and config schema of the graph assigned to an assistant
 * @param assistantId - The ID of the assistant
 * @returns Graph schema with JSON schemas for input, output, state, and config
 */
getSchemas(assistantId: string): Promise<GraphSchema>;

interface GraphSchema {
  /** The ID of the graph */
  graph_id: string;
  /** Schema for input state (JSON Schema format) */
  input_schema?: JSONSchema7 | null;
  /** Schema for output state (JSON Schema format) */
  output_schema?: JSONSchema7 | null;
  /** Schema for graph state (JSON Schema format) */
  state_schema?: JSONSchema7 | null;
  /** Schema for graph config (JSON Schema format) */
  config_schema?: JSONSchema7 | null;
}

const schemas = await client.assistants.getSchemas("assistant-123");

if (schemas.input_schema) {
  console.log("Input schema:", JSON.stringify(schemas.input_schema, null, 2));
}

if (schemas.state_schema) {
  console.log("State schema:", JSON.stringify(schemas.state_schema, null, 2));
}

/**
 * Get the subgraphs of an assistant
 * @param assistantId - The ID of the assistant
 * @param options - Subgraph retrieval options
 * @returns The subgraphs of the assistant
 */
getSubgraphs(assistantId: string, options?: SubgraphOptions): Promise<Subgraphs>;

interface SubgraphOptions {
  /** Specific namespace to retrieve */
  namespace?: string;
  /** Whether to recursively include nested subgraphs */
  recurse?: boolean;
}

type Subgraphs = Record<string, GraphSchema>;

// Get all subgraphs
const subgraphs = await client.assistants.getSubgraphs("assistant-123");
console.log("Available subgraphs:", Object.keys(subgraphs));

// Get specific namespace
const authSubgraph = await client.assistants.getSubgraphs("assistant-123", {
  namespace: "auth"
});

// Get with recursive expansion
const allSubgraphs = await client.assistants.getSubgraphs("assistant-123", {
  recurse: true
});

/**
 * List all versions of an assistant
 * @param assistantId - ID of the assistant
 * @param payload - Version listing options
 * @returns List of assistant versions
 */
getVersions(assistantId: string, payload?: GetVersionsPayload): Promise<AssistantVersion[]>;

/**
 * Change the active version of an assistant
 * @param assistantId - ID of the assistant
 * @param version - The version number to set as latest
 * @returns The updated assistant
 */
setLatest(assistantId: string, version: number): Promise<Assistant>;

interface GetVersionsPayload {
  /** Filter by metadata */
  metadata?: Metadata;
  /** Maximum number of versions to return (default: 10) */
  limit?: number;
  /** Number of versions to skip (default: 0) */
  offset?: number;
}

interface AssistantVersion {
  /** Version number */
  version: number;
  /** Assistant ID */
  assistant_id: string;
  /** Graph ID for this version */
  graph_id: string;
  /** Configuration for this version */
  config: Config;
  /** Version creation timestamp */
  created_at: string;
  /** Version metadata */
  metadata?: Metadata;
}

// Get all versions
const versions = await client.assistants.getVersions("assistant-123");
console.log(`Assistant has ${versions.length} versions`);

// Get recent versions
const recentVersions = await client.assistants.getVersions("assistant-123", {
  limit: 5
});

// Set specific version as latest
await client.assistants.setLatest("assistant-123", 3);

// Rollback to previous version
const versions = await client.assistants.getVersions("assistant-123", { limit: 2 });
if (versions.length > 1) {
  await client.assistants.setLatest("assistant-123", versions[1].version);
}

interface Config {
  /** Tags for this assistant and any sub-calls */
  tags?: string[];
  /** Maximum number of times a call can recurse (default: 25) */
  recursion_limit?: number;
  /** Runtime values for configurable attributes */
  configurable?: {
    /** ID of the thread */
    thread_id?: string | null;
    /** Timestamp of the state checkpoint */
    checkpoint_id?: string | null;
    [key: string]: unknown;
  };
}

type Metadata = {
  source?: "input" | "loop" | "update" | string;
  step?: number;
  writes?: Record<string, unknown> | null;
  parents?: Record<string, string>;
  [key: string]: unknown;
} | null | undefined;

try {
  const assistant = await client.assistants.get("nonexistent-id");
} catch (error) {
  if (error.status === 404) {
    console.error("Assistant not found");
  } else if (error.status === 403) {
    console.error("Access denied");
  } else {
    console.error("Unexpected error:", error.message);
  }
}