Skip to main content
Use the official XpertAI TypeScript SDK, published as @xpert-ai/xpert-sdk, for new integrations in TypeScript or JavaScript projects. The SDK supports servers, scripts and backend workflows independently of ChatKit. If your development environment uses Python, Java, Go or another language, use the TypeScript SDK implementation and the HTTP API reference below to build a client or SDK in that language. Preserve the authentication, request and response structures, SSE event handling and reconnection behavior. Follow the latest official documentation and TypeScript SDK source for current usage.
Legacy AI/v1 OpenAPI integration, such as POST /api/ai/v1/chat, is deprecated and no longer maintained; availability is not guaranteed. This notice applies to old endpoints. The SDK use cases below remain available and have been updated to use the official SDK.

Before you start

  1. Publish the agent and obtain its ID (xpertId), the assistant_id field from agent search.
  2. Create an API Key with access to that agent and store it in a server environment variable.
  3. Set XPERTAI_API_URL, for example https://api.xpertai.cn/api/ai. Use your own address for private deployments; do not append /v1.
  4. Use Node.js 18 or later and install the SDK:
Create your API Key here: Create an API Key

Start a conversation with the SDK

This example creates a thread and starts a run, then waits for its result. Set XPERTAI_API_KEY and XPERTAI_XPERT_ID before running it.
Save thread.thread_id and reuse the thread for subsequent messages with client.runs.wait() or client.runs.stream(). For an agent conversation, pass assistantId when creating the thread and use the same agent ID for subsequent runs. The SDK serializes assistantId as the HTTP field assistant_id. The protocol allows omission to create an unbound thread under the current request identity. If a later run uses a different execution identity, conversation access checks can return 403. Binding the agent at creation establishes its scope early; it does not grant additional access.

Thread creation succeeds, but the run returns 403

201 Created confirms thread creation, not permission to run the agent. If a run returns You do not have access to this conversation:
  1. Confirm that the API Key can access the published agent. Create a new thread with client.threads.create({ assistantId: xpertId }), then pass the same xpertId to the run. Changing the example does not repair a previously created thread.
  2. Use the same credentials and caller identity when creating and running the thread. Do not reuse a thread belonging to another user or an unrelated agent.
  3. If a new, bound thread still returns 403, have the administrator check the API Key’s effective caller, the conversation’s owner (createdById) and agent binding (xpertId), and the deployed server version. Supplying assistantId does not bypass ownership or scope checks and cannot resolve every 403.

Receive streaming output

For real-time progress, replace the runs.wait() call in the same main() function with:
For streaming calls, check run completion, error and interrupt events. HTTP success or a closed connection alone does not prove the task succeeded. Reconnect to an existing run with client.runs.joinStream(threadId, runId); it subscribes to an existing run and does not start a new one. To print only answer text as it arrives, replace the loop above with the following. Handle other events in your application’s lifecycle logic; filtering text alone does not establish whether the run succeeded.

Query agents

The snippets below reuse client, xpertId, thread and input from the first example. Use them as needed in the same main(). They retain the original agent, thread, run and storage use cases.

Search and retrieve an agent

client.assistants.search() calls POST /api/ai/assistants/search and returns an array of accessible published agents. Select the target agent and use its assistant_id as XPERTAI_XPERT_ID (the xpertId or XP variable in examples). To find a specific agent, pass metadata: { slug: "your-xpert-slug" } with the search options.

Create and manage threads

Specify a thread ID

This specifies the creation ID; it does not pre-fill agent state.

Read thread lists, details and current state

Current state comes from the thread checkpoint and can be read after the first run. See the compatibility section for getHistory() support.

Continue a conversation in the same thread

Reuse the existing thread ID instead of creating a thread for every message.

Background runs and run management

Create a background run

create() returns a run record while execution continues in the background. wait() starts a new run and waits for its result. These are alternative invocation styles; do not call both for the same message.

Read status and list runs

Reuse run.run_id returned by background creation:

Cancel an active run

Execute this when cancellation of that run is intended:

Reconnect to an existing run

Save thread_id and run_id from creation. Streaming creation also exposes the run ID through the onRunCreated callback of runs.stream(). After a disconnection, use joinStream() to subscribe to that existing run:
This subscribes to an existing run instead of starting another task. A new runs.create() or runs.wait() call is not a reconnection and can repeat execution.

Upload an attachment before a conversation

Upload through the current SDK’s contexts client, then pass the returned file handle to the agent:

Persistent Store

Store examples remain available for saving and reading data across runs. Use the agent ID as the first namespace segment; this example adds a child namespace.

Write and read

List namespaces and search data

searchItems() accepts the namespace array as its first argument and query options as its second. Semantic query search requires the appropriate memory model configuration; the example only lists data in the namespace.

Compatibility and unsupported calls

A method exposed by the SDK is not proof that the target deployment implements its server capability. In the current platform source, the following calls from the old examples cannot be presented as runnable cases: These are specific support limits, not deprecation of agent queries, thread management, runs or Store examples. Verify SDK and server versions for private deployments.

Common SDK capabilities

See the SDK repository for SDK updates and complete examples.

HTTP API reference

For direct HTTP integration, the HTTP API Reference sidebar group provides method badges, request fields, responses, cURL examples and a playground for the endpoints used above. These are the current SDK endpoints, independent of ChatKit. Authenticate with your server-side API Key using Authorization: Bearer <API_KEY> or x-api-key. Start by creating a thread, then start a streaming run, or create a background run. To recover an interrupted connection, subscribe to the existing run; do not start the same task again. HTTP wire fields can differ from SDK option names: for example, assistant_id, thread_id and max_depth. Use the request schema on the specific endpoint page. This reference covers the guide’s examples; methods listed above as unsupported are not presented as available endpoints.

Technical support

The SDK continues to evolve. For questions or suggestions, contact xpertai on WeChat for technical discussions.