Error Handling

/**
 * Thrown when attempting to bind structured output to a model that already has tools bound
 */
class MultipleToolsBoundError extends Error {
  name: "MultipleToolsBoundError";
  message: "The model already has tools bound to it. Cannot bind structured output format.";
}

/**
 * Thrown when multiple structured outputs are returned but only one was expected
 */
class MultipleStructuredOutputsError extends Error {
  name: "MultipleStructuredOutputsError";
  message: "Multiple structured outputs returned when one was expected";
  outputs: any[];
}

/**
 * Thrown when structured output parsing fails
 */
class StructuredOutputParsingError extends Error {
  name: "StructuredOutputParsingError";
  message: string;
  cause?: Error;
  rawOutput?: string;
}

/**
 * Thrown when tool invocation fails
 */
class ToolInvocationError extends Error {
  name: "ToolInvocationError";
  message: string;
  toolName: string;
  toolInput: any;
  cause?: Error;
}

/**
 * Thrown when tool call limit is exceeded
 */
class ToolCallLimitExceededError extends Error {
  name: "ToolCallLimitExceededError";
  limit: number;
  actualCalls: number;
}

/**
 * Thrown when PII detection fails
 */
class PIIDetectionError extends Error {
  name: "PIIDetectionError";
  cause?: Error;
}

import { createAgent, ToolInvocationError } from "langchain";

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [/* tools */],
});

try {
  const result = await agent.invoke({
    messages: [{ role: "user", content: "Do something" }],
  });
} catch (error) {
  if (error instanceof ToolInvocationError) {
    console.error(`Tool ${error.toolName} failed:`, error.message);
    console.error("Input:", error.toolInput);
    console.error("Cause:", error.cause);
  } else {
    console.error("Unknown error:", error);
  }
}

import {
  createAgent,
  StructuredOutputParsingError,
  MultipleStructuredOutputsError,
} from "langchain";
import { z } from "zod";

const Schema = z.object({
  value: z.number(),
  label: z.string(),
});

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [],
  responseFormat: Schema,
});

try {
  const result = await agent.invoke({
    messages: [{ role: "user", content: "Parse this data" }],
  });

  console.log(result.structuredResponse);
} catch (error) {
  if (error instanceof StructuredOutputParsingError) {
    console.error("Failed to parse structured output:");
    console.error("Message:", error.message);
    console.error("Raw output:", error.rawOutput);
    console.error("Cause:", error.cause);

    // Implement fallback logic
    return fallbackResponse();
  } else if (error instanceof MultipleStructuredOutputsError) {
    console.error("Multiple outputs returned:");
    console.error("Outputs:", error.outputs);

    // Choose one or combine
    return error.outputs[0];
  } else {
    throw error;
  }
}

import { tool, createAgent } from "langchain";
import { z } from "zod";

// Tool with error handling
const apiTool = tool(
  async ({ endpoint }) => {
    try {
      const response = await fetch(endpoint);

      if (!response.ok) {
        return `Error: HTTP ${response.status} - ${response.statusText}`;
      }

      const data = await response.json();
      return JSON.stringify(data);
    } catch (error) {
      return `Error: ${error.message}`;
    }
  },
  {
    name: "api_call",
    description: "Call an API endpoint",
    schema: z.object({
      endpoint: z.string().url(),
    }),
  }
);

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [apiTool],
});

// Agent-level error handling
try {
  const result = await agent.invoke({
    messages: [{ role: "user", content: "Call the API" }],
  });
} catch (error) {
  if (error instanceof ToolInvocationError) {
    console.error(`Tool ${error.toolName} failed completely:`, error.message);

    // Notify user or implement retry
    return handleToolFailure(error);
  } else {
    throw error;
  }
}

import { createMiddleware, createAgent } from "langchain";

// Error-handling middleware
const errorMiddleware = createMiddleware({
  name: "error-handler",

  wrapToolCall: async (request, handler, runtime) => {
    try {
      return await handler(request);
    } catch (error) {
      console.error(`Tool ${request.toolName} failed:`, error);

      // Log to monitoring service
      await logError({
        type: "tool_error",
        toolName: request.toolName,
        args: request.args,
        error: error.message,
      });

      // Return error as tool result (don't throw)
      return {
        content: `Error: ${error.message}`,
        error: error.message,
      };
    }
  },

  wrapModelCall: async (state, handler, runtime) => {
    try {
      return await handler(state);
    } catch (error) {
      console.error("Model call failed:", error);

      // Log error
      await logError({
        type: "model_error",
        error: error.message,
      });

      // Re-throw for agent to handle
      throw error;
    }
  },
});

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [],
  middleware: [errorMiddleware],
});

import {
  createAgent,
  toolCallLimitMiddleware,
  ToolCallLimitExceededError,
} from "langchain";

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [/* tools */],
  middleware: [
    toolCallLimitMiddleware({
      runLimit: 5,
      errorMessage: "Maximum tool calls exceeded for this request",
    }),
  ],
});

try {
  const result = await agent.invoke({
    messages: [{ role: "user", content: "Do many things" }],
  });
} catch (error) {
  if (error instanceof ToolCallLimitExceededError) {
    console.error(`Limit exceeded: ${error.limit} calls`);
    console.error(`Actual calls: ${error.actualCalls}`);

    // Notify user
    return {
      error: "Too many operations required. Please simplify your request.",
    };
  } else {
    throw error;
  }
}

import { createAgent } from "langchain";

async function callAgentWithFallback(input: string) {
  const agent = createAgent({
    model: "openai:gpt-4o",
    tools: [/* tools */],
  });

  try {
    // Try with tools
    return await agent.invoke({
      messages: [{ role: "user", content: input }],
    });
  } catch (error) {
    console.warn("Agent with tools failed, trying without tools:", error);

    // Fallback: agent without tools
    const simpleAgent = createAgent({
      model: "openai:gpt-4o",
      tools: [],
    });

    try {
      return await simpleAgent.invoke({
        messages: [{ role: "user", content: input }],
      });
    } catch (fallbackError) {
      console.error("Fallback agent also failed:", fallbackError);

      // Final fallback: return error message
      return {
        messages: [
          {
            role: "assistant",
            content: "I apologize, but I'm unable to process your request at this time.",
          },
        ],
      };
    }
  }
}

async function invokeWithRetry(agent: ReactAgent, input: any, maxRetries = 3) {
  let lastError: Error;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await agent.invoke(input);
    } catch (error) {
      lastError = error;
      console.warn(`Attempt ${attempt} failed:`, error);

      if (attempt < maxRetries) {
        // Exponential backoff
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }

  throw new Error(`Failed after ${maxRetries} attempts: ${lastError.message}`);
}

// Usage
try {
  const result = await invokeWithRetry(agent, {
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error) {
  console.error("All retry attempts failed:", error);
}