@ag-kit/adapter-adp

@ag-kit/adapter-adp

Tencent Cloud ADP (Agent Development Platform) adapter for AG-Kit agents. This package provides integration between AG-Kit and Tencent Cloud's LKE (Large Knowledge Engine) service, enabling you to use ADP chatbots with AG-Kit's agent infrastructure.

Installation

npm install @ag-kit/agents @ag-kit/adapter-adp

Features

• AdpAgent: Agent implementation that connects to Tencent Cloud ADP chatbot services
• Streaming Support: Real-time SSE (Server-Sent Events) streaming responses
• Thinking Events: Support for thinking/reasoning process events from the model
• Workflow Integration: Support for ADP workflows with tool call events
• Custom Variables: Pass custom parameters to workflows and knowledge base

Environment Variables

Configure the following environment variables:

ADP_APP_KEY=your-adp-app-key  # ADP application key, required if not passed in config when creating the agent
TENCENTCLOUD_SECRETID=your-tencent-cloud-secret-id
TENCENTCLOUD_SECRETKEY=your-tencent-cloud-secret-key
TENCENTCLOUD_SESSIONTOKEN=your-tencent-cloud-session-token  # Optional, for temporary credentials

Usage

Basic Agent Setup

import { AdpAgent } from "@ag-kit/adapter-adp";

// Create the agent
const agent = new AdpAgent({
  name: "my-adp-agent",
  description: "A Tencent Cloud ADP chatbot agent",
  adpConfig: {
    appKey: process.env.ADP_APP_KEY, // Optional if set in env
  },
});

With Credentials in Config

import { AdpAgent } from "@ag-kit/adapter-adp";

const agent = new AdpAgent({
  name: "my-adp-agent",
  description: "An ADP agent with inline credentials",
  adpConfig: {
    appKey: "your-app-key", // Optional if ADP_APP_KEY env is set
    credential: {
      secretId: "your-secret-id", // Optional if TENCENTCLOUD_SECRETID env is set
      secretKey: "your-secret-key", // Optional if TENCENTCLOUD_SECRETKEY env is set
      token: "your-session-token", // Optional if TENCENTCLOUD_SESSIONTOKEN env is set
    },
  },
});

With Custom Request Options

import { AdpAgent } from "@ag-kit/adapter-adp";

const agent = new AdpAgent({
  name: "my-adp-agent",
  description: "An ADP agent with custom config",
  adpConfig: {
    appKey: "your-app-key",
    request: {
      baseUrl: "https://wss.lke.cloud.tencent.com", // Custom base URL (leave empty for default value)
      endpoint: "/v1/qbot/chat/sse", // Custom endpoint (leave empty for default value)
      body: {
        modelName: "gpt-4", // Specify model
        searchNetwork: "enable", // Enable web search
        workflowStatus: "enable", // Enable workflows
        systemRole: "You are a helpful assistant", // Custom system prompt
      },
    },
  },
});

Running the Agent

import { randomUUID } from "crypto";

const runId = randomUUID();
const threadId = randomUUID();

const observable = agent.run({
  runId,
  threadId,
  messages: [
    {
      id: randomUUID(),
      role: "user",
      content: "Hello, how can you help me?",
    },
  ],
  forwardedProps: {
    // Request body options
    visitorBizId: "user-123", // Visitor (User) ID
    customVariables: {
      key1: "value1",
    },
  },
});

observable.subscribe({
  next: (event) => console.log(event),
  complete: () => console.log("Done"),
  error: (err) => console.error(err),
});

API Reference

AdpAgent

Agent class that extends AbstractAgent and connects to Tencent Cloud ADP services.

Constructor:

constructor(config: AgentConfig & { adpConfig: AdpConfig })

AdpConfig

Configuration options for the ADP adapter.

interface AdpConfig {
  appKey?: string; // ADP application key (optional if ADP_APP_KEY env is set)
  credential?: {
    secretId?: string; // Tencent Cloud secret ID (optional if TENCENTCLOUD_SECRETID env is set)
    secretKey?: string; // Tencent Cloud secret key (optional if TENCENTCLOUD_SECRETKEY env is set)
    token?: string; // Session token (optional if TENCENTCLOUD_SESSIONTOKEN env is set)
  };
  historyCount?: number; // Number of history messages to retrieve (reserved)
  request?: {
    baseUrl?: string; // Base URL for ADP API (default: https://wss.lke.cloud.tencent.com)
    endpoint?: string; // API endpoint (default: /v1/qbot/chat/sse)
    body?: Partial<AdpChatRequest>; // Additional request body options
  };
}

AdpChatRequest Options

For further information, please check the ADP product documentation.

interface AdpChatRequest {
  streamingThrottle?: number; // Stream reply frequency control
  customVariables?: Record<string, string>; // Custom parameters for workflows
  systemRole?: string; // Role instructions (prompt)
  incremental?: boolean; // Whether to output content incrementally
  searchNetwork?: "" | "enable" | "disable"; // Web search toggle
  modelName?: string; // Specify model name
  stream?: "" | "enable" | "disable"; // Streaming toggle
  workflowStatus?: "" | "enable" | "disable"; // Workflow toggle
}

Supported Events

The adapter emits the following AG-UI events:

• RUN_STARTED / RUN_FINISHED / RUN_ERROR - Run lifecycle events
• TEXT_MESSAGE_CHUNK (TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END) - Streaming text response chunks
• THINKING_START / THINKING_END - Thinking process boundaries
• THINKING_TEXT_MESSAGE_START / THINKING_TEXT_MESSAGE_CONTENT / THINKING_TEXT_MESSAGE_END - Thinking content events
• TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT - Workflow tool call events

Requirements

• @ag-ui/client: AG-UI client protocol
• axios: HTTP client for API requests
• rxjs: Reactive extensions for JavaScript
• tencentcloud-sdk-nodejs-lke: Tencent Cloud LKE SDK

Related Resources

• AG-Kit Documentation
• Tencent Cloud ADP Documentation
• AG-Kit Examples