ai-agents-for-beginners

Cara Mendesain Agen AI yang Baik

(Klik gambar di atas untuk melihat video pelajaran ini)

Pola Desain Penggunaan Alat

Alat sangat menarik karena memungkinkan agen AI memiliki rentang kemampuan yang lebih luas. Alih-alih agen hanya memiliki sekumpulan aksi terbatas yang bisa dilakukan, dengan menambahkan alat, agen sekarang dapat melakukan berbagai tindakan. Dalam bab ini, kita akan melihat Pola Desain Penggunaan Alat, yang menjelaskan bagaimana agen AI dapat menggunakan alat tertentu untuk mencapai tujuan mereka.

Pendahuluan

Dalam pelajaran ini, kita akan mencari jawaban atas pertanyaan-pertanyaan berikut:

Tujuan Pembelajaran

Setelah menyelesaikan pelajaran ini, Anda akan dapat:

Apa itu Pola Desain Penggunaan Alat?

Pola Desain Penggunaan Alat berfokus pada memberikan kemampuan kepada LLM untuk berinteraksi dengan alat eksternal guna mencapai tujuan tertentu. Alat adalah kode yang dapat dijalankan oleh agen untuk melakukan tindakan. Sebuah alat dapat berupa fungsi sederhana seperti kalkulator, atau panggilan API ke layanan pihak ketiga seperti pencarian harga saham atau prakiraan cuaca. Dalam konteks agen AI, alat dirancang untuk dijalankan oleh agen sebagai respons terhadap pemanggilan fungsi yang dihasilkan model.

Dalam kasus penggunaan apa pola ini dapat diterapkan?

Agen AI dapat memanfaatkan alat untuk menyelesaikan tugas kompleks, mengambil informasi, atau membuat keputusan. Pola desain penggunaan alat sering digunakan dalam skenario yang memerlukan interaksi dinamis dengan sistem eksternal, seperti basis data, layanan web, atau interpreter kode. Kemampuan ini berguna untuk berbagai kasus penggunaan termasuk:

Apa saja elemen/komponen yang diperlukan untuk mengimplementasikan pola desain penggunaan alat?

Komponen-komponen ini memungkinkan agen AI melakukan berbagai tugas. Mari kita lihat elemen kunci yang diperlukan untuk mengimplementasikan Pola Desain Penggunaan Alat:

Selanjutnya, mari kita lihat lebih detail tentang Pemanggilan Fungsi/Alat.

Pemanggilan Fungsi/Alat

Pemanggilan fungsi adalah cara utama kita memungkinkan Large Language Models (LLM) berinteraksi dengan alat. Anda sering akan melihat istilah ‘Fungsi’ dan ‘Alat’ digunakan bergantian karena ‘fungsi’ (blok kode yang dapat digunakan ulang) adalah ‘alat’ yang digunakan agen untuk menjalankan tugas. Untuk memanggil kode fungsi, LLM harus membandingkan permintaan pengguna dengan deskripsi fungsi. Untuk ini, skema yang berisi deskripsi dari semua fungsi yang tersedia dikirim ke LLM. LLM kemudian memilih fungsi yang paling sesuai untuk tugas tersebut dan mengembalikan nama beserta argumennya. Fungsi yang dipilih dipanggil, responsnya dikirim kembali ke LLM, yang menggunakan informasi tersebut untuk merespons permintaan pengguna.

Untuk pengembang mengimplementasikan pemanggilan fungsi untuk agen, Anda akan memerlukan:

  1. Model LLM yang mendukung pemanggilan fungsi
  2. Skema yang berisi deskripsi fungsi
  3. Kode untuk setiap fungsi yang dideskripsikan

