Configurable

Using agent execution parameters when communicating with an agent.

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

tsx

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

  // [!code highlight:3]
  const { agent } = useAgent({
    agentId: "sample_agent",
  });

  // Pass configuration when running the agent
  // [!code highlight:8]
  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

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)

Configurable

Using agent execution parameters when communicating with an agent.

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.

app/page.tsx

tsx

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

  // [!code highlight:3]
  const { agent } = useAgent({
    agentId: "sample_agent",
  });

  // Pass configuration when running the agent
  // [!code highlight:8]
  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

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)