Skip to main content

Development SDK

Digital Xpert provides a set of APIs and an SDK for developers to interact with Xpert intelligent agents. These APIs allow you to create custom applications to communicate with Digital Xpert's intelligent agents.

The Xpert agent interface follows the Agent Protocol standard, which is a protocol for communication between agents. The Agent Protocol provides a universal way for agents to exchange messages, facilitating interoperability between agents.

  • First, create a Key for authentication to access the Xpert intelligent agent program.
Develop key
Develop Key
  • Use the Key to access the Xpert intelligent agent's REST APIs or use the LangGraph SDK to access the XpertAI platform.

Using the LangGraph SDK to Call the XpertAI Platform​

The XpertAI intelligent agent platform can be interacted with via the LangGraph SDK (@langchain/langgraph-sdk (JS/TS SDK) / langgraph-sdk Python SDK). This SDK encapsulates the core capabilities for communicating with the LangGraph REST API, making it easy to manage core components such as assistants, threads, runs, and persistent storage (store).

info

Reference code: XpertAI SDK Examples

1. Installation​

Ensure that the Node.js environment is installed, then install the SDK in your project:

# Install with yarn
yarn add @langchain/langgraph-sdk
# Or install with npm
npm install @langchain/langgraph-sdk

By default, the SDK connects to http://localhost:8123 (e.g., when started locally with langgraph-cli). Otherwise, you need to specify the API URL or apiKey during configuration (npm).

2. Initialize the Client​

In JavaScript/TypeScript, you can create a Client instance as follows:

import { Client } from "@langchain/langgraph-sdk";

const client = new Client({
  apiUrl: "https://api.mtda.cloud/api/ai/", // Your baseUrl of XpertAI server.
  apiKey: "your-api-key", // API Key of xpert
})

If not explicitly configured, the SDK will connect to http://localhost:8123 by default (npm).

3. Managing Digital Xperts (Agents)​

List Existing Digital Xperts​

import { Client, Assistant } from "@langchain/langgraph-sdk";

// List all xperts
const xperts: Assistant[] = await client.assistants.search({
  metadata: null,
  offset: 0,
  limit: 10,
})
console.log("Experts:", xperts);

Each Digital Xpert is an assistant (npm, LangGraph).

Retrieve a Single Digital Xpert​

const xpert = await client.assistants.get(xpertId);

4. Creating and Managing Threads​

Create a New Thread (Empty State)​

const thread = await client.threads.create(); // Or pass threadId, metadata, etc., as initialization parameters
console.log("New Thread:", thread);

In the example, it returns properties such as thread_id, status, etc. (LangGraph).

Pre-fill State​

const threadWithState = await client.threads.create({
  threadId: "xxxxxxx",
  ifExists: 'raise'
});

This allows you to inject a thread ID during creation (LangGraph).

Query Thread List & Retrieve State​

const list = await client.threads.search({ limit: 10, offset: 0 });
const singleThread = await client.threads.get(thread.thread_id);
const history = await client.threads.getHistory(thread.thread_id, { limit: 50 });

5. Starting Runs​

You can initiate a run for a specific Digital Xpert within a thread, including support for streaming responses.

Start a Streaming Run​

const stream = client.runs.stream(thread.thread_id, assistant.assistant_id, {
  input: { 
    input: "Tell me a joke.", // more parameters 
  },
});
for await (const chunk of streamResponse) {
  const data = (<{ type: 'message', data: string | {type: 'text' | string; text?: string; data?: any} }>chunk.data)
  // Output text messages only
  if (data.type === 'message') {
    if (typeof data.data === 'string') {
      process.stdout.write(data.data)
    } else if (data.data.type === 'text') {
      process.stdout.write(data.data.text ?? '')
    } else {
      // console.log(`Component:`, data.data);
    }
  }
}

This allows processing responses as they are generated, suitable for interactive scenarios (npm).

Other Run Operation Examples​

const run = await client.runs.create(thread.thread_id, assistant.assistant_id, { input: { ... } });
const result = await client.runs.join(thread.thread_id, run.run_id);
await client.runs.cancel(thread.thread_id, run.run_id);
const runsList = await client.runs.list(thread.thread_id, { limit: 10 });

6. Using Store (Persistent Storage)​

Store data that needs to be saved across requests in sessions or tasks.

// Write
await client.store.putItem([xpert_id], "key1", { value: 42 });

// Read
const item = await client.store.getItem([xpert_id], "key1");

// List namespaces
const namespaces = await client.store.listNamespaces({
  prefix: [xpert_id],
  maxDepth: 2,
  limit: 10
});

// Search
const found = await client.store.searchItems({ namespacePrefix: "my", query: "42" });

Detailed interfaces are defined in StoreClient (LangGraph).

7. XpertAI Platform Integration Tips​

  • Configure Default API Address and Key: The API address must be explicitly specified, and the key can be configured uniformly using the environment variable LANGGRAPH_API_KEY.
  • Stream Output to Frontend: Suitable for React and other frontends, you can use the SDK's streaming capabilities to build real-time conversational interfaces.
  • Persistent Memory: Use the Store feature to save key session data, enhancing the agent's memory capabilities.

References​

More Information​

The SDK is still being improved. If you encounter any issues or have suggestions, please add WeChat: xpertai to contact us for technical discussions.