Migrating to the v2 API

Overview

With the v2 API, your client app communicates with an assistant, which is an orchestration layer that offers several capabilities, including automatic state management, skill versioning, and easier deployment.

All communication with an assistant takes place within the context of a session, which maintains conversation state throughout the duration of the conversation. State data, including any context variables that are defined by your dialog or client application, are automatically stored by watsonx Assistant, without any action required on the part of your application.

State data persists until you explicitly delete the session, or until the session times out because of inactivity.

If you prefer to manage state yourself, the v2 API also provides a stateless message method that functions more like the v1 API. If you use the stateless message method, you do not need to explicitly create or delete sessions, and your app is responsible for maintaining context. For more information about the stateless message method, see the API Reference.

If you have an existing application that uses the v1 API to send user input directly to a workspace, migrating your app to use the v2 API is a straightforward process.

Assistant ID

The v2 runtime API sends messages to an assistant. On the Assistant Settings page, find the assistant ID. Your application uses this ID to communicate with the assistant. The service credentials are the same for both the v1 and v2 APIs.

Currently, there is no API support for retrieving an assistant ID. To find the assistant ID, you must use the watsonx Assistant user interface.

Call the v2 runtime API

After you create an assistant, you can update your client application to use the v2 runtime API instead of the v1 runtime API.

1. Before sending the first message in a conversation, use the v2 Create a session method to create a session. Save the returned session ID:

   service
   .createSession({
    assistant_id: assistantId,
   })
   .then(res => {
    sessionId = res.session_id;
   })
   

   session_id = service.create_session(
      assistant_id = assistant_id
   ).get_result()['session_id']
   

   CreateSessionOptions createSessionOptions = new CreateSessionOptions.Builder(assistantId).build();
   SessionResponse session = service.createSession(createSessionOptions).execute().getResult();
   String sessionId = session.getSessionId();
   

2. Use the v2 Send user input to assistant method to send user input to the assistant. Instead of specifying the workspace ID as you did with the v1 API, you specify the assistant ID and the session ID:

   service
     .message({
       assistant_id: assistantId,
       session_id: sessionId,
       input: messageInput
     })
   

    response = service.message(
       assistant_id,
       session_id,
       input = message_input
    ).get_result()
   

    MessageInput input = new MessageInput.Builder().text(inputText).build();
    MessageOptions messageOptions = new MessageOptions.Builder(assistantId, sessionId)
      .input(input)
      .build();
    MessageResponse response = service.message(messageOptions)
      .execute()
      .getResult();
   

   The basic message structure has not changed; in particular, the user input is still sent as input.text.

3. After a conversation ends, use the v2 Delete session method to delete the session.

   service
     .deleteSession({
       assistant_id: assistantId,
       session_id: sessionId,
     })
   

   service.delete_session(
       assistant_id = assistant_id,
       session_id = session_id
   )
   

   DeleteSessionOptions deleteSessionOptions = new DeleteSessionOptions.Builder(assistantId, sessionId
     .build();
   service.deleteSession(deleteSessionOptions).execute();
   

   If you do not explicitly delete the session, it will be automatically deleted after the configured timeout interval. The timeout duration depends on your plan.

To see examples of the v2 APIs in the context of a simple client application, see Building a custom client using the API.

Handle the v2 response format

Your application might need to be updated to handle the v2 runtime response format, depending on which parts of the response your application needs to access:

• Output for all response types (such as text and option) are still returned in the output.generic object. Application code for handling these responses should work without modification.

• Detected intents and entities are now returned as part of the output object, rather than at the root of the response JSON.

• The conversation context is now organized into two objects:

  • The global context contains system-level context data that is shared by all skills in the assistant.

  • The skill context contains any user-defined context variables that are used by your dialog skill.

  However, keep in mind that state data, including conversation context, is now maintained by the assistant, so your application might not need to access the context at all (see Let the assistant maintain state).

Refer to the v2 API Reference for complete documentation of the v2 response format.

Let the assistant maintain state

For most applications, you can now remove any code included for maintaining state. It is no longer necessary to save the context and send it back to watsonx Assistant with each turn of the conversation. The context is automatically maintained by watsonx Assistant and can be accessed by your dialog as before.

Note that with the v2 API, the context is by default not included in responses to the client application. However, your code can still access context variables if necessary:

• You can still send a context object as part of the message input. Any context variables that you include are stored as part of the context maintained by watsonx Assistant. (If the context variable you send already exists in the context, the new value overwrites the previously stored value.)

  Make sure the context object that you send conforms to the v2 format. All user-defined context variables that are sent by your application should be part of the skill context; typically, the only global context variable you might need to set is system.user_id, which is used by Plus and Premium plans for billing purposes.

• You can still retrieve context variables from either the global or skill context. To have the context object included with message responses, use the return_context property in the message input options. For more information, see Accessing context data in dialog.