Configurable

What is this?#

LangGraph agents are able to take execution parameters, such as auth tokens and similar properties. You can add these using this feature.

If you wish to read further, you can refer to the configuration guide by LangGraph

When should I use this?#

This is useful when you want to send execution-time configuration information (such as different tokens or metadata for a given session) that should not be part of the agent state.

Looking for authentication?

If you need to pass authentication tokens specifically, see the dedicated Authentication guide which covers LangGraph Platform and self-hosted authentication patterns in detail.

Implementation#

By default, LangGraph agents are invoked with a config argument. This config has a configurable property which can be accessed and filled with your data.

Pass configuration from the frontend#

First, pass the configuration properties as you would like to receive them in the agent.

Do not call runAgent directly in the component body: it would run on every render and can trigger errors such as thread is already processing. Use a useEffect with an empty dependency array (or call runAgent from an event handler) when you want to start the run once with a given config.

app/page.tsx

import { useAgent } from "@copilotkit/react-core/v2"; 
import { useEffect } from "react";
function YourMainContent() {
  // ...

  const { agent } = useAgent({
    agentId: "sample_agent",
  });

  // Pass configuration when running the agent
  useEffect(() => {
    agent.runAgent({
      forwardedProps: {
        config: {
          configurable: {
            authToken: 'example-token'
          },
          recursion_limit: 50,
        }
      }
    });
  }, []);

  // ...

  return (... your component UI markdown)
}

Use configurables in agent#

Now you can simply pull the values from the provided config argument in any agent node

async def agent_node(state: AgentState, config: RunnableConfig):

    auth_token = config['configurable'].get('authToken', None)

    return state

async function agentNode(state: AgentState, config: RunnableConfig): Promise<AgentState> {
    const authToken = config.configurable?.authToken ?? null;

    return state;
}

Optional: Define configurables schema#

If you'd like, you can define a schema to indicate which configurables you wish to receive. Any item passed to "configurables" which is not included in the schema, will be filtered out.

You can read more about this here.

from typing import TypedDict

# define which properties will be allowed in the configuration
class ConfigSchema(TypedDict):
  authToken: str

# ...add all necessary graph nodes

# when defining the state graph, apply the config schema
workflow = StateGraph(AgentState, config_schema=ConfigSchema)

import { StateSchema } from "@langchain/langgraph";
import { z } from "zod";

// define which properties will be allowed in the configuration
export const ConfigSchema = new StateSchema({
  authToken: z.string()
})

// ...add all necessary graph nodes

// when defining the state graph, apply the config schema
const workflow = new StateGraph(AgentStateSchema, ConfigSchema)