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.
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.
Pertama, buat fungsi penerjemahan sederhana. Fungsi ini menggunakan tabel terjemahan yang telah ditentukan sebelumnya untuk tujuan demonstrasi.
Copy
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.
Sekarang, buat instans Assistant. Instans ini merupakan agen yang akan menggunakan tool terjemahan yang telah Anda definisikan.
Copy
# Create an Assistantassistant = 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.
Copy
# Create a new threadthread = Threads.create()# Add a user message to the threadMessages.create( thread_id=thread.id, role="user", content="Please translate 'Hello world' into Chinese.")# Run the Assistantrun = Runs.create(thread_id=thread.id, assistant_id=assistant.id)# Wait for the run to completerun = 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.
Copy
# Check if a function call is requiredif 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.
Setelah agen menyelesaikan pemrosesan, Anda dapat mengambil respons agen dari thread percakapan dan menampilkannya kepada pengguna.
Copy
# Get the Assistant's responsemessages = Messages.list(thread_id=thread.id)for message in messages.data: if message.role == "assistant": print(f"Assistant: {message.content[0].text.value}")
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.
Copy
import inspectdef 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:
Fungsi translate_text secara otomatis dikonversi menjadi:
Copy
{ "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.
Copy
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])
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.
Copy
# 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 mappingtools_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.