Node SDK

ChatBotKit Node SDK es un kit de desarrollo de software que permite a los desarrolladores crear interfaces de IA conversacional y chatbots. Proporciona un conjunto de herramientas, bibliotecas y API para ayudar a los desarrolladores a crear chatbots para diferentes plataformas.

SDKs

El SDK de ChatBotKit para Node se compone de varios paquetes individuales. Cada paquete aporta características específicas para la plataforma de destino:

Instalación

To install ChatBotKit Node SDK, simply run the following command in your terminal:

npm install @chatbotkit/sdk

Additional SDKs for your platform of choice can be installed in a similar way:

npm install @chatbotkit/next @chatbotkit/react

Utilización

ChatBotKit Node SDK es compatible con CommonJS y Modules. Puedes importar el SDK en tu código de la siguiente manera:

const { ChatBotKit } = require('@chatbotkit/sdk')

...o si prefieres el estilo módulo puedes hacer esto:

import { ChatBotKit } from '@chatbotkit/sdk'

La documentación de TypeScript también está disponible en https://chatbotkit.github.io/node-sdk/.

Compatibilidad

El Node SDK es compatible con todos los entornos JavaScript incluyendo: AWS Lambda, Vercel Serverless, Vercel Edge, Cloudflare Workers, Browser y muchos más.

Instanciación

El SDK consta de varias bibliotecas de clientes. Los clientes son objetos de clase que contienen todos los métodos disponibles para interactuar con una categoría concreta de métodos de la API de ChatBotKit. Los métodos se pueden importar y utilizar de forma independiente. Por lo tanto, tanto la programación orientada a objetos como la funcional son totalmente compatibles.

Importar la parte superior ChatBotKit le da acceso a todas las funcionalidades. Por ejemplo:

// access all clients

import { ChatBotKit } from '@chatbotkit/sdk'

Las clases de cliente individuales pueden importarse así:

// access only the conversation client

import { ConversationClient } from '@chatbotkit/sdk/conversation/index.js'

Antes de empezar a utilizar un cliente, debe instanciar su clase. Este principio se aplica a todos los clientes del SDK.

import { ConversationClient } from '@chatbotkit/sdk/conversation/index.js'

const client = new ConversationClient({
  // options
})

Acceder a métodos individuales es tan fácil como importar el cliente base y la versión del método deseado. Por ejemplo:

import { Client } from '@chatbotkit/sdk/client.js'
import { conversationList } from '@chatbotkit/sdk/conversation/v1.js'

const client = new Client({
  // options
})

await conversationList(client)

Autenticación

Todos los clientes deben instanciarse con un secreto.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

El secreto puede ser un token de API, que le da acceso a todos los métodos de la API, o un token de sesión limitado, que sólo le da acceso a unos pocos métodos de conversación. Este último se utiliza para acceder de forma segura a las conversaciones vinculadas a tus usuarios individuales.

Además del secreto también puede pasar en runAsUserId si necesita invocar la solicitud en nombre de una cuenta secundaria en una configuración de cuentas de tipo padre-hijo (consulte API para socios). El siguiente ejemplo muestra cómo configurar el SDK:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here',
  runAsUserId: '...the child user id here'
})

Paginación

Todos los métodos de lista admiten la paginación basada en el cursor. Los resultados están siempre en orden cronológico inverso, lo que significa que los elementos más recientes están siempre en la parte superior. Para obtener la página siguiente, el cursor debe especificar el ID del último elemento. Por ejemplo:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

// get first page

const page1 = await client.conversation.list()

// get the second page

const page2 = await client.conversation.list({ cursor: page1.items.at(-1).id })

También puede utilizar el streaming para acceder a todos los elementos sin necesidad de paginar manualmente los resultados. Esta potente función se analiza en la siguiente sección.

Streaming

Streaming is a powerful feature which allows you to access large quantities of ChatBotKit data without manually paginating the results. Streaming is also useful to tap into ChatBotKit events when interacting with your ChatBotKit bots and integrations. Streaming simplifies tremendously all types of access patterns.

Todos los métodos de lista soportan streaming por defecto, lo que significa que podemos paginar fácilmente a través de todos los elementos y acceder a todos los resultados sin paginaciones manuales. Por ejemplo:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.list().stream()) {
  if (type === 'item') {
	  console.log('conversation', data)
  }
}

Del mismo modo, podemos acceder a varios eventos al realizar operaciones de finalización y de otro tipo, por ejemplo:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.complete(null, { messages }).stream()) {
  if (type === 'token') {
    console.log('token', data)
  }
}

Observe que el método stream produce objetos compuestos por parámetros de tipo y datos. El tipo corresponde al tipo de evento y los datos representan la información asociada. Métodos como conversation. complete producen varios tipos de eventos, no sólo simples tokens.

Excepciones

Todos los métodos pueden lanzar excepciones. Todas las excepciones tienen una firma de error estándar. Por ejemplo:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

try {
  const page = await client.conversation.list()
} catch (e) {
  console.log('message', e.message)
  console.log('code', e.code)
}

Cada excepción contiene las siguientes propiedades:

Los tipos de código más comunes son:

Todas las excepciones de la API producen también el código de estado correspondiente.

Reaccione

El SDK de ChatBotKit React ofrece un amplio conjunto de funciones y capacidades, entre las que se incluyen:

• userConversationManager: Un React Hook para gestionar el flujo de conversaciones. Maneja todo el trabajo pesado de enviar y recibir mensajes, así como indicadores de pensamiento y escritura.
• AutoTextarea: Un componente React que redimensiona automáticamente el textarea para ajustarlo al contenido. Útil para interfaces de chat que permiten a los usuarios escribir mensajes.
• ChatInput: Un componente React que proporciona una interfaz de entrada de chat. Útil para interfaces de chat para permitir a los usuarios escribir mensajes. Maneja automáticamente modificadores como ctrl, cmd y shift.
• Mensajes de chat: Un componente React que proporciona una interfaz de mensajes de chat. Útil para interfaces de chat para mostrar mensajes.

Siguiente

The ChatBotKit SDK for Next.js is crafted to integrate chatbot functionalities seamlessly into Next.js applications, specifically optimized for Next.js Edge runtime environments.

El SDK incluye actualmente las siguientes utilidades:

• flujo: Esta función se puede utilizar para transmitir cualquier respuesta de ChatBotKit al cliente. Codificará automáticamente la respuesta como JSONL y es totalmente compatible con @chatbotkit/react. useConversationManager gancho.

Ejemplos

En la próxima sección, nos adentraremos en una variedad de casos de uso típicos, proporcionando ideas prácticas para su comprensión. Para quienes busquen situaciones más complejas, en el repositorio oficial de Node SDK Examples encontrará una gran cantidad de ejemplos avanzados. Este recurso está diseñado para enriquecer aún más tus conocimientos y habilidades.

Finalización de la conversación

Se puede completar el siguiente mensaje de una conversación proporcionando el historial completo de la conversación hasta el momento. Por ejemplo, para obtener el siguiente mensaje de la conversación podemos hacer lo siguiente:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

const { text } = await client.conversation.complete({ model: 'gpt-4', messages })

console.log('bot:', text)

Tenga en cuenta que el método completo está sujeto a un tiempo de espera de 30 segundos. Por esta razón, recomendamos utilizar la API de streaming en su lugar.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.complete(null, { model: 'gpt-4', messages }).stream()) {
  if (type === 'result') {
    console.log('bot:', data)
  }
}

El ejemplo anterior no almacena la conversación. El siguiente ejemplo muestra cómo hacerlo.

Crear y completar conversaciones

Para almacenar una conversación, primero tenemos que crearla.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const conversation = await client.conversation.create({
  backstory: '...your backstroy here',
  model: 'gpt-4'
})

Después podemos interactuar con la conversación de forma similar al ejemplo anterior.

for await (const { type, data } of conversation.complete(null, { text: 'Hello!' }).stream()) {
  if (type === 'result') {
    console.log('bot:', data)
  }
}

Observe que en lugar de enviar el historial completo de la conversación, sólo enviamos el mensaje del usuario con el parámetro de texto.

También puedes dividir esto en dos pasos. Esto es particularmente útil cuando tienes un proceso asíncrono donde el mensaje es capturado en un lugar pero completado en una parte diferente del código. Por ejemplo:

await conversation.send({ text: 'Hello!' })

Podemos recibir el mensaje del bot así:

const { text } = await conversation.receive()

Ten en cuenta que el método de recepción también admite streaming.

Sesiones de conversación

To enable secure client-side interaction, we need to create a session and initialise the SDK client-side. We are still using the same code-base server-side and client-side without swapping our mental model. Here is an example.

// server

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const conversation = await client.conversation.create({
  backstory: '...your backstroy here',
  model: 'gpt-4'
})

const { token } = await client.conversation.session.create(conversation.id)

// pass the token to the client

En el cliente podemos utilizar el token para interactuar con la API de forma segura.

// client

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: token // is the token passed from the server
})

await conversation.send({ text: 'Hello!' })

const { text } = await conversation.receive()

Ten en cuenta que las sesiones caducan. Proporcionamos el tiempo de expiración del servidor en el parámetro expiresAt respond. Necesitas llevar un registro de este tiempo o manejar excepciones( códigoNOT_AUTHORIZED ). También hay que tener en cuenta que los tokens de sesión están limitados únicamente a la conversación actual. En otras palabras, el usuario sólo puede interactuar con el chatbot y no con cualquier otro método de la API.

Creación de conjuntos de datos y registros

A common use-case is to create and import Datasets and Dataset Records. This is a very easy process.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const dataset = await client.dataset.create({
  name: '...the dataset name',
  description: '...the dataset description',
})

await client.dataset.record.create(dataset.id, {
  text: '...the record text'
})

Búsqueda de conjuntos de datos

Searching the dataset is part of the conversational flow so typically you do not need to do that when interacting with your conversational AI bot. However, this method is also available in case it is needed. This is how to use it.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const { records } = await client.dataset.search('...dataset id', '...my search')

// do something wihth the found records

Conclusión

Con esto concluye la documentación de ChatBotKit Node SDK. Para más información sobre cómo utilizar el SDK, consulta el repositorio oficial en https://github.com/chatbotkit/node-sdk.