### Run Development Server

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/README.md

Install dependencies and start the local development server for the Next.js application. Ensure environment variables are set up in `.env.local`.

```bash
yarn dev
```

--------------------------------

### AI SDK Examples Hub Guide Box

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/04-page-components.md

This snippet represents the guide box component on the AI SDK Examples Hub landing page. It includes a placeholder for a description of AI SDK and RSC integration, along with comments indicating links to sub-examples for agents and tools.

```typescript
<GuideInfoBox>
  {/* Description of AI SDK + RSC integration */}
  {/* Links to /ai_sdk/agent and /ai_sdk/tools */}
</GuideInfoBox>
```

--------------------------------

### Troubleshooting Reference Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/README.md

Example of a question about required environment variables and where to find this information in the documentation.

```markdown
Question: "What environment variables are required?"
Answer: 06-configuration-reference.md (all env vars documented)
```

--------------------------------

### Install LangChain and AI SDK Packages

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/agent/README.md

Install the necessary LangChain and AI SDK packages for your project. This command installs the core libraries required for LangChain development.

```bash
npm install langchain @langchain/core @langchain/community ai
```

--------------------------------

### Vercel Start Command

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Use this command to start your Next.js application after deployment on Vercel.

```bash
yarn start
```

--------------------------------

### Integration Reference Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/README.md

Example of a question related to setting up document retrieval and the relevant documentation files to consult.

```markdown
Question: "How do I set up document retrieval?"
Answer: 06-configuration-reference.md + 01-api-endpoints.md (ingest/retrieval routes)
```

--------------------------------

### Install LangChain & AI SDK Packages

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/tools/README.md

Install the necessary LangChain and AI SDK packages for your project.

```bash
npm install @langchain/openai @langchain/core ai zod zod-to-json-schema
```

--------------------------------

### Development Reference Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/README.md

Example of a question a developer might ask about the ChatWindow component API and where to find the answer.

```markdown
Question: "What's the ChatWindow component API?"
Answer: 01-api-endpoints.md, or search "ChatWindow" in TOC
```

--------------------------------

### Shell Command Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/00-TABLE-OF-CONTENTS.md

Shows an example of a curl command for making a POST request to an API endpoint.

```bash
# Shell commands
curl -X POST http://localhost:3000/api/chat
```

--------------------------------

### ChatLayout Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/02-components-reference.md

Example of how to use the ChatLayout component with chat messages and an input form.

```typescript
<ChatLayout
  content={<ChatMessages messages={messages} />}
  footer={<ChatInput {...props} />}
/>
```

--------------------------------

### Complete LangGraph Definition Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/07-langgraph-reference.md

An example demonstrating the initialization of an LLM, definition of a state schema, addition of an agent node, configuration of edges, and compilation of the graph.

```typescript
import {
  StateGraph,
  MessagesAnnotation,
  START,
  Annotation,
} from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";

// 1. Initialize LLM
const llm = new ChatOpenAI({
  model: "gpt-4o-mini",
  temperature: 0
});

// 2. Define state schema with custom fields
const builder = new StateGraph(
  Annotation.Root({
    messages: MessagesAnnotation.spec["messages"],
    timestamp: Annotation<number>
  })
)

// 3. Add agent node that calls LLM
.addNode("agent", async (state, config) => {
  // Invoke LLM with system prompt and messages
  const message = await llm.invoke([
    {
      type: "system",
      content: "You are a pirate named Patchy..."
    },
    ...state.messages
  ]);

  // Return state updates
  return {
    messages: message,
    timestamp: Date.now()
  };
})

// 4. Connect START to agent node
.addEdge(START, "agent");

// 5. Compile graph
const graph = builder.compile();

// 6. Export for use
export const graph = graph;
```

--------------------------------

### RetrieverTool Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Example of creating a RetrieverTool instance for searching documents within an agent.

```typescript
const retrieverTool = createRetrieverTool(retriever, {
  name: "search_documents",
  description: "Search the document database"
});
```

--------------------------------

### GuideInfoBox Component Usage

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/02-components-reference.md

Example of how to use the GuideInfoBox component to wrap informational content, such as a list.

```typescript
<GuideInfoBox>
  <ul>
    <li>First bullet point</li>
    <li>Second bullet point</li>
  </ul>
</GuideInfoBox>
```

--------------------------------

### Component Import Paths Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/02-components-reference.md

Demonstrates how to import various UI components using the Next.js path alias '@/' configured in tsconfig.json.

```typescript
// Example imports
import { ChatWindow } from "@/components/ChatWindow";
import { ChatMessageBubble } from "@/components/ChatMessageBubble";
import { Button } from "@/components/ui/button";
import { Dialog, DialogContent, DialogTrigger } from "@/components/ui/dialog";
import { UploadDocumentsForm } from "@/components/UploadDocumentsForm";
import { GuideInfoBox } from "@/components/guide/GuideInfoBox";
```