Mari gunakan contoh mendapatkan waktu saat ini di sebuah kota untuk ilustrasi:

  1. Inisialisasi LLM yang mendukung pemanggilan fungsi:

    Tidak semua model mendukung pemanggilan fungsi, jadi penting untuk memastikan bahwa LLM yang Anda gunakan mendukungnya. Azure OpenAI mendukung pemanggilan fungsi. Kita dapat memulai dengan membuat klien OpenAI terhadap API Responses Azure OpenAI (endpoint stabil /openai/v1/ — tidak perlu api_version).

     # Inisialisasi klien OpenAI untuk Azure OpenAI (API Respon, endpoint v1)
 client = OpenAI(
     base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
     api_key=os.environ["AZURE_OPENAI_API_KEY"],
 )
 deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

  2. Buat Skema Fungsi:

    Selanjutnya kita akan mendefinisikan skema JSON yang berisi nama fungsi, deskripsi fungsi, dan nama serta deskripsi parameter fungsi. Kemudian skema ini akan kita kirim ke klien yang telah dibuat sebelumnya, bersama dengan permintaan pengguna untuk mengetahui waktu di San Francisco. Yang penting dicatat adalah bahwa pemanggilan alat adalah yang dikembalikan, bukan jawaban akhir dari pertanyaan. Seperti disebutkan sebelumnya, LLM mengembalikan nama fungsi yang dipilih untuk tugas tersebut, beserta argumen yang akan diteruskan ke fungsi.

     # Deskripsi fungsi untuk model membaca (format alat datar API Respons)
 tools = [
     {
         "type": "function",
         "name": "get_current_time",
         "description": "Get the current time in a given location",
         "parameters": {
             "type": "object",
             "properties": {
                 "location": {
                     "type": "string",
                     "description": "The city name, e.g. San Francisco",
                 },
             },
             "required": ["location"],
         },
     }
 ]

      
 # Pesan pengguna awal
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}]

 # Panggilan API pertama: Minta model untuk menggunakan fungsi
 response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     tool_choice="auto",
     store=False,
 )

 # API Respon mengembalikan panggilan alat sebagai item function_call dalam response.output.
 # Tambahkan mereka ke percakapan agar model memiliki konteks penuh pada giliran berikutnya.
 messages += response.output

 print("Model's response:")
 print(response.output)
  

     Model's response:
 [ResponseFunctionToolCall(arguments='{"location":"San Francisco"}', call_id='call_pOsKdUlqvdyttYB67MOj434b', name='get_current_time', type='function_call')]

  3. Kode fungsi yang diperlukan untuk menjalankan tugas:

    Setelah LLM memilih fungsi mana yang harus dijalankan, kode yang menjalankan tugas harus diimplementasikan dan dijalankan. Kita dapat mengimplementasikan kode untuk mendapatkan waktu saat ini dalam Python. Kita juga perlu menulis kode untuk mengekstrak nama dan argumen dari response_message untuk mendapatkan hasil akhir.

       def get_current_time(location):
     """Get the current time for a given location"""
     print(f"get_current_time called with location: {location}")  
     location_lower = location.lower()
        
     for key, timezone in TIMEZONE_DATA.items():
         if key in location_lower:
             print(f"Timezone found for {key}")  
             current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
             return json.dumps({
                 "location": location,
                 "current_time": current_time
             })
      
     print(f"No timezone data found for {location_lower}")  
     return json.dumps({"location": location, "current_time": "unknown"})

     # Menangani pemanggilan fungsi
 tool_calls = [item for item in response.output if item.type == "function_call"]
 if tool_calls:
     for tool_call in tool_calls:
         if tool_call.name == "get_current_time":

             function_args = json.loads(tool_call.arguments)

             time_response = get_current_time(
                 location=function_args.get("location")
             )

             # Mengembalikan hasil alat sebagai item function_call_output
             messages.append({
                 "type": "function_call_output",
                 "call_id": tool_call.call_id,
                 "output": time_response,
             })
 else:
     print("No tool calls were made by the model.")

 # Panggilan API kedua: Dapatkan respons akhir dari model
 final_response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     store=False,
 )

 return final_response.output_text

       get_current_time called with location: San Francisco
   Timezone found for san francisco
   The current time in San Francisco is 09:24 AM.

Pemanggilan fungsi adalah inti dari sebagian besar, jika tidak semua, desain penggunaan alat agen, tetapi mengimplementasikannya dari awal kadang bisa menantang. Seperti yang kita pelajari dalam Pelajaran 2, framework agentic menyediakan blok bangunan yang sudah dibuat sebelumnya untuk mengimplementasikan penggunaan alat.

Contoh Penggunaan Alat dengan Framework Agentic

Berikut adalah beberapa contoh bagaimana Anda dapat mengimplementasikan Pola Desain Penggunaan Alat menggunakan berbagai framework agentic:

Microsoft Agent Framework

Microsoft Agent Framework adalah framework AI open-source untuk membangun agen AI. Framework ini menyederhanakan proses penggunaan pemanggilan fungsi dengan memungkinkan Anda mendefinisikan alat sebagai fungsi Python dengan dekorator @tool. Framework menangani komunikasi bolak-balik antara model dan kode Anda. Framework ini juga menyediakan akses ke alat yang sudah dibuat seperti Pencarian File dan Interpreter Kode melalui FoundryChatClient.

Diagram berikut menggambarkan proses pemanggilan fungsi dengan Microsoft Agent Framework:

function calling

Dalam Microsoft Agent Framework, alat didefinisikan sebagai fungsi yang didekorasi. Kita dapat mengubah fungsi get_current_time yang kita lihat sebelumnya menjadi alat dengan menggunakan dekorator @tool. Framework akan otomatis menyerialkan fungsi beserta parameternya, menciptakan skema untuk dikirim ke LLM.

import os
from agent_framework import tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

@tool(approval_mode="never_require")
def get_current_time(location: str) -> str:
    """Get the current time for a given location"""
    ...

# Buat klien
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

# Buat agen dan jalankan dengan alat tersebut
agent = provider.as_agent(name="TimeAgent", instructions="Use available tools to answer questions.", tools=get_current_time)
response = await agent.run("What time is it?")

Microsoft Foundry Agent Service

