Skip to main content
Assistant API (Deprecated)

Function calling (Deprecated)

Assistant API mendukung function calling. Fitur ini memungkinkan agen untuk secara otomatis memanggil fungsi eksternal guna menjalankan tugas, seperti menerjemahkan teks. Topik ini menggunakan contoh “Translation Agent” yang sederhana untuk membantu Anda memahami dasar-dasar function calling dengan cepat.

Assistant API sedang ditinggalkan. Migrasikan ke Responses API sebagai alternatif. Responses API mencakup beberapa tool bawaan dan mendukung manajemen konteks multi-turn.

Quick start

Pada contoh ini, Anda akan membuat agen penerjemah dan fungsi bernama translate_text yang dapat dipanggil oleh agen tersebut. Selanjutnya, Anda akan meminta agen untuk menerjemahkan "Hello world" ke dalam bahasa Tionghoa.

Before you begin

Anda dapat menginstal library dependensi yang diperlukan, seperti requests dan dashscope, dengan menjalankan perintah berikut:
pip install requests dashscope

Step 1: Create the "translate_text" function

Pertama, buat fungsi penerjemahan sederhana. Fungsi ini menggunakan tabel terjemahan yang telah ditentukan sebelumnya untuk tujuan demonstrasi.
def translate_text(text, target_language):
    """
    Translates text into the specified target language.
    This is a simple demonstration that uses a predefined translation.

    Parameters:
        text (str): The text to translate.
        target_language (str): The target language code (for example, 'zh', 'es', or 'ja').

    Returns:
        str: The translated text or an error message.
    """
    # A translation dictionary for demonstration.
    mock_translations = {
        ('Hello world', 'zh'): '你好世界',
        ('Hello world', 'es'): '¡Hola Mundo!',
        ('Hello world', 'ja'): 'こんにちは世界',
        ('How are you?', 'zh'): '你好吗?',
        ('How are you?', 'es'): '¿Cómo estás?',
        ('How are you?', 'ja'): 'お元気ですか?'
    }

    try:
        return mock_translations.get((text, target_language),
            f"Translation not found. In a production environment, a translation service would be called here.")
    except Exception as e:
        return f"Translation failed: {str(e)}"
Explanation:
  • Translation feature: Mensimulasikan fitur terjemahan menggunakan tabel terjemahan yang telah ditentukan sebelumnya dan mendukung konversi antar beberapa bahasa.
  • Error handling: Fungsi ini mencakup mekanisme penanganan error dasar untuk memastikan selalu mengembalikan respons yang sesuai dalam semua situasi.
Sekarang, Anda dapat menggunakan Assistant API untuk membuat agen. Agen ini secara otomatis memproses kueri pengguna dan memanggil fungsi translate_text yang telah didefinisikan untuk menyediakan layanan terjemahan.

Step 2: Describe the "translate_text" function

Anda harus mendeskripsikan fungsi translate_text kepada agen. Agen menggunakan deskripsi ini untuk memanggil fungsi dengan benar.
from dashscope import Assistants, Messages, Runs, Threads
import json
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
# Define the translation tool
translation_tool = {
    "type": "function",
    "function": {
        "name": "translate_text",
        "description": "Translates text into the specified target language",
        "parameters": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string",
                    "description": "The text to translate"
                },
                "target_language": {
                    "type": "string",
                    "description": "The target language code (for example, 'zh', 'es', or 'ja')"
                }
            },
            "required": ["text", "target_language"]
        }
    }
}
Explanation:
  • name: Nama fungsi adalah translate_text. Agen menggunakan nama ini untuk memanggil fungsi tersebut.
  • description: Deskripsi tool yang membantu agen memahami tujuannya.
  • parameters: Mendefinisikan parameter fungsi, yang mencakup teks yang akan diterjemahkan dan bahasa target.

Step 3: Create an agent

Sekarang, buat instans Assistant. Instans ini merupakan agen yang akan menggunakan tool terjemahan yang telah Anda definisikan.
# Create an Assistant
assistant = Assistants.create(
    model='qwen-plus',
    name='Translation Agent',
    description='An agent that can translate text between different languages',
    instructions='You are a translation agent. When a user requests a translation, use the translate_text function to help them.',
    tools=[translation_tool]
)
Explanation:
  • model: Menentukan model yang digunakan. Contoh ini menggunakan qwen-plus, yang mendukung pemahaman bahasa dan pemrosesan tugas.
  • name: Nama agen. Atur nilainya menjadi "Translation Assistant".
  • description: Deskripsi tujuan agen, yaitu membantu pengguna menerjemahkan teks.
  • tools: Mendaftarkan translation_tool yang telah Anda definisikan sebelumnya. Hal ini memungkinkan agen untuk memanggil tool tersebut.