--------------------------------

### Type Safety Reference Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/README.md

Example of a question about the return type of the executeTool server action and the relevant documentation files.

```markdown
Question: "What does the executeTool server action return?"
Answer: 03-utilities-and-helpers.md + 05-types-and-interfaces.md (StreamableValue)
```

--------------------------------

### JSON Structure Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/00-TABLE-OF-CONTENTS.md

Provides an example of a JSON structure for chat messages.

```json
// JSON structures
{
  "messages": [
    { "role": "user", "parts": [{"type": "text", "text": "Hello"} ] }
  ]
}
```

--------------------------------

### Chat Endpoint Request Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Example of how to send a POST request to the /api/chat endpoint with user messages. This demonstrates the expected JSON body structure for initiating a chat conversation.

```bash
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [{"type": "text", "text": "Hello, how are you?"}]
      }
    ]
  }'
```

--------------------------------

### Custom State Graph Example Page

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/COMPLETION-SUMMARY.txt

This Next.js page features a custom state graph example using Langchain. It demonstrates building complex conversational flows with state management.

```typescript
import { LanggraphPage } from "@langchain/nextjs/langgraph";

export default LanggraphPage;

```

--------------------------------

### Example Usage - Stream Mode for Retrieval Agents API

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Demonstrates how to call the retrieval agents API in stream mode using curl. This example sends a user message and expects a streaming text response.

```bash
curl -X POST http://localhost:3000/api/chat/retrieval_agents \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [{"type": "text", "text": "What is LangChain?"}]
      }
    ],
    "show_intermediate_steps": false
  }'
```

--------------------------------

### ChatMessageBubble Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/02-components-reference.md

An example demonstrating how to use the ChatMessageBubble component with sample message data, an AI emoji, and source citations.

```typescript
<ChatMessageBubble
  message={{
    id: "1",
    role: "assistant",
    parts: [{ type: "text", text: "Hello!" }]
  }}
  aiEmoji="🐕"
  sources={[
    {
      pageContent: "Document excerpt...",
      metadata: { loc: { lines: { from: 10, to: 20 } } }
    }
  ]}
/>
```

--------------------------------

### AI SDK RSC Examples Hub Page

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/COMPLETION-SUMMARY.txt

This Next.js page serves as a hub for React Server Components (RSC) examples using the AI SDK. It provides access to various AI-related demonstrations.

```typescript
import { AiSdkPage } from "@langchain/nextjs/ai_sdk";

export default AiSdkPage;

```

--------------------------------

### Example Request for Structured Output API

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Demonstrates how to send a POST request to the structured output API endpoint with a user message. The body includes the messages array, which is processed by the API.

```bash
curl -X POST http://localhost:3000/api/chat/structured_output \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [{"type": "text", "text": "What a beautiful day!"}]
      }
    ]
  }'
```

--------------------------------

### AI SDK Tool Calling Example Page

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/COMPLETION-SUMMARY.txt

This Next.js page illustrates tool calling within React Server Components using the AI SDK. It demonstrates how agents can utilize external tools.

```typescript
import { ToolCallingPage } from "@langchain/nextjs/ai_sdk";

export default ToolCallingPage;

```

--------------------------------

### Agent with SERP API Access

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/README.md

This example utilizes a prebuilt LangGraph agent that can access the internet via SERP API. Ensure your SERPAPI_API_KEY is set in `.env.local` to enable internet access for the agent.

```typescript
import { ChatOpenAI } from "@langchain/openai";
import { TavilySearchResults } from "@langchain/community/tools/retrieval";
import { AgentExecutor, createOpenAIFunctions agent } from "langchain/agents";
import { PromptTemplate } from "@langchain/core/prompts";

const model = new ChatOpenAI({ temperature: 0 });
const tools = [new TavilySearchResults()];

const prompt = PromptTemplate.fromTemplate(`You are very powerful tool user.`);

constlc_agent = await createOpenAIFunctions agent({
  llm: model,
  tools,
  prompt,
});

const agentExecutor = new AgentExecutor({ agent: lc_agent, tools });

const result = await agentExecutor.invoke({
  input: "What is the weather in San Francisco?",
});

console.log(result);
```

--------------------------------

### ChatWindow Component Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/02-components-reference.md

Demonstrates how to integrate the ChatWindow component into a Next.js page, configuring its endpoint, placeholder, and other optional props.

```typescript
import { ChatWindow } from "@/components/ChatWindow";

export default function Page() {
  return (
    <ChatWindow
      endpoint="/api/chat/retrieval"
      emoji="🐕"
      placeholder="Ask about the document..."
      emptyStateComponent={<div>Start a conversation</div>}
      showIngestForm={true}
      showIntermediateStepsToggle={false}
    />
  );
}
```

--------------------------------

