What is Ct Agent Toolkit

The ct-agent-toolkit is a library designed to facilitate the integration of popular agent frameworks such as LangChain, CrewAI, Vercel’s AI SDK, and Model Context Protocol (MCP) with APIs through function calling.

Use cases

Use cases for the ct-agent-toolkit include building AI-driven e-commerce solutions, automating product management tasks, and enhancing customer interactions through intelligent agents.

How to use

To use the ct-agent-toolkit, install it via npm with the command ‘npm install @commercetools-demo/commercetools-agent-toolkit’. Configure it with your commercetools project API client credentials and specify the actions you want to enable in the configuration.

Key features

Key features of the ct-agent-toolkit include support for both Python and TypeScript, integration with popular agent frameworks, and the ability to perform various API actions such as reading, creating, and updating products and carts.

Where to use

The ct-agent-toolkit can be used in e-commerce applications, particularly those utilizing commercetools for managing products, carts, and other related functionalities.

NOTE: This is NOT an official commercetools code and NOT production ready. Use it at your own risk

Agent Toolkit

The commercetools Agent Toolkit enables popular agent frameworks including LangChain, Vercel’s AI SDK, and Model Context Protocol (MCP) to integrate with APIs through function calling. The
library is not exhaustive of the entire commercetools API. It includes support for TypeScript and is built directly on top of the [Node][node-sdk] SDK.

Included below are basic instructions, but refer to the TypeScript package for more information.

TypeScript

Installation

You don’t need this source code unless you want to modify the package. If you just
want to use the package run:

npm install @commercetools-demo/ct-agent-toolkit 

Requirements

• Node 18+

Usage

The library needs to be configured with your commercetools project API client credentials which is available in your Merchant center.
Important: Ensure that the API client credentials have the necessary scopes aligned with the actions you configure in the toolkit. For example, if you configure products: { read: true }, your API client must have the view_products scope.
Additionally, configuration enables you to specify the types of actions that can be taken using the toolkit.

import { CommercetoolsAgentToolkit } from "@commercetools-demo/ct-agent-toolkit/langchain";

const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  projectKey: process.env.PROJECT_KEY!,
  authUrl: process.env.AUTH_URL!,
  apiUrl: process.env.API_URL!,
  configuration: {
    context: {
      isAdmin: true,
    },
    actions: {
      products: {
        read: true,
        create: true,
        update: true,
      },
      project: {
        read: true,
      },
    },
  },
});

Tools

The toolkit works with LangChain and Vercel’s AI SDK and can be passed as a list of tools. For example:

import { AgentExecutor, createStructuredChatAgent } from "langchain/agents";

const tools = commercetoolsAgentToolkit.getTools();

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

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

Context

In some cases you will want to provide values that serve as defaults when making requests. Providing context is required to access the tools.

Customer Context

    const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
      clientId: process.env.CLIENT_ID!,
      clientSecret: process.env.CLIENT_SECRET!,
      projectKey: process.env.PROJECT_KEY!,
      authUrl: process.env.AUTH_URL!,
      apiUrl: process.env.API_URL!,
      configuration: {
        context: {
          customerId: "customer-12345",
          cartId: "cart-12345",
        },
      },
    });

Admin Context

const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  projectKey: process.env.PROJECT_KEY!,
  authUrl: process.env.AUTH_URL!,
  apiUrl: process.env.API_URL!,
  configuration: {
    context: {
      isAdmin: true,
    },
  },
});

Store Context

const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  projectKey: process.env.PROJECT_KEY!,
  authUrl: process.env.AUTH_URL!,
  apiUrl: process.env.API_URL!,
  configuration: {
    context: {
      storeKey: "store-12345",
    },
  },
});

Associate Context

const commercetoolsAgentToolkit = new CommercetoolsAgentToolkit({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  projectKey: process.env.PROJECT_KEY!,
  authUrl: process.env.AUTH_URL!,
  apiUrl: process.env.API_URL!,
  configuration: {
    context: {
      customerId: "customer-12345", // Required for associate operations
      businessUnitKey: "business-unit-12345",
    },
  },
});

Note: Providing one of the following parameters is required: --isAdmin, --customerId, --storeKey, or both --customerId and --businessUnitKey for associate operations

Model Context Protocol

The commercetools Agent Toolkit also supports the Model Context Protocol (MCP).

If you prefer to install the MCP package directly (for example, to run it via a script or manage it as a project dependency), you can use:

npm install @commercetools-demo/mcp

Then, you might need to configure your PATH or use npx @commercetools-demo/mcp ... to run it.

To run the commercetools MCP server directly using npx (which handles downloading the package if needed), use the following command:

npx -y @commercetools-demo/mcp --tools=all --clientId=CLIENT_ID --clientSecret=CLIENT_SECRET --projectKey=PROJECT_KEY --authUrl=AUTH_URL --apiUrl=API_URL --isAdmin=true

Replace CLIENT_ID, CLIENT_SECRET, PROJECT_KEY, AUTH_URL, and API_URL with your actual values. Or, you could set the API_SECRET_KEY in your environment variables.

Alternatively, you can set up your own MCP server. For example:

import { CommercetoolsAgentToolkit } from "@commercetools-demo/ct-agent-toolkit/modelcontextprotocol";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new CommercetoolsAgentToolkit({
  clientId: process.env.CLIENT_ID!,
  clientSecret: process.env.CLIENT_SECRET!,
  projectKey: process.env.PROJECT_KEY!,
  authUrl: process.env.AUTH_URL!,
  apiUrl: process.env.API_URL!,
  configuration: {
    context: {
      isAdmin: true,
    },
    actions: {
      products: {
        read: true,
      },
      cart: {
        read: true,
        create: true,
        update: true,
      }
    },
  },
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Commercetools MCP Server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

getTools()

Returns the current set of available tools that can be used with LangChain, AI SDK, or other agent frameworks:

const tools = commercetoolsAgentToolkit.getTools();

Supported API methods

• Read products
• Create products
• Update products
• Read project information
• Search products
• Read category information
• Create category
• Update category
• Read product selection
• Create product selection
• Update product selection
• Read order information
• Create order
• Update order
• Read cart information
• Create cart
• Replicate cart
• Update cart
• Read customer group
• Create customer group
• Update customer group
• Read quote request
• Create quote request
• Update quote request
• Read staged quote
• Create staged quote
• Update staged quote
• Read standalone price
• Create standalone price
• Update standalone price
• Read product discount
• Create product discount
• Update product discount
• Read cart discount
• Create cart discount
• Update cart discount
• Read product type
• List product types
• Create product type
• Update product type
• Read store
• Create store
• Update store
• Read business unit
• Create business unit
• Update business unit