Step 4: Create a conversation thread and interact with the agent

Buat thread percakapan baru, tambahkan pesan pengguna ke dalamnya, lalu jalankan agen untuk memproses kueri pengguna.
# Create a new thread
thread = Threads.create()

# Add a user message to the thread
Messages.create(
    thread_id=thread.id,
    role="user",
    content="Please translate 'Hello world' into Chinese."
)

# Run the Assistant
run = Runs.create(thread_id=thread.id, assistant_id=assistant.id)

# Wait for the run to complete
run = Runs.wait(thread_id=thread.id, run_id=run.id)
Explanation:
  • Threads.create(): Membuat thread percakapan baru untuk pesan-pesan selanjutnya.
  • Messages.create(): Menambahkan pesan pengguna ke dalam thread. Dalam kasus ini, pengguna meminta penerjemahan "Hello world" ke bahasa Tionghoa.
  • Runs.create(): Memulai pemrosesan pesan pengguna oleh agen.
  • Runs.wait(): Menunggu hingga agen menyelesaikan pemrosesan.

Step 5: Handle the function call and return the result

Jika agen perlu memanggil tool selama pemrosesan, fungsi translate_text akan dipanggil dan hasilnya dikembalikan.
# Check if a function call is required
if run.required_action:
    for tool_call in run.required_action.submit_tool_outputs.tool_calls:
        if tool_call.function.name == "translate_text":
            args = json.loads(tool_call.function.arguments)
            translation = translate_text(args["text"], args["target_language"])

            # Submit the tool output
            Runs.submit_tool_outputs(
                thread_id=thread.id,
                run_id=run.id,
                tool_outputs=[{"tool_call_id": tool_call.id, "output": translation}]
            )

            # Wait for the new run to complete
            run = Runs.wait(thread_id=thread.id, run_id=run.id)
Explanation:
  • Check for a function call: Jika agen perlu memanggil fungsi, kode Anda memeriksa apakah fungsi yang diminta adalah translate_text, lalu melakukan terjemahan menggunakan fungsi yang telah didefinisikan sebelumnya.
  • Submit the result: Kirim hasil terjemahan ke agen menggunakan Runs.submit_tool_outputs, lalu tunggu respons berikutnya dari agen.

Step 6:Get the agent's response

Setelah agen menyelesaikan pemrosesan, Anda dapat mengambil respons agen dari thread percakapan dan menampilkannya kepada pengguna.
# Get the Assistant's response
messages = Messages.list(thread_id=thread.id)
for message in messages.data:
    if message.role == "assistant":
        print(f"Assistant: {message.content[0].text.value}")

Summary

Dengan mengikuti langkah-langkah ini, Anda telah berhasil membuat agen yang dapat menangani permintaan terjemahan pengguna dan menggunakan fungsi terjemahan untuk melakukan konversi teks. Assistant API mempermudah dan meningkatkan efisiensi pembuatan agen kompleks yang berbasis tugas. Anda dapat memperluas fitur agen sesuai kebutuhan, misalnya dengan menambahkan lebih banyak tool atau memodifikasi instruksi perilaku agen.

Quickly generate descriptions for business functions

Pada contoh Quick Start, Anda perlu mendeskripsikan fungsi "translate_text" kepada agen. Proses ini bisa membosankan. Oleh karena itu, kami menyediakan fungsi konversi sederhana untuk membantu Anda mendeskripsikan fungsi bisnis Anda dengan cepat.
import inspect