### StateGraph Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Demonstrates building a stateful computation graph using StateGraph. Adds a node, defines a transition, and compiles the graph for execution.

```typescript
const graph = new StateGraph(annotation)
  .addNode("agent", async (state) => {
    // Process state
    return { updatedField: value };
  })
  .addEdge(START, "agent")
  .compile();
```

--------------------------------

### Set SUPABASE_URL

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Required for retrieval examples. Format: https://[project-id].supabase.co. Obtain from Supabase Dashboard.

```bash
SUPABASE_URL="https://abc123.supabase.co"
```

--------------------------------

### Example Usage: Ingest API

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Demonstrates how to call the ingest API using curl to send a JSON payload containing text to be indexed.

```bash
curl -X POST http://localhost:3000/api/retrieval/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "text": "# My Document\n\nThis is the content of my document that should be indexed for retrieval."
  }'
```

--------------------------------

### POST /api/chat/agents - Full Steps Mode

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Example of how to call the /api/chat/agents endpoint to receive the full conversation history including intermediate steps, useful for debugging or detailed UIs. Set `show_intermediate_steps` to true.

```bash
curl -X POST http://localhost:3000/api/chat/agents \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [{"type": "text", "text": "What is 5 + 3?"}]
      }
    ],
    "show_intermediate_steps": true
  }'
```

--------------------------------

### Structured Output with Zod Schema

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/README.md

This example demonstrates returning structured output from an LLM using OpenAI Functions and Zod for schema definition. It forces the LLM to return arguments in a specified format.

```typescript
import { createStructuredOutputChain } from "langchain/chains/openai_functions";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

const model = new ChatOpenAI({ temperature: 0 });

const extractionChain = await createStructuredOutputChain(
  z.object({
    name: z.string().describe("The name of the person"),
    age: z.number().describe("The age of the person"),
    hair_color: z.string().describe("The hair color of the person"),
  }),
  model,
  {
    prompt: new PromptTemplate({
      template: "Extract the name, age, and hair color from the following text: {text}",
      inputVariables: ["text"],
    }),
  }
);

const result = await extractionChain.invoke({
  text: "My name is John Doe. I am 30 years old and have black hair.",
});

console.log(result);
```

--------------------------------

### TypeScript Code Block Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/00-TABLE-OF-CONTENTS.md

Illustrates a basic TypeScript code snippet for defining a chain.

```typescript
// TypeScript example
const chain = prompt.pipe(model).pipe(outputParser);
```

--------------------------------

### ChatInput Component Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/02-components-reference.md

Demonstrates how to integrate the ChatInput component into a React application, binding its state and handlers to manage user input and submission.

```typescript
<ChatInput
  value={input}
  onChange={(e) => setInput(e.target.value)}
  onSubmit={(e) => handleSubmit(e)}
  loading={isLoading}
  placeholder="Type your message..."
  actions={<UploadButton />}
>
  <Checkbox>Show details</Checkbox>
</ChatInput>
```

--------------------------------

### Set SUPABASE_PRIVATE_KEY

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Required for retrieval examples. Use the Service Role Key from Supabase Dashboard. Never commit to version control.

```bash
SUPABASE_PRIVATE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### AI SDK Agent Streaming Example Page

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/COMPLETION-SUMMARY.txt

This Next.js page demonstrates agent streaming within React Server Components using the AI SDK. It showcases real-time agent responses.

```typescript
import { AgentStreamingPage } from "@langchain/nextjs/ai_sdk";

export default AgentStreamingPage;

```

--------------------------------

### Example Usage of Retrieval Chat API

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Demonstrates how to send a POST request to the retrieval chat API with a conversation history. This is useful for testing the RAG endpoint and simulating user interactions.

```bash
curl -X POST http://localhost:3000/api/chat/retrieval \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [{"type": "text", "text": "Previous question?"}]
      },
      {
        "role": "assistant",
        "parts": [{"type": "text", "text": "Some answer"}]
      },
      {
        "role": "user",
        "parts": [{"type": "text", "text": "Follow-up question about the document?"}]
      }
    ]
  }'
```

--------------------------------

### useChat Hook Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/08-ai-sdk-integration.md

Demonstrates how to use the useChat hook from the @ai-sdk/react package to manage chat messages, input, and form submission. Requires the '/api/chat' endpoint to be configured.

```typescript
const { messages, input, handleInputChange, handleSubmit } = useChat({
  api: "/api/chat",
  onError: (e) => console.error(e)
});

return (
  <form onSubmit={handleSubmit}>
    <input value={input} onChange={handleInputChange} />
    <button type="submit">Send</button>
  </form>
);
```

--------------------------------

### UploadDocumentsForm Usage Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/02-components-reference.md

Demonstrates how to use the UploadDocumentsForm component within a Dialog structure in a React application.

```typescript
<Dialog>
  <DialogTrigger asChild>
    <Button>Upload Document</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Upload document</DialogTitle>
    </DialogHeader>
    <UploadDocumentsForm />
  </DialogContent>
