AI Engineering Academy · Pelajaran

Mendefinisikan Alat untuk Agent Anda

Buat alat khusus dengan dekorator @tool, tulis deskripsi yang jelas agar LLM dapat menentukan kapan setiap alat perlu dipanggil, dan tambahkan validasi masukan dengan Pydantic.

Pelajaran 2 dari 413 langkah

Mendefinisikan Alat untuk Agent Anda adalah pelajaran AI Engineering Academy gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar AI Engineering Academy, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus AI Engineering Academy mencakup 4 pelajaran total.

Alat Memberi Agen Kemampuan Super

Agen tanpa alat hanya dapat menalar tentang hal yang sudah diketahuinya—agen tersebut tidak dapat mencari di web, mengueri basis data, atau mengirim email. Alat adalah fungsi Python yang memperluas kemampuan agen dengan memungkinkannya melakukan tindakan di dunia nyata dan mengambil informasi terbaru. Mendefinisikan alat dengan jelas merupakan salah satu langkah terpenting dalam membangun agen yang andal.

Dekorator @tool di LangChain

Dekorator @tool milik LangChain mengubah fungsi Python apa pun menjadi alat yang dapat dipanggil agen. Dokstring fungsi menjadi deskripsi alat yang digunakan LLM untuk menentukan kapan alat tersebut harus dipanggil. Deskripsi yang jelas dan spesifik secara signifikan meningkatkan ketepatan pemilihan alat oleh agen.

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    '''Get the current weather conditions for a given city.
    Use this tool when the user asks about weather in a specific location.
    Input should be just the city name, e.g. 'London' or 'New York'.
    '''
    # Real implementation would call a weather API
    return f'The weather in {city} is 18 degrees Celsius and partly cloudy.'

print(get_weather.name)         # 'get_weather'
print(get_weather.description)  # The docstring above

Anotasi Tipe dan Pembuatan Skema

LangChain secara otomatis membuat Skema JSON untuk setiap alat berdasarkan anotasi tipe Python-nya. Agen menerima skema ini dalam perintah sistem sehingga mengetahui argumen yang diperlukan, tipenya, dan batasannya. Selalu beri anotasi tipe yang tepat pada fungsi alat Anda.

from langchain_core.tools import tool

@tool
def calculate_compound_interest(
    principal: float,
    annual_rate: float,
    years: int
) -> float:
    '''Calculate compound interest earned over a number of years.
    Args:
        principal: Initial investment amount in dollars.
        annual_rate: Annual interest rate as a decimal (e.g. 0.05 for 5%).
        years: Number of years to compound.
    Returns:
        Final amount after compounding.
    '''
    return principal * (1 + annual_rate) ** years

# Inspect the auto-generated schema
print(calculate_compound_interest.args_schema.schema())

Validasi Input dengan Pydantic

Untuk alat dengan input yang kompleks, definisikan model Pydantic sebagai args_schema. Dengan demikian, Anda memperoleh validasi otomatis, koersi tipe, dan dokumentasi deskriptif tingkat bidang yang dilihat LLM saat menentukan cara memanggil alat.

from langchain_core.tools import tool
from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description='The search query to look up.')
    num_results: int = Field(default=5, ge=1, le=20, description='Number of results to return (1-20).')

@tool(args_schema=SearchInput)
def web_search(query: str, num_results: int = 5) -> str:
    '''Search the web for current information on any topic.
    Use this for facts that may have changed after the model training cutoff.
    '''
    return f'Searching for "{query}", returning {num_results} results...'

Menulis Deskripsi Alat yang Efektif

Deskripsi alat adalah bagian terpenting dari definisi alat Anda—LLM membacanya untuk menentukan kapan dan bagaimana alat tersebut dipanggil. Deskripsi yang baik menjawab: Apa yang dilakukan alat ini? Kapan alat ini harus digunakan? Seperti apa inputnya? Seperti apa outputnya?

Buruk: 'Alat pencarian.'
Baik: 'Cari web untuk berita, fakta, atau data terkini. Gunakan saat pengguna menanyakan peristiwa terbaru atau fakta yang tidak ada dalam data pelatihan. Input: kueri pencarian yang ringkas.'

Tipe Nilai Kembalian Alat

Alat dapat mengembalikan string, kamus, atau objek Pydantic terstruktur. Namun, pada akhirnya agen memerlukan hasil dalam bentuk teks untuk dimasukkan ke percakapan. Jika Anda mengembalikan kamus, LangChain akan membuat serialisasinya menjadi string. Untuk data bertingkat yang kompleks, formatlah sebagai ringkasan yang mudah dibaca, bukan JSON mentah, agar model lebih mudah menalar.

from langchain_core.tools import tool
import json

@tool
def get_stock_price(ticker: str) -> str:
    '''Look up the current stock price for a given ticker symbol.
    Input should be the stock ticker symbol in uppercase, e.g. AAPL or MSFT.
    '''
    # Stub — real implementation calls a financial API
    data = {'ticker': ticker, 'price': 182.50, 'currency': 'USD', 'change': '+1.2%'}
    return f'{ticker}: ${data["price"]} ({data["change"]})'

Menangani Kesalahan Alat dengan Baik

Alat dapat gagal. API dapat tidak tersedia, batas waktu jaringan dapat terjadi, dan pengguna dapat memberikan input yang tidak valid. Alih-alih membiarkan pengecualian menghentikan putaran agen, bungkus logika alat dalam try/except dan kembalikan string kesalahan yang deskriptif. Agen kemudian dapat menalar tentang kegagalan tersebut dan menentukan apakah perlu mencoba lagi atau menggunakan pendekatan lain.

from langchain_core.tools import tool
import requests