Microsoft Foundry Agent Service adalah framework agentic yang lebih baru yang dirancang untuk memberdayakan pengembang membangun, menerapkan, dan menskalakan agen AI berkualitas tinggi dan dapat diperluas dengan aman tanpa perlu mengelola sumber daya komputasi dan penyimpanan yang mendasari. Ini sangat berguna untuk aplikasi enterprise karena merupakan layanan yang dikelola penuh dengan keamanan tingkat perusahaan.

Dibandingkan dengan pengembangan langsung memakai API LLM, Microsoft Foundry Agent Service menawarkan beberapa keunggulan, termasuk:

Alat yang tersedia di Microsoft Foundry Agent Service dapat dibagi menjadi dua kategori:

  1. Alat Pengetahuan:
  2. Alat Aksi:

Layanan Agent memungkinkan kita menggunakan alat-alat ini bersama sebagai toolset. Layanan ini juga menggunakan threads yang menyimpan riwayat pesan dari percakapan tertentu.

Bayangkan Anda adalah agen penjualan di perusahaan bernama Contoso. Anda ingin mengembangkan agen percakapan yang dapat menjawab pertanyaan tentang data penjualan Anda.

Gambar berikut menggambarkan bagaimana Anda dapat menggunakan Microsoft Foundry Agent Service untuk menganalisis data penjualan Anda:

Agentic Service In Action

Untuk menggunakan alat-alat ini dengan layanan, kita dapat membuat klien dan mendefinisikan alat atau toolset. Untuk mengimplementasikannya secara praktis, kita dapat menggunakan kode Python berikut. LLM akan dapat melihat toolset dan memutuskan apakah akan menggunakan fungsi yang dibuat pengguna, fetch_sales_data_using_sqlite_query, atau Interpreter Kode yang sudah dibuat berdasarkan permintaan pengguna.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from fetch_sales_data_functions import fetch_sales_data_using_sqlite_query # fungsi fetch_sales_data_using_sqlite_query yang dapat ditemukan dalam file fetch_sales_data_functions.py.
from azure.ai.projects.models import ToolSet, FunctionTool, CodeInterpreterTool

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

# Inisialisasi toolset
toolset = ToolSet()

# Inisialisasi agen pemanggil fungsi dengan fungsi fetch_sales_data_using_sqlite_query dan menambahkannya ke toolset
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Inisialisasi alat Interpreter Kode dan menambahkannya ke toolset.
code_interpreter = CodeInterpreterTool()toolset.add(code_interpreter)

agent = project_client.agents.create_agent(
    model="gpt-5-mini", name="my-agent", instructions="You are helpful agent", 
    toolset=toolset
)

Apa saja pertimbangan khusus saat menggunakan Pola Desain Penggunaan Alat untuk membangun agen AI yang dapat dipercaya?

Kekhawatiran umum dengan SQL yang dihasilkan secara dinamis oleh LLM adalah keamanan, terutama risiko injeksi SQL atau tindakan berbahaya, seperti menghapus atau mengubah database. Meskipun kekhawatiran ini valid, hal ini dapat diatasi secara efektif dengan konfigurasi izin akses database yang tepat. Untuk sebagian besar database, ini melibatkan pengaturan database sebagai read-only. Untuk layanan database seperti PostgreSQL atau Azure SQL, aplikasi harus diberikan peran read-only (SELECT).

Menjalankan aplikasi di lingkungan yang aman semakin meningkatkan perlindungan. Dalam skenario enterprise, data biasanya diekstrak dan diubah dari sistem operasional ke database read-only atau data warehouse dengan skema yang ramah pengguna. Pendekatan ini memastikan data aman, dioptimalkan untuk performa dan aksesibilitas, serta aplikasi memiliki akses terbatas hanya baca.

Contoh Kode

Punya Pertanyaan Lebih Lanjut tentang Pola Desain Penggunaan Alat?

Bergabunglah dengan Microsoft Foundry Discord untuk bertemu dengan pelajar lain, mengikuti jam kantor, dan mendapatkan pertanyaan tentang Agen AI Anda dijawab.

Sumber Daya Tambahan

Pengujian Singkat Agen Ini (Opsional)

Setelah Anda belajar cara menerapkan agen dalam Pelajaran 16, Anda dapat melakukan pengujian singkat untuk TravelToolAgent pelajaran ini (apakah masih memanggil alatnya dan menjawab?) dengan tests/lesson-04-smoke-tests.json. Lihat tests/README.md untuk cara menjalankannya.

Pelajaran Sebelumnya

Memahami Pola Desain Agen

Pelajaran Selanjutnya

Agentic RAG

Penafian: Dokumen ini telah diterjemahkan menggunakan layanan terjemahan AI Co-op Translator. Meskipun kami berupaya untuk mencapai akurasi, harap diketahui bahwa terjemahan otomatis mungkin mengandung kesalahan atau ketidakakuratan. Dokumen asli dalam bahasa aslinya harus dianggap sebagai sumber yang sah. Untuk informasi penting, disarankan menggunakan terjemahan profesional oleh manusia. Kami tidak bertanggung jawab atas kesalahpahaman atau penafsiran yang keliru yang timbul dari penggunaan terjemahan ini.

This site is open source. Improve this page.