</Dialog>
```

--------------------------------

### Structured Output Page

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/COMPLETION-SUMMARY.txt

This Next.js page showcases an example of generating structured JSON output. It's useful for tasks requiring data in a specific format.

```typescript
import { ChatClient } from "@langchain/nextjs/chat";

export default function Index() {
  return <ChatClient title="Structured Output" />; 
}

```

--------------------------------

### Agents Chat Window Configuration

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/04-page-components.md

Configure the ChatWindow component for the agents page. This setup enables tool-calling capabilities and an option to display intermediate steps.

```typescript
<ChatWindow
  endpoint="/api/chat/agents"
  emoji="🦜"
  placeholder="Ask me anything! I'm connected to the internet..."
  emptyStateComponent={InfoCard}
  showIntermediateStepsToggle={true}
/>
```

--------------------------------

### Swap Vector Store Implementation

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Replace the existing vector store initialization with a new one, for example, using `PineconeVectorStore` instead of `SupabaseVectorStore`.

```typescript
import { PineconeVectorStore } from "@langchain/community/vectorstores/pinecone";

const vectorstore = new PineconeVectorStore(
  new OpenAIEmbeddings(),
  { pineconeIndex }
);
```

--------------------------------

### Looping Until Completion with Conditional Edges

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/07-langgraph-reference.md

Implement looping logic in a graph by using conditional edges that check for completion criteria. This example loops until no tool calls are present.

```typescript
.addConditionalEdges(
  "agent",
  (state) => {
    lastMsg = state.messages[-1];
    if (lastMsg.tool_calls) return "tools";
    return END;
  },
  { "tools": "tools", END: END }
)
```

--------------------------------

### Configure and create the agent

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/agent/README.md

Sets up the agent with tools, a prompt from LangChain Hub, and the language model, then initializes the AgentExecutor.

```typescript
  (async () => {
    const tools = [new TavilySearchResults({ maxResults: 1 })];

    const prompt = await pull<ChatPromptTemplate>(
      "hwchase17/openai-tools-agent",
    );

    const agent = createToolCallingAgent({
      llm,
      tools,
      prompt,
    });

    const agentExecutor = new AgentExecutor({
      agent,
      tools,
    });
```

--------------------------------

### Analyze Bundle Size with Next.js

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/README.md

Run this command to analyze the bundle size of your application. This is useful for optimizing code size, especially for edge functions.

```bash
ANALYZE=true yarn build
```

--------------------------------

### Error Response Example

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Example of a JSON error response from an API endpoint. This format is used to communicate errors back to the client, including a status code and an error message.

```json
{
  "error": "error message text"
}
```

--------------------------------

### Create and Pipe a PromptTemplate with Chat Model

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Demonstrates creating a prompt template, piping it to a chat model, and then to an output parser. Use this to build sequential processing pipelines.

```typescript
const chain = PromptTemplate.fromTemplate("{input}")
  .pipe(chatModel)
  .pipe(outputParser);

const result = await chain.invoke({ input: "Hello" });
```

--------------------------------

### Define Prompt and Chat Model

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/tools/README.md

Define the system prompt and initialize the chat model (e.g., ChatOpenAI). This sets up the AI's persona and the model to be used for generating responses.

```typescript
  (async () => {
    const prompt = ChatPromptTemplate.fromMessages([
      [
        "system",
        `You are a helpful assistant. Use the tools provided to best assist the user.`,
      ],
      ["human", "{input}"],
    ]);

    const llm = new ChatOpenAI({
      model: "gpt-4o-mini",
      temperature: 0,
    });
```

--------------------------------

### ChatWindow Component Configuration Props

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Defines the props for the ChatWindow component, specifying their types, whether they are required, default values, and example usage.

```typescript
endpoint: "/api/chat"
emptyStateComponent: <InfoCard />
placeholder: "Ask me anything"
emoji: "🤖"
showIngestForm: true
showIntermediateStepsToggle: true
```

--------------------------------

### Vercel Build Command

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Use this command to build your Next.js application for deployment on Vercel.

```bash
yarn build
```

--------------------------------

### Update Custom State Fields

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/07-langgraph-reference.md

Provides an example of updating custom fields within the state, including incrementing a counter and merging data.

```typescript
return {
  customField: newValue,
  counter: state.counter + 1,
  data: { ...state.data, key: value }
};
```

--------------------------------

### Trace LangGraph Execution Events

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/07-langgraph-reference.md

Streams execution events from a LangGraph, logging events that start with 'on_'. Requires the graph and input to be defined.

```typescript
const eventStream = graph.streamEvents(
  input,
  { version: "v2" }
);

for await (const { event, data } of eventStream) {
  if (event.includes("on_")) {
    console.log(`[${event}]`, data);
  }
}
```

--------------------------------

### Initialize the chat model

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/agent/README.md

Configure and instantiate the ChatOpenAI model with specified parameters like model name and temperature.

```typescript
const llm = new ChatOpenAI({
  model: "gpt-4o-mini",
  temperature: 0,
});
```

--------------------------------

### Add Edge to StateGraph

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/07-langgraph-reference.md

Use addEdge to define a connection between two nodes in a StateGraph. The START constant represents the graph's entry point.

```typescript
.addEdge(START, "agent")
```

```typescript
.addEdge("agent", "next_node")
```

--------------------------------

### POST /api/chat/agents - Stream Mode

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/01-api-endpoints.md

Example of how to call the /api/chat/agents endpoint to receive only the final text response, suitable for streaming interfaces. Set `show_intermediate_steps` to false.

```bash
curl -X POST http://localhost:3000/api/chat/agents \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "parts": [{"type": "text", "text": "What is 5 + 3?"}]
      }
    ],
    "show_intermediate_steps": false
  }'
```

--------------------------------

### Analyze Bundle Size

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Run this command to analyze the bundle size breakdown of your Next.js application. This helps in identifying large dependencies and optimizing the build.

```bash
ANALYZE=true yarn build
```

--------------------------------

### Local Development Environment Variables

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Set these variables in your .env.local file for local development. Includes API keys for OpenAI and optional services like SerpApi and Supabase.

```bash
# .env.local - local development
OPENAI_API_KEY="sk-..."
LANGCHAIN_CALLBACKS_BACKGROUND=false

# Optional for testing agents
SERPAPI_API_KEY="..."

# Optional for retrieval examples
SUPABASE_URL="https://abc123.supabase.co"
SUPABASE_PRIVATE_KEY="eyJ..."
```

--------------------------------

### Next.js Bundle Analysis Configuration

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Configuration for enabling bundle size analysis in next.config.js. Run with the ANALYZE=true environment variable.

```javascript
module.exports = {
  // Bundle analysis support
  // Run: ANALYZE=true yarn build
}
```

--------------------------------

### Enable LANGCHAIN_TRACING_V2

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Enable LangSmith tracing for debugging and monitoring. Requires LANGCHAIN_API_KEY when enabled.

```bash
LANGCHAIN_TRACING_V2=true
```

--------------------------------

### PromptTemplate

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Manages prompt strings by formatting input variables. Supports template syntax with variable placeholders.

```APIDOC
## PromptTemplate

### Description
Manages prompt strings by formatting input variables. Supports template syntax with variable placeholders.

### Constructor
`PromptTemplate.fromTemplate(template: string): PromptTemplate`

### Methods
- `pipe(nextStep)`: LCEL composition.
- `invoke(values)`: Execute with variables.
- `stream(values)`: Stream output.

### Template Syntax
- `{variable_name}`: Variable placeholders.
```

--------------------------------

### Supabase Client Initialization

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Initializes a Supabase client using `createClient` from `@supabase/supabase-js`. This client is used for database operations like querying, inserting, and calling RPC functions.

```typescript
const client = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_PRIVATE_KEY!
);
```

--------------------------------

### Home Page Chat Window Configuration

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/04-page-components.md

Configures the `ChatWindow` component for the home page with a pirate theme. It specifies the backend endpoint, emoji, placeholder text, and an empty state component.

```typescript
<ChatWindow
  endpoint="api/chat"
  emoji="🏴‍☠️"
  placeholder="I'm an LLM pretending to be a pirate! Ask me about the pirate life!"
  emptyStateComponent={InfoCard}