def function_to_schema(func) -> dict:
    # Map Python types to JSON schema types
    type_map = {
        str: "string",
        int: "integer",
        float: "number",
        bool: "boolean",
        list: "array",
        dict: "object",
        type(None): "null",
    }

    # Try to get the function's signature
    try:
        signature = inspect.signature(func)
    except ValueError as e:
        # If getting the signature fails, raise an error with the error message
        raise ValueError(
            f"Failed to get signature for function {func.__name__}: {str(e)}"
        )

    # Initialize a dictionary to store parameter types
    parameters = {}
    # Iterate over the function's parameters and map their types
    for param in signature.parameters.values():
        try:
            param_type = type_map.get(param.annotation, "string")
        except KeyError as e:
            # If the parameter's type annotation is unknown, raise an error
            raise KeyError(
                f"Unknown type annotation {param.annotation} for parameter {param.name}: {str(e)}"
            )
        parameters[param.name] = {"type": param_type}

    # Create a list of required parameters (those without a default value)
    required = [
        param.name
        for param in signature.parameters.values()
        if param.default == inspect._empty
    ]

    # Return the function's schema as a dictionary
    return {
        "type": "function",
        "function": {
            "name": func.__name__,
            "description": (func.__doc__ or "").strip(),  # Get the function description (docstring)
            "parameters": {
                "type": "object",
                "properties": parameters,  # Parameter types
                "required": required,  # List of required parameters
            },
        },
    }
Sebagai contoh, pertimbangkan fungsi translate_text dari Quick Start:
translation_tool = function_to_schema(translate_text)
print(json.dumps(translation_tool, indent=4, ensure_ascii=False))
Fungsi translate_text secara otomatis dikonversi menjadi:
{
    "type": "function",
    "function": {
        "name": "translate_text",
        "description": "Translates text into the specified target language.\n    This is a simple demonstration that uses a predefined translation.\n\n    Parameters:\n        text (str): The text to translate.\n        target_language (str): The target language code (for example, 'zh', 'es', or 'ja').\n\n    Returns:\n        str: The translated text or an error message.",
        "parameters": {
            "type": "object",
            "properties": {
                "text": {
                    "type": "string"
                },
                "target_language": {
                    "type": "string"
                }
            },
            "required": [
                "text",
                "target_language"
            ]
        }
    }
}
Sekarang, Anda dapat meneruskan deskripsi fungsi tersebut ke model.
assistant = Assistants.create(
    model='qwen-plus',
    name='Translation Agent',
    description='An agent that can translate text between different languages',
    instructions='You are a translation agent. When a user requests a translation, use the translate_text function to help them.',
    tools=[translation_tool]
)

Use streaming output

Ketika Anda menggunakan keluaran streaming, Anda harus memodifikasi logika kode pada Langkah 5: Tangani pemanggilan fungsi dan kembalikan hasilnya. Hal ini karena objek Runs sekarang mengembalikan aliran acara Assistant. Ketika Assistant memutuskan untuk memanggil fungsi, objek Runs mengembalikan event thread.run.requires_action dan parameter input data.required_action.submit_tool_outputs.tool_calls yang disediakan oleh Large Language Model (LLM). Anda harus mengirimkan output fungsi pada titik ini. Perhatikan bahwa Anda juga harus mengaktifkan keluaran streaming saat mengirimkan output fungsi dengan run = Runs.submit_tool_outputs.
# This code is for demonstration only. Integrate it into your project after you fully understand the logic.
# Assume that the assistant, thread, and message objects have been created.

# Define the tool function mapping
tools_map = {
    "translate_text": translate_text,  # Translation function
}

run = Runs.create(
        thread_id=thread.id,
        assistant_id=assistant.id,
        stream=True  # Enable streaming output
    )
while True:  # Add an outer loop
    for event, data in run:  # For more information about the event stream and event data, see the Assistant API streaming output documentation.
        if event == 'thread.run.requires_action':   # The Assistant has called a tool and is waiting for the function output.
            tool_outputs = []  # The method for submitting the output is similar to that in Step 5.
            for tool in data.required_action.submit_tool_outputs.tool_calls:
                name = tool.function.name
                args = json.loads(tool.function.arguments)
                output = tools_map[name](**args)
                tool_outputs.append({
                    "tool_call_id": tool.id,
                    "output": output,
                })
            run = Runs.submit_tool_outputs(  # Submit the function output
                thread_id=thread.id,
                run_id=data.id,
                tool_outputs=tool_outputs,
                stream=True  # Streaming output must also be enabled here.
            )
            break  # Break out of the current for loop. The next loop will poll the new Runs object.
    else:
        break  # If the first for loop finishes normally without triggering a function call, break out of the while loop.
Anda mungkin memperhatikan adanya loop while tambahan di luar loop for yang memproses aliran acara. Hal ini karena sistem menghasilkan objek Runs baru ketika Anda mengirimkan output fungsi. Loop while membantu Anda melacak aliran acara terbaru secara otomatis. Ini memungkinkan Assistant untuk terus menghasilkan respons setelah menerima hasil pemanggilan fungsi.