@tool
def fetch_url(url: str) -> str:
    '''Fetch the text content of a web page given its URL.
    Use for accessing specific documents or web pages the user references.
    '''
    try:
        resp = requests.get(url, timeout=10)
        resp.raise_for_status()
        return resp.text[:2000]  # Return first 2000 chars
    except requests.Timeout:
        return 'Error: Request timed out after 10 seconds.'
    except requests.HTTPError as e:
        return f'Error: HTTP {e.response.status_code}'
    except Exception as e:
        return f'Error fetching URL: {str(e)}'

Alat Asinkron

Saat agen Anda menjalankan banyak pemanggilan alat atau alat Anda melakukan permintaan jaringan yang terikat I/O, definisikan fungsi alat asinkron agar tidak memblokir putaran peristiwa. Pelaksana agen LangChain mendukung alat asinkron secara bawaan—cukup gunakan async def dalam fungsi alat Anda.

from langchain_core.tools import tool
import httpx

@tool
async def async_fetch(url: str) -> str:
    '''Asynchronously fetch content from a URL.
    Preferred over fetch_url when making multiple concurrent requests.
    '''
    async with httpx.AsyncClient(timeout=10) as client:
        try:
            resp = await client.get(url)
            resp.raise_for_status()
            return resp.text[:2000]
        except Exception as e:
            return f'Error: {str(e)}'

Mengatur Alat ke dalam Toolkit

Saat Anda memiliki banyak alat yang saling berkaitan, kelompokkan alat tersebut ke dalam toolkit—sebuah kelas yang mengembalikan daftar alat. Toolkit LangChain mengikuti pola umum: toolkit menerima konfigurasi seperti kunci API dalam konstruktornya dan menyediakan metode get_tools(). Hal ini membuat pengelolaan alat menjadi rapi dan dapat digunakan kembali di berbagai agen.

from langchain_core.tools import BaseTool
from typing import List

class WeatherToolkit:
    def __init__(self, api_key: str):
        self.api_key = api_key

    def get_tools(self) -> List[BaseTool]:
        return [
            get_weather,          # defined earlier with @tool
            get_weather_forecast,  # another tool
            get_weather_alert      # another tool
        ]

# Usage
toolkit = WeatherToolkit(api_key='your_weather_api_key')
tools = toolkit.get_tools()
print(f'Loaded {len(tools)} weather tools')

Membatasi Akses Alat berdasarkan Peran Pengguna

Tidak semua pengguna boleh mengakses setiap alat. Pengguna dengan akses hanya-baca tidak boleh memicu alat send_email atau delete_record. Terapkan akses alat berbasis peran dengan memilih alat mana yang diteruskan kepada agen berdasarkan izin pengguna yang telah diautentikasi.

def get_tools_for_user(user_role: str) -> list:
    read_tools = [web_search, get_weather, calculate_compound_interest]
    write_tools = [send_email, create_calendar_event, update_record]

    if user_role == 'admin':
        return read_tools + write_tools
    elif user_role == 'member':
        return read_tools
    else:
        return [web_search]  # Guest: only public search

Praktik Terbaik Dokumentasi Alat

Alat yang terdokumentasi dengan baik secara signifikan mengurangi kesalahan agen. Ikuti praktik terbaik berikut: gunakan nama yang diawali kata kerja yang jelas (search_web, bukan websearch), jelaskan format input yang diharapkan secara eksplisit, sebutkan kapan alat TIDAK boleh digunakan untuk menghindari positif palsu, dan jelaskan seperti apa bentuk output agar model dapat menguraikannya dengan benar.

Pemeriksaan Singkat

Uji pemahaman Anda tentang pendefinisian alat untuk agen LangChain.

Jawab di pelajaran interaktif

Ringkasan Pelajaran

Dalam pelajaran ini Anda mempelajari bahwa: anotasi @tool mengubah fungsi Python menjadi alat yang dapat dipanggil agen dengan menggunakan docstring-nya sebagai deskripsi, skema Pydantic menambahkan input bertipe yang tervalidasi, dan alat harus menangani kesalahan dengan baik dengan mengembalikan string kesalahan yang deskriptif. Selanjutnya, kita akan merakit agen ReAct lengkap dengan LangChain dan melacak langkah-langkah penalarannya.

Gratis untuk memulai

Belajar Python dengan tutor AI — gratis

Tulis dan jalankan kode asli di browser kamu, dapatkan bantuan instan dari tutor AI 24/7, dan lanjutkan di mana kamu tinggalkan di web atau aplikasi.

Kursus: 30
Pelajaran: 120

Mulai belajar gratis Lihat kursus lengkapnya

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Mendefinisikan Alat untuk Agent Anda” gratis?

Ya — teks lengkap “Mendefinisikan Alat untuk Agent Anda” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus AI Engineering Academy, upgrade ke CoddyKit PRO. Kursus AI Engineering Academy mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Mendefinisikan Alat untuk Agent Anda”?

Buat alat khusus dengan dekorator @tool, tulis deskripsi yang jelas agar LLM dapat menentukan kapan setiap alat perlu dipanggil, dan tambahkan validasi masukan dengan Pydantic. Kamu berlatih AI Engineering Academy dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai AI Engineering Academy?

Tidak diperlukan pengalaman sebelumnya. AI Engineering Academy di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Mendefinisikan Alat untuk Agent Anda” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran AI Engineering Academy ini?

Ya. Setiap pelajaran AI Engineering Academy menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

Kerangka ReAct: Berpikir, Bertindak, Mengamati
Mendefinisikan Alat untuk Agent Anda
Membangun Agent ReAct dengan LangChain
Menangani Kegagalan dan Perulangan Agen

← Kembali ke AI Engineering Academy