This document provides examples that demonstrate how to use agents.
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.
To run the following examples, you need Python SDK 1.18.0 or later and Java SDK 2.14.2 or later. To update the Python SDK, run the pip install -U dashscope command.
Simple Assistant example
import json
import sys
from http import HTTPStatus
from dashscope import Assistants, Messages, Runs, Threads
def create_assistant():
# create assistant with information
assistant = Assistants.create(
model='qwen-max', # This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant.', # noqa E501
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
print('Failed: ')
print(res)
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant()
print(assistant)
verify_status_code(assistant)
# create thread.
thread = Threads.create(
messages=[{
'role': 'user',
'content': 'How to make delicious beef and potato stew?'
}])
print(thread)
verify_status_code(thread)
# create run
run = Runs.create(thread.id, assistant_id=assistant.id)
print(run)
verify_status_code(run)
# wait for run completed or requires_action
run_status = Runs.wait(run.id, thread_id=thread.id)
print(run_status)
# get the thread messages.
msgs = Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
Simple Assistant example (streaming output)
Copy
import json
import sys
from http import HTTPStatus
from dashscope import Assistants, Messages, Runs, Threads
def create_assistant():
# create assistant with information
assistant = Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant.', # noqa E501
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
print('Failed: ')
print(res)
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant()
print(assistant)
verify_status_code(assistant)
# create thread.
thread = Threads.create(
messages=[{
'role': 'user',
'content': 'How to make delicious beef and potato stew?'
}])
print(thread)
verify_status_code(thread)
# create run with stream.
run_iterator = Runs.create(thread.id,
assistant_id=assistant.id,
stream=True)
# iterator over the event and message.
for event, msg in run_iterator:
print(event)
print(msg)
# get the thread messages.
msgs = Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
Make function calls using the Assistant
import json
import sys
from http import HTTPStatus
from dashscope import Assistants, Messages, Runs, Steps, Threads
def create_assistant_call_function():
# create assistant with information
assistant = Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant. When asked a question, use tools wherever possible.', # noqa E501
tools=[{
'type': 'function',
'function': {
'name': 'big_add',
'description': 'Add to number',
'parameters': {
'type': 'object',
'properties': {
'left': {
'type': 'integer',
'description': 'The left operator'
},
'right': {
'type': 'integer',
'description': 'The right operator.'
}
},
'required': ['left', 'right']
}
}
}],
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
print('Failed: ')
print(res)
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant_call_function()
print(assistant)
verify_status_code(assistant)
# create thread.
thread = Threads.create()
print(thread)
verify_status_code(thread)
# create a message.
message = Messages.create(thread.id, content='Add 87787 to 788988737.')
print(message)
verify_status_code(message)
# create a new run to run message
message_run = Runs.create(thread.id, assistant_id=assistant.id)
print(message_run)
verify_status_code(message_run)
# get run statue
run_status = Runs.get(message_run.id, thread_id=thread.id)
print(run_status)
verify_status_code(run_status)
# wait for run completed or requires_action
run_status = Runs.wait(message_run.id, thread_id=thread.id)
print(run_status)
# if prompt input tool result, submit tool result.
# should call big_add
if run_status.required_action:
tool_outputs = [{
'output':
'789076524'
}]
run = Runs.submit_tool_outputs(message_run.id,
thread_id=thread.id,
tool_outputs=tool_outputs)
print(run)
verify_status_code(run)
# wait for run completed or requires_action
run_status = Runs.wait(message_run.id, thread_id=thread.id)
print(run_status)
verify_status_code(run_status)
run_steps = Steps.list(run.id, thread_id=thread.id)
print(run_steps)
verify_status_code(run_steps)
# get the thread messages.
msgs = Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
Make function calls using the Assistant (streaming output)
The Java example in this section demonstrates how to generate a JSON schema, including the implementation of the description field.# yapf: disable
import json
import sys
from http import HTTPStatus
import dashscope
from dashscope import Assistants, Messages, Runs, Steps, Threads
def create_assistant_call_function():
# create assistant with information
assistant = Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant. When asked a question, use tools wherever possible.', # noqa E501
tools=[{
'type': 'function',
'function': {
'name': 'big_add',
'description': 'Add to number',
'parameters': {
'type': 'object',
'properties': {
'left': {
'type': 'integer',
'description': 'The left operator'
},
'right': {
'type': 'integer',
'description': 'The right operator.'
}
},
'required': ['left', 'right']
}
}
}],
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
print('Failed: ')
print(res)
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant_call_function()
print(assistant)
verify_status_code(assistant)
# create run
run_iterator = Runs.create_thread_and_run(thread={'messages': [{
'role': 'user',
'content': 'What is transformer? Explain it in simple terms.'
}]}, assistant_id=assistant.id, stream=True)
thread = None
for event, run in run_iterator:
print(event)
print(run)
if event == 'thread.created':
thread = run
verify_status_code(run)
run_status = Runs.get(run.id, thread_id=thread.id)
print(run_status)
verify_status_code(run_status)
# list run steps
run_steps = Steps.list(run.id, thread_id=thread.id)
print(run_steps)
verify_status_code(run_steps)
# create a message.
message = Messages.create(thread.id, content='Add 87787 to 788988737.')
print(message)
verify_status_code(message)
# create a new run to run message
responses = Runs.create(thread.id, assistant_id=assistant.id, stream=True)
for event, message_run in responses:
print(event)
print(message_run)
verify_status_code(message_run)
# get run statue
run_status = Runs.get(message_run.id, thread_id=thread.id)
print(run_status)
verify_status_code(run_status)
# if prompt input tool result, submit tool result.
# should call big_add
if run_status.required_action:
tool_outputs = [{
'output':
'789076524'
}]
# submit output with stream.
responses = Runs.submit_tool_outputs(message_run.id,
thread_id=thread.id,
tool_outputs=tool_outputs,
stream=True)
for event, run in responses:
print(event)
print(run)
verify_status_code(run)
run_status = Runs.get(run.id, thread_id=thread.id)
print(run_status)
verify_status_code(run_status)
run_steps = Steps.list(run.id, thread_id=thread.id)
print(run_steps)
verify_status_code(run_steps)
# get the thread messages.
msgs = Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
Call tools using the Assistant
You may need to request permission to use the tools.
List of supported tools
Tool | Feature |
|---|---|
quark_search | Calls Quark Search to provide relevant results. |
text_to_image | Calls the text-to-image tool to generate images based on a prompt. |
code_interpreter | Code interpreter plugin. |
Quark Search example
Copy
import json
import sys
from http import HTTPStatus
import dashscope
def create_assistant():
# create assistant with information
assistant = dashscope.Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant. When asked a question, use tools wherever possible.', # noqa E501
tools=[{
'type': 'quark_search'
}],
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant()
print(assistant)
verify_status_code(assistant)
# create a thread.
thread = dashscope.Threads.create()
print(thread)
verify_status_code(thread)
# create a message.
message = dashscope.Messages.create(thread.id, content='Can you check the weather in Beijing today?')
print(message)
verify_status_code(message)
# create a new run to run message
message_run = dashscope.Runs.create(thread.id, assistant_id=assistant.id)
print(message_run)
verify_status_code(message_run)
# wait for run completed
run = dashscope.Runs.wait(message_run.id, thread_id=thread.id)
print(run)
run = dashscope.Runs.get(run.id, thread_id=thread.id)
print(run)
verify_status_code(run)
run_steps = dashscope.Steps.list(run.id, thread_id=thread.id)
print(run_steps)
verify_status_code(run_steps)
# get the thread messages.
msgs = dashscope.Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4, ensure_ascii=False))
Call the Quark tool using the Assistant (streaming output)
Copy
import json
import sys
from http import HTTPStatus
import dashscope
def create_assistant():
# create assistant with information
assistant = dashscope.Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant. When asked a question, use tools wherever possible.', # noqa E501
tools=[{
'type': 'quark_search'
}],
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
print('Failed: ')
print(res)
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant()
print(assistant)
verify_status_code(assistant)
# create a thread.
thread = dashscope.Threads.create()
print(thread)
verify_status_code(thread)
# create a message.
message = dashscope.Messages.create(thread.id,
content='What is the weather like in Beijing today?')
print(message)
verify_status_code(message)
# create a new run to run message
stream_iterator = dashscope.Runs.create(thread.id,
assistant_id=assistant.id,
stream=True)
for event, msg in stream_iterator:
print(event)
print(msg)
verify_status_code(msg)
# get run statue
# run_9fa03862-aa36-4e1c-b2a7-9fdd91cb9a1d
run = dashscope.Runs.get(msg.id, thread_id=thread.id)
print(run)
verify_status_code(run)
# print run status, to verify run is completed.
print(run.status)
run_steps = dashscope.Steps.list(run.id, thread_id=thread.id)
print(run_steps)
verify_status_code(run_steps)
# get the thread messages.
msgs = dashscope.Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4, ensure_ascii=False))
Text-to-image example
Copy
import json
import sys
from http import HTTPStatus
import dashscope
def create_assistant():
# create assistant with information
assistant = dashscope.Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant. When asked a question, use tools wherever possible.', # noqa E501
tools=[{
'type': 'text_to_image'
}],
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant()
print(assistant)
verify_status_code(assistant)
# create a thread.
thread = dashscope.Threads.create()
print(thread)
verify_status_code(thread)
# create a message.
message = dashscope.Messages.create(thread.id, content='Draw a picture of a cute kitten lying on the sofa.')
print(message)
verify_status_code(message)
# create a new run to run message
message_run = dashscope.Runs.create(thread.id, assistant_id=assistant.id)
print(message_run)
verify_status_code(message_run)
# get run statue
run = dashscope.Runs.get(message_run.id, thread_id=thread.id)
print(run)
verify_status_code(run)
# print run status, to verify run is completed.
print(run.status)
# wait for run completed or requires_action
run = dashscope.Runs.wait(run.id, thread_id=thread.id)
print(run)
run = dashscope.Runs.get(run.id, thread_id=thread.id)
print(run)
verify_status_code(run)
run_steps = dashscope.Steps.list(run.id, thread_id=thread.id)
print(run_steps)
verify_status_code(run_steps)
# get the thread messages.
msgs = dashscope.Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4, ensure_ascii=False))
Call the code interpreter plugin
import json
import sys
from http import HTTPStatus
import dashscope
def create_assistant():
# create assistant with information
assistant = dashscope.Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='A tool helper.',
instructions='You are a helpful assistant. When asked a question, use tools wherever possible.', # noqa E501
tools=[{
'type': 'code_interpreter'
}],
)
return assistant
def verify_status_code(res):
if res.status_code != HTTPStatus.OK:
sys.exit(res.status_code)
if __name__ == '__main__':
# create assistant
assistant = create_assistant()
print(assistant)
verify_status_code(assistant)
# create a thread.
thread = dashscope.Threads.create()
print(thread)
verify_status_code(thread)
# create a message.
message = dashscope.Messages.create(thread.id, content='There are some chickens and rabbits in a cage. From the top, there are 100 heads. From the bottom, there are 334 feet. Use a tool to calculate how many chickens and rabbits are in the cage.')
print(message)
verify_status_code(message)
# create a new run to run message
message_run = dashscope.Runs.create(thread.id, assistant_id=assistant.id)
print(message_run)
verify_status_code(message_run)
# get run statue
run = dashscope.Runs.get(message_run.id, thread_id=thread.id)
print(run)
verify_status_code(run)
# print run status, to verify run is completed.
print(run.status)
# wait for run completed or requires_action
run = dashscope.Runs.wait(run.id, thread_id=thread.id)
print(run)
run = dashscope.Runs.get(run.id, thread_id=thread.id)
print(run)
verify_status_code(run)
run_steps = dashscope.Steps.list(run.id, thread_id=thread.id)
print(run_steps)
verify_status_code(run_steps)
# get the thread messages.
msgs = dashscope.Messages.list(thread.id)
print(msgs)
print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4, ensure_ascii=False))
Use the RAG feature with the Assistant
from dashscope import Assistants, Messages, Runs, Threads
assistant = Assistants.create(
# This example uses qwen-max. You can change the model name as needed. For a list of models, see https://help.aliyun.com/model-studio/getting-started/models
model='qwen-max',
name='smart helper',
description='An intelligent assistant that can call existing plugins to help users based on their requests.',
instructions='You are an intelligent assistant. Remember the following information: ${document1}', # from rag library
tools=[
{
"type": "rag",
"prompt_ra": {
"pipeline_id": ["fqcioazfej","fqcioazfej"], # Knowledge base IDs ["9c0simc8q8", "13loysdy91"]
"multiknowledge_rerank_top_n":10, # Total number of segments retrieved from multiple knowledge bases
"rerank_top_n":5, # Number of segments retrieved from a single knowledge base
"parameters": {
"type": "object",
"properties": {
"query_word": {
"type": "str",
"value": "${document1}"
}
}
}
}
},
]
)
def send_message(assistant, message='What is Model Studio?'):
print(f"Query: {message}")
# create thread.
# create a thread.
thread = Threads.create()
print(thread)
# create a message.
message = Messages.create(thread.id, content=message)
# create run
run = Runs.create(thread.id, assistant_id=assistant.id)
print(run)
# # get run statue
# run_status = Runs.get(run.id, thread_id=thread.id)
# print(run_status)
# wait for run completed or requires_action
run_status = Runs.wait(run.id, thread_id=thread.id)
# print(run_status)
# if prompt input tool result, submit tool result.
run_status = Runs.get(run.id, thread_id=thread.id)
print(run_status)
# verify_status_code(run_status)
# get the thread messages.
msgs = Messages.list(thread.id)
# print(msgs)
# print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4))
print("Run result:")
for message in msgs['data'][::-1]:
print("content: ", message['content'][0]['text']['value'])
print("\n")
if __name__ == "__main__":
send_message(assistant, message='What is Model Studio?')