@cloudbase/agent-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 @cloudbase/agent-agents @cloudbase/agent-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
• File Upload: Upload images and documents to COS for multimodal conversations (requires enableUpload: true)

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 "@cloudbase/agent-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 "@cloudbase/agent-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 "@cloudbase/agent-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),
});

With File Upload (Images and Documents)

When enableUpload is set to true, you can send images and documents in messages. Files are automatically uploaded to Tencent Cloud COS and processed by ADP.

Note: File upload requires Tencent Cloud credentials (TENCENTCLOUD_SECRETID and TENCENTCLOUD_SECRETKEY).

import { AdpAgent } from "@cloudbase/agent-adapter-adp";
import { randomUUID } from "crypto";
import * as fs from "fs";

const agent = new AdpAgent({
  name: "my-adp-agent",
  adpConfig: {
    appKey: "your-app-key",
    enableUpload: true, // Enable file upload
    credential: {
      secretId: "your-secret-id",
      secretKey: "your-secret-key",
    },
  },
});

const observable = agent.run({
  runId: randomUUID(),
  threadId: randomUUID(),
  messages: [
    {
      id: randomUUID(),
      role: "user",
      content: [
        { type: "text", text: "What's in this image?" },
        {
          type: "binary",
          mimeType: "image/png",
          filename: "screenshot.png",
          data: fs.readFileSync("./screenshot.png"),
        },
      ],
    },
  ],
});

Supported file types:

• Images: image/png, image/jpeg, image/bmp
• Documents: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, text/plain

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)
  enableUpload?: boolean; // Enable file upload for images and documents (default: false)
  request?: {
    baseUrl?: string; // Base URL for ADP API (default: https://wss.lke.cloud.tencent.com)
    endpoint?: string; // API endpoint (default: /v1/qbot/chat/sse)
    docParseEndpoint?: string; // Document parse API endpoint (default: /v1/qbot/chat/docParse)
    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
• cos-nodejs-sdk-v5: Tencent Cloud COS SDK (for file upload)

Related Resources

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