/>
```

--------------------------------

### API Endpoints Reference

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/COMPLETION-SUMMARY.txt

This section details the 6 HTTP POST endpoints available in the application, including their request and response schemas, handler implementations, configuration details, error handling patterns, and usage examples.

```APIDOC
## API Endpoints

### Description
This section details the 6 HTTP POST endpoints available in the application, including their request and response schemas, handler implementations, configuration details, error handling patterns, and usage examples.

### Method
POST

### Endpoint
`/api/chat` (example, actual endpoints may vary)

### Parameters
#### Query Parameters
- **sessionId** (string) - Optional - The session ID for the chat.

#### Request Body
- **message** (string) - Required - The user's message.
- **history** (array) - Optional - The chat history.

### Request Example
```json
{
  "message": "Hello, how are you?",
  "history": [
    {"role": "user", "content": "Hi"},
    {"role": "assistant", "content": "Hello!"}
  ]
}
```

### Response
#### Success Response (200)
- **response** (string) - The assistant's reply.
- **sources** (array) - Optional - Sources used to generate the response.

#### Response Example
```json
{
  "response": "I am doing well, thank you!",
  "sources": ["doc1.pdf", "doc2.pdf"]
}
```

### Error Handling
- **400** - Bad Request: Invalid input provided.
- **500** - Internal Server Error: An unexpected error occurred.
```

--------------------------------

### SupabaseVectorStore.fromDocuments Static Method

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

A static method to create and populate a SupabaseVectorStore directly from a list of documents.

```APIDOC
## SupabaseVectorStore.fromDocuments Static Method

### Description
A static method to create and populate a SupabaseVectorStore directly from a list of documents.

### Method Signature
```typescript
SupabaseVectorStore.fromDocuments(
  docs: Document[],
  embeddings: Embeddings,
  options: VectorStoreOptions
): Promise<SupabaseVectorStore>
```

### Parameters
- **docs** (Document[]) - Required - The documents to add to the vector store.
- **embeddings** (Embeddings) - Required - The embedding generator to use.
- **options** (VectorStoreOptions) - Required - Configuration options for the vector store.
```

--------------------------------

### ChatOpenAI Alternative Models

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Lists alternative models for ChatOpenAI, highlighting their capabilities, speed, and cost trade-offs. Use 'gpt-4-turbo' or 'gpt-4o' for more capable responses, or 'gpt-3.5-turbo' for faster, cheaper options.

```typescript
// More capable (slower, more expensive)
model: "gpt-4-turbo"
```

```typescript
// Faster, cheaper legacy option
model: "gpt-3.5-turbo"
```

```typescript
// Latest GPT-4 model
model: "gpt-4o"
```

--------------------------------

### Stream Results and Update Client

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/tools/README.md

Call the `.stream` method on the chain to get a stream of results. Iterate over the stream, parse each item, and update the streamable value to send data to the client. Finally, signal the end of the stream.

```typescript
    const streamResult = await chain.stream({
      input,
    });

    for await (const item of streamResult) {
      stream.update(JSON.parse(JSON.stringify(item, null, 2)));
    }

    stream.done();
  })();

  return { streamData: stream.value };
}
```

--------------------------------

### Import necessary modules for agent

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/agent/README.md

Import core LangChain modules for agents, prompts, tools, and models, along with helpers for streaming.

```typescript
"use server";

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TavilySearchResults } from "@langchain/community/tools/tavily_search";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { pull } from "langchain/hub";
import { createStreamableValue } from "ai/rsc";
```

--------------------------------

### RunnableSequence

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Chains operations together using Langchain Expression Language (LCEL) for sequential execution.

```APIDOC
## RunnableSequence

### Description
Chains operations together using Langchain Expression Language (LCEL) for sequential execution.

### Constructor
`RunnableSequence.from([step1, step2, step3])`

### Methods
- `invoke(input)`: Execute chain synchronously.
- `stream(input)`: Stream output tokens.
- `streamEvents(input, options)`: Stream execution events.
- `pipe(nextStep)`: Add additional step.

### Usage Example
```typescript
const chain = PromptTemplate.fromTemplate("{input}")
  .pipe(chatModel)
  .pipe(outputParser);

const result = await chain.invoke({ input: "Hello" });
```
```

--------------------------------

### runAgent()

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/03-utilities-and-helpers.md

Executes a tool-calling agent with streaming event output using AI SDK RSC integration. It sets up a TavilySearch tool, pulls an agent prompt, and uses a ChatOpenAI model to stream execution events.

```APIDOC
## runAgent()

### Description
Executes a tool-calling agent with streaming event output using AI SDK RSC integration. It sets up a TavilySearch tool, pulls an agent prompt, and uses a ChatOpenAI model to stream execution events.

### Signature
```typescript
export async function runAgent(input: string): Promise<{ streamData: AsyncIterable<any> }>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **input** (string) - Required - User query or question for the agent to process

### Return Type
```typescript
{ streamData: AsyncIterable<any> }
```

### Returns
Streamable value with agent execution events.

### Usage Example
```typescript
// In a React Server Component
import { runAgent } from "@/app/ai_sdk/agent/action";
import { readStreamableValue } from "@ai-sdk/rsc";

async function AgentComponent() {
  const { streamData } = await runAgent("What is the weather today?");
  
  for await (const event of readStreamableValue(streamData)) {
    console.log(event);
  }
}
```
```

--------------------------------

### runAgent Server Action

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/README.md

A server action designed for invoking tool-calling agents.

```APIDOC
## runAgent()

### Description
Server action for initiating and managing tool-calling agents.

### Signature
`runAgent(args)`

### Parameters
(Parameters not explicitly detailed in source)

### Returns
(Return value not explicitly detailed in source)
```

--------------------------------

### Set NEXT_PUBLIC_DEMO to true

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Disable document ingestion in demo/hosted deployments. When true, the ingest endpoint returns 403 Forbidden.

```bash
NEXT_PUBLIC_DEMO="true"
```

--------------------------------

### SupabaseVectorStore Constructor

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Initializes a new SupabaseVectorStore instance. This class allows you to store and retrieve documents using Supabase as the backend vector database.

```APIDOC
## SupabaseVectorStore Constructor

### Description
Initializes a new SupabaseVectorStore instance. This class allows you to store and retrieve documents using Supabase as the backend vector database.

### Constructor Signature
```typescript
new SupabaseVectorStore(
  embeddings: Embeddings,
  options: {
    client: SupabaseClient;
    tableName?: string;
    queryName?: string;
  }
)
```

### Parameters
#### Embeddings
- **embeddings** (Embeddings) - Required - Embedding generator (e.g., OpenAIEmbeddings)

#### Options
- **options.client** (SupabaseClient) - Required - Initialized Supabase client
- **options.tableName** (string) - Optional - Database table name (default: "documents")
- **options.queryName** (string) - Optional - RPC function name (default: "match_documents")

### Methods
- `asRetriever(options?)` - Create retriever instance
- `addDocuments(docs)` - Add documents to store
- `similaritySearch(query, k)` - Find similar documents
- `fromDocuments(docs, embeddings, options)` - Static creation method
```

--------------------------------

### Demo Deployment Environment Variables (Ingest Disabled)

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Environment variables for a demo deployment where data ingestion is disabled. Sets NEXT_PUBLIC_DEMO to true.

```shell
OPENAI_API_KEY=sk-...
LANGCHAIN_CALLBACKS_BACKGROUND=false
SUPABASE_URL=https://abc123.supabase.co
SUPABASE_PRIVATE_KEY=eyJ...
NEXT_PUBLIC_DEMO=true
```

--------------------------------

### executeTool()

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/03-utilities-and-helpers.md

Executes tool/function calling with an LLM to extract structured output. It supports two modes: `withStructuredOutput` (wso=true) for direct structured object return, and traditional function calling (wso=false). It also allows streaming execution events (streamEvents=true) or just the output (streamEvents=false).

```APIDOC
## executeTool()

### Description
Executes tool/function calling with an LLM to extract structured output. It supports two modes: `withStructuredOutput` (wso=true) for direct structured object return, and traditional function calling (wso=false). It also allows streaming execution events (streamEvents=true) or just the output (streamEvents=false).

### Signature
```typescript
export async function executeTool(
  input: string,
  options?: {
    wso?: boolean;
    streamEvents?: boolean;
  }
): Promise<{ streamData: AsyncIterable<any> }>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **input** (string) - Required - User input for tool execution
- **options** (object) - Optional - Optional configuration flags
  - **options.wso** (boolean) - Optional - Use `withStructuredOutput` instead of function calling
  - **options.streamEvents** (boolean) - Optional - Stream execution events vs. streamed output only

### Return Type
```typescript
{
  streamData: AsyncIterable<any>
}
```

### Returns
Streamable value with tool execution output or events.

### Usage Example - Structured Output Mode
```typescript
import { executeTool } from "@/app/ai_sdk/tools/action";
import { readStreamableValue } from "@ai-sdk/rsc";

async function WeatherComponent() {
  const { streamData } = await executeTool(
    "Get weather for San Francisco, CA",
    { wso: true, streamEvents: false }
  );
  
  for await (const output of readStreamableValue(streamData)) {
    console.log(output);
    // Output: { city: "San Francisco", state: "CA" }
  }
}
```

### Usage Example - Function Calling Mode with Events
```typescript
const { streamData } = await executeTool(
  "Get weather for Boston, MA",
  { wso: false, streamEvents: true }
);

for await (const event of readStreamableValue(streamData)) {
  console.log(event);
  // Output: { event: "on_llm_start", ... }
}
```
```

--------------------------------

### Configure ChatOpenAI Model

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/07-langgraph-reference.md

Instantiates a ChatOpenAI model with specific parameters for generation.

```typescript
const llm = new ChatOpenAI({
  model: "gpt-4o-mini",
  temperature: 0,
  topP: 1,
  frequencyPenalty: 0,
  presencePenalty: 0,
  maxTokens: 2048
});
```

--------------------------------

### Set LANGCHAIN_PROJECT

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Set the project name in LangSmith for organizing traces. Recommended if using tracing.

```bash
LANGCHAIN_PROJECT="nextjs-starter"
```

--------------------------------

### SystemMessage Constructor

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Represents system-level instructions or metadata. Used for configuring LLM behavior.

```typescript
new SystemMessage(content: string)
```

--------------------------------

### Execute Tool with Function Calling and Events

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/03-utilities-and-helpers.md

Executes a tool using traditional function calling and streams execution events. Useful for detailed visibility into the tool execution process. Set `wso` to false and `streamEvents` to true.

```typescript
const { streamData } = await executeTool(
  "Get weather for Boston, MA",
  { wso: false, streamEvents: true }
);

for await (const event of readStreamableValue(streamData)) {
  console.log(event);
  // Output: { event: "on_llm_start", ... }
}
```

--------------------------------

### SupabaseVectorStore Static fromDocuments Method

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

A static method to create a SupabaseVectorStore instance by adding documents. It takes an array of documents, an Embeddings generator, and vector store options.

```typescript
SupabaseVectorStore.fromDocuments(
  docs: Document[],
  embeddings: Embeddings,
  options: VectorStoreOptions
): Promise<SupabaseVectorStore>
```

--------------------------------

### executeTool Server Action

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/README.md

A server action specifically for extracting and executing tools.

```APIDOC
## executeTool()

### Description
Server action used for the extraction and execution of tools within the system.

### Signature
`executeTool(args)`

### Parameters
(Parameters not explicitly detailed in source)

### Returns
(Return value not explicitly detailed in source)
```

--------------------------------

### Create LCEL Chain for Tool Execution

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/tools/README.md

Construct a LangChain Expression Language (LCEL) chain that pipes the prompt, the model with tools, and an output parser. This chain orchestrates the process of receiving input, calling the model, and parsing the tool output.

```typescript
const chain = prompt.pipe(modelWithTools).pipe(
  new JsonOutputKeyToolsParser<z.infer<typeof Weather>>({
    keyName: "get_weather",
    zodSchema: Weather,
  }),
);
```

--------------------------------

### SerpAPI Tool Configuration

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Configuration for the SerpAPI web search tool. The API key is loaded from the SERPAPI_API_KEY environment variable. Set maxResults to control the number of search results.

```typescript
new SerpAPI({
  // apiKey loaded from SERPAPI_API_KEY env var
  maxResults: 1  // Number of search results
})
```

--------------------------------

### Create RetrieverTool Function

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Wraps a document retriever as a tool for agent use. Requires a retriever instance and tool configuration.

```typescript
function createRetrieverTool(
  retriever: BaseRetriever,
  options: {
    name: string;
    description: string;
  }
): Tool
```

--------------------------------

### OpenAIEmbeddings Constructor

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/05-types-and-interfaces.md

Initializes a new OpenAIEmbeddings instance for generating text embeddings using OpenAI models.

```APIDOC
## OpenAIEmbeddings Constructor

### Description
Initializes a new OpenAIEmbeddings instance for generating text embeddings using OpenAI models.

### Constructor Signature
```typescript
new OpenAIEmbeddings({
  apiKey?: string;
  model?: string;
  [key: string]: any;
})
```

### Parameters
- **apiKey** (string) - Optional - Your OpenAI API key.
- **model** (string) - Optional - The embedding model to use (default: "text-embedding-3-small").
- **[key: string]: any** - Additional arbitrary properties.

### Methods
- `embedQuery(text)` - Generate embedding for query
- `embedDocuments(texts)` - Batch embed documents
```

--------------------------------

### ChatOpenAI Default Configuration

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Shows the default configuration for ChatOpenAI, including temperature and model settings. Temperature affects response creativity and consistency based on the use case.

```typescript
new ChatOpenAI({
  temperature: 0.8 or 0.2,  // See endpoint docs
  model: "gpt-4o-mini"
})
```

--------------------------------

### Vercel Production Deployment Environment Variables

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Environment variables for a Vercel production deployment. Includes essential API keys and Langchain tracing configurations.

```shell
OPENAI_API_KEY=sk-...
LANGCHAIN_CALLBACKS_BACKGROUND=false
SUPABASE_URL=https://abc123.supabase.co
SUPABASE_PRIVATE_KEY=eyJ...
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls_...
LANGCHAIN_PROJECT=my-prod-project
NEXT_PUBLIC_DEMO=false
```

--------------------------------

### Import client-side modules for streaming

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/app/ai_sdk/agent/README.md

Import necessary hooks and functions for client-side state management and reading streamable data.

```typescript
"use client";

import { useState } from "react";
import { readStreamableValue } from "ai/rsc";
import { runAgent } from "./action";
```

--------------------------------

### Calculator Tool Configuration

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Configuration for the Calculator tool. No specific configuration is needed to use this tool.

```typescript
new Calculator()
// No configuration needed
```

--------------------------------

### Set OPENAI_API_KEY

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/06-configuration-reference.md

Required for initializing ChatOpenAI models and OpenAIEmbeddings. Obtain from the OpenAI API Dashboard.

```bash
OPENAI_API_KEY="sk-..."
```

--------------------------------

### Simple Chat Page

Source: https://github.com/langchain-ai/langchain-nextjs-template/blob/main/_autodocs/COMPLETION-SUMMARY.txt

This Next.js page provides a simple chat interface with a pirate theme. It demonstrates basic chat functionality.

```typescript
import { ChatClient } from "@langchain/nextjs/chat";

export default function Index() {
  return <ChatClient title="Pirate Chat" />; 
}

```