Skip to main content
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Assistant API (Deprecated)

Getting started with Assistant API (Deprecated)

The Assistant API provides a set of development tools to help you easily manage conversation messages and call tools. This topic uses the example of building a painting assistant from scratch to help you quickly learn the basic encoding methods of the Assistant API.

The Assistant API is being deprecated. Migrate to the Responses API as an alternative. The Responses API includes multiple built-in tools and supports multi-turn context management.

Typical process

The following is a typical process for building an agent application (Assistant):
  1. Create an Assistant: When you create an assistant, select a model, provide instructions, and add tools, such as a code interpreter and function calling.
  2. Create a Thread: When a user starts a conversation, create a session thread to track the conversation history.
  3. Send a Message to the Thread: Add the user's message to the conversation.
  4. Start a Run: Run the assistant on the session thread. The assistant parses the message, calls the appropriate tools or services, generates a response, and returns it to you.

Example scenario

Text generation models cannot generate images on their own. A specific text-to-image model is typically required to convert text into images. An agent application created with the Assistant API can automatically optimize the descriptive words provided by the user, call a text-to-image tool to generate high-quality images. For example, to generate a lifelike image of a pet cat, you only need to provide a basic description. The drawing assistant automatically refines the prompt and passes it directly to the text-to-image tool to efficiently complete the image creation task.

Procedure

The following steps guide you through the process in Python for the non-streaming output mode. For the complete Python and Java SDK code for both streaming and non-streaming output, see Complete code at the end of this topic.
image

Step 1: Prepare the development environment

  • Request permission to use plugins: You must first request permission to use the Image Generation plugin. Go to the Plug-ins page in the Model Studio console and click Apply for Plug-in on the corresponding card.
  • Python interpreter: The Assistant API requires Python 3.8 or later. You can check your Python version. To install a specific version of Python, see Download Python.
  • DashScope SDK: We recommend that you use the latest version of the DashScope SDK. You can use the command on the right to check your version. To install a specific version of the DashScope SDK, use pip.
  • API key: The Assistant API requires an Alibaba Cloud Model Studio API key. You can get an API key here. When you use the DashScope SDK for the first time, we recommend that you configure the API key as an environment variable to avoid exposing sensitive information.
# Check the Python interpreter version
python --version

# Check the DashScope SDK
pip list | grep dashscope

# Install DashScope SDK version 1.17.0
pip install dashscope==1.17.0

Step 2: Create an Assistant

After you import the Dashscope SDK, use the create method of the Assistant class to create an Assistant agent. This process involves setting the following key parameters:
  • model: the name of the large language model, used to configure the LLM for the agent
  • name: the name of the agent, used to distinguish it
  • description: a description of the agent's function
  • instructions: instructions in natural language that define the agent's role and task
  • tools: a list of tools configured for the agent
In our example, the goal is to build an Assistant that focuses on painting. Because the text-to-image tool has high requirements for language understanding, we select Qwen-Max as the reasoning model to enhance the Assistant's semantic understanding and text generation capabilities.The configuration details of the agent, including its name, function description, and instructions, are clearly shown in the accompanying code snippet.To enrich the agent's functionality and practicality, we integrate the official pre-built plugin Image Generation. This ensures the agent can automatically generate corresponding image content based on the received text descriptions.You can create an unlimited number of Assistants. However, frequent calls to a single model may trigger rate limiting. We recommend that you configure different models for your Assistants based on their use cases.For more information about how to use the API, see Assistants API.
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a new painting assistant using Qwen-Max
painting_assistant = dashscope.Assistants.create(
    model='qwen-max',  # Use the Qwen-Max model for enhanced understanding. Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    name='Art Maestro',  # The assistant's name is "Art Maestro"
    description='An AI assistant specializing in painting and art knowledge.',
    instructions='''You are an expert painting assistant. Provide detailed information about painting techniques, art history, and creative guidance.''',
    tools=[
        {
            'type': 'text_to_image',  # A tool for generating images based on descriptions
            'description': 'Use this tool to create visual examples of a painting style, technique, or art concept.'
        }
    ]
)

# Print the assistant's ID to confirm successful creation
print(f"Painting assistant 'Art Maestro' created successfully, ID: {painting_assistant.id}")

Step 3: Create a Thread

A Thread is a key concept in the Assistant API that represents a continuous conversation context.A Thread lets you create a session management thread when a user starts a new conversation. The Assistant can use the Thread to understand the entire conversation context and provide more coherent and relevant responses.We recommend that you:
  • Create a new Thread for each new user or new conversation topic.
  • Continue to use the same Thread when you need to maintain context.
  • Consider creating a new Thread when the conversation topic changes significantly to avoid context confusion.
In the painting assistant scenario, the Thread can track the user's initial request, the Assistant's preliminary suggestions, the user's feedback, and the final painting result, forming a complete creation process. This ensures the coherence and traceability of the entire creation process.For more information about how to use the API, see Threads API.
from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a new empty thread
thread = dashscope.Threads.create()

# Check if the thread was created successfully
if thread.status_code == HTTPStatus.OK:
    print(f"Thread created successfully. Thread ID: {thread.id}")
    print("You can now start a painting conversation with the AI assistant.")
else:
    print(f"Thread creation failed. Status code: {thread.status_code}")
    print(f"Error code: {thread.code}")
    print(f"Error message: {thread.message}")

# Note: This empty thread can now be used to maintain the context of your painting project discussion,
# including any future messages about ragdoll cats or other painting subjects.

Step 4: Add a Message to a Thread

Your input is passed through a Message object. The Assistant API supports sending one or more messages to a single Thread. When you create a Message, consider the following parameters:
  • The unique ID of the Thread: thread_id
  • The content of the message: content
Although there is no hard limit on the number of tokens a Thread can receive, the actual number of tokens passed to the LLM must comply with the model's maximum input length limit. For more information, see the official documentation for each Qwen series model regarding context length.In our scenario, you will send the first message in the Thread through a Message: "Please help me draw a picture of a ragdoll cat." You need to create a Message class. The detailed parameter settings are provided in the accompanying code snippet.For more information about how to use the API, see Messages.
After the Messages.create() method is executed, it automatically adds the message to the thread and triggers spooling. This is equivalent to completing both the message creation and sending operations at the same time, which is the default behavior of the API.
from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a message to tell the assistant what to do.
message = dashscope.Messages.create(thread.id, content='Please help me draw a picture of a ragdoll cat.')

# Check if the message was created successfully
if message.status_code == HTTPStatus.OK:
    print('Message created successfully! Message ID: %s' % message.id)
else:
    print('Message creation failed. Status code: %s, Error code: %s, Error message: %s' % (message.status_code, message.code, message.message))

Step 5: Create and execute a Run

After a user assigns a message to a specific Thread, you can start a Run to activate the pre-set Assistant. The assistant uses all messages in the thread as context, utilizes the specified model and available plugins to intelligently respond to the user's questions, and inserts the generated answers into the thread's message sequence.In this scenario, perform the following steps:
  1. Initialize a run object to drive the painting assistant, passing the thread ID (thread.id) and assistant ID (assistant.id).
  2. Use the run object's wait method (Run.wait) until the execution is complete.
  3. Use the message list method (Messages.list) to retrieve the pet cat picture drawn by the assistant.
This series of operations ensures an automated processing flow for the assistant, from receiving a question to outputting a result.For more information about how to use the API, see Runs API.
Many users may be using the model at the same time, which can extend the processing time. We recommend that you wait until the status shows "complete" before you perform the next operation to ensure a smooth process.
from http import HTTPStatus
import json
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Create a new run to execute the message
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)
if run.status_code != HTTPStatus.OK:
    print('Failed to create assistant, Status code: %s, Error code: %s, Error message: %s' % (run.status_code, run.code, run.message))
else:
    print('Assistant created successfully, ID: %s' % run.id)

# Wait for the run to complete or require action
run = dashscope.Runs.wait(run.id, thread_id=thread.id)
if run.status_code != HTTPStatus.OK:
    print('Failed to get run status, Status code: %s, Error code: %s, Error message: %s' % (run.status_code, run.code, run.message))
else:
    print(run)

# Get the thread messages to get the run output
msgs = dashscope.Messages.list(thread.id)
if msgs.status_code != HTTPStatus.OK:
    print('Failed to get messages, Status code: %s, Error code: %s, Error message: %s' % (msgs.status_code, msgs.code, msgs.message))
else:
    print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4))

Complete code

  • Non-streaming output
  • Streaming output
import dashscope
from http import HTTPStatus
import json
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

def check_status(component, operation):
    if component.status_code == HTTPStatus.OK:
        print(f"{operation} successful.")
        return True
    else:
        print(f"{operation} failed. Status code: {component.status_code}, Error code: {component.code}, Error message: {component.message}")
        return False

# 1. Create a painting assistant
painting_assistant = dashscope.Assistants.create(
    # Model list: https://www.alibabacloud.com/help/en/model-studio/getting-started/models
    model='qwen-max',
    name='Art Maestro',
    description='AI assistant for painting and art knowledge',
    instructions='''Provide information on painting techniques, art history, and creative guidance.
    Use tools for research and image generation.''',
    tools=[
        {'type': 'text_to_image', 'description': 'For creating visual examples'}
    ]
)

if not check_status(painting_assistant, "Assistant creation"):
    exit()

# 2. Create a new thread
thread = dashscope.Threads.create()

if not check_status(thread, "Thread creation"):
    exit()

# 3. Send a message to the thread
message = dashscope.Messages.create(thread.id, content='Please help me draw a picture of a ragdoll cat.')

if not check_status(message, "Message creation"):
    exit()

# 4. Run the assistant on the thread
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)

if not check_status(run, "Run creation"):
    exit()

# 5. Wait for the run to complete
print("Waiting for the assistant to process the request...")
run = dashscope.Runs.wait(run.id, thread_id=thread.id)

if check_status(run, "Run completion"):
    print(f"Run completed, status: {run.status}")
else:
    print("Run not completed.")
    exit()

# 6. Retrieve and display the assistant's response
messages = dashscope.Messages.list(thread.id)

if check_status(messages, "Message retrieval"):
    if messages.data:
        # Display the content of the last message (the assistant's response)
        last_message = messages.data[0]
        print("\nAssistant's response:")
        print(json.dumps(last_message, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
    else:
        print("No messages found in the thread.")
else:
    print("Failed to retrieve the assistant's response.")

# Tip: This code creates a painting assistant, starts a conversation about how to draw a ragdoll cat,
# and displays the assistant's answer.

What to do next

For detailed parameter explanations for Assistant API components, see Assistant API development reference.
Alibaba Cloud Model Studio home pageAlibaba Cloud Model Studio
Get Started
Application Development
Prompt
Application Data
Knowledge Base (RAG)
Plugin
Application Calling
Permissions
Assistant API (Deprecated)
Support