Definiowanie narzędzi dla agenta
Uczestnicy utworzą niestandardowe narzędzia za pomocą dekoratora @tool, napiszą jasne opisy używane przez LLM do decydowania, kiedy wywołać dane narzędzie, oraz dodadzą walidację danych wejściowych z Pydantic.
Definiowanie narzędzi dla agenta to bezpłatna lekcja AI Engineering Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Engineering Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Narzędzia nadają agentom supermoce
Agent bez narzędzi może jedynie rozumować na podstawie tego, co już wie — nie może przeszukiwać internetu, odpytywać bazy danych ani wysyłać wiadomości e-mail. Narzędzia to funkcje Python rozszerzające możliwości agenta, ponieważ pozwalają mu wykonywać działania w świecie rzeczywistym i pobierać aktualne informacje. Jasne definiowanie narzędzi jest jednym z najważniejszych etapów budowania niezawodnego agenta.
Dekorator @tool w LangChain
Dekorator @tool w LangChain przekształca dowolną funkcję Python w narzędzie, które może wywołać agent. Docstring funkcji staje się opisem narzędzia używanym przez LLM do podjęcia decyzji, kiedy je wywołać. Jasny i konkretny opis znacząco poprawia dokładność wyboru narzędzia przez agenta.
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 aboveAdnotacje typów i generowanie schematu
LangChain automatycznie generuje schemat JSON dla każdego narzędzia na podstawie adnotacji typów Python. Agent otrzymuje ten schemat w prompcie systemowym, dzięki czemu wie, jakie argumenty są wymagane, jakie mają typy i jakie obowiązują ograniczenia. Proszę zawsze opatrywać funkcje narzędzi precyzyjnymi adnotacjami typów.
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())Walidacja danych wejściowych za pomocą Pydantic
W przypadku narzędzi przyjmujących złożone dane wejściowe proszę zdefiniować model Pydantic jako args_schema. Zapewnia to automatyczną walidację, konwersję typów oraz opisową dokumentację na poziomie pól, którą LLM widzi podczas podejmowania decyzji o sposobie wywołania narzędzia.
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...'Pisanie skutecznych opisów narzędzi
Opis narzędzia jest najważniejszą częścią jego definicji — LLM czyta go, aby zdecydować, kiedy i jak wywołać narzędzie. Dobry opis odpowiada na pytania: Co robi to narzędzie? Kiedy należy go używać? Jak powinny wyglądać dane wejściowe? Jak będą wyglądać dane wyjściowe?
- Zły: „Narzędzie wyszukiwania”.
- Dobry: „Przeszukuje internet pod kątem aktualnych wiadomości, faktów lub danych. Należy użyć, gdy użytkownik pyta o najnowsze wydarzenia lub fakty, których nie ma w danych treningowych. Dane wejściowe: zwięzłe zapytanie wyszukiwania”.
Typy zwracane przez narzędzia
Narzędzia mogą zwracać ciągi tekstowe, słowniki lub ustrukturyzowane obiekty Pydantic. Agent ostatecznie potrzebuje jednak wyniku w postaci tekstu, aby dołączyć go do rozmowy. Jeśli zostanie zwrócony słownik, LangChain serializuje go do ciągu tekstowego. W przypadku złożonych, zagnieżdżonych danych proszę sformatować je jako czytelne podsumowanie zamiast surowego JSON, aby ułatwić modelowi rozumowanie.
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"]})'Elegancka obsługa błędów narzędzi
Narzędzia mogą zawodzić. Interfejsy API mogą przestać działać, mogą wystąpić przekroczenia limitu czasu sieci, a użytkownicy mogą podawać nieprawidłowe dane. Zamiast pozwalać, aby wyjątki przerywały pętlę agenta, proszę opakować logikę narzędzia w try/except i zwracać opisowy ciąg błędu. Agent może wtedy przeanalizować awarię i zdecydować, czy ponowić próbę, czy zastosować inne podejście.
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)}'Narzędzia asynchroniczne
Gdy agent wykonuje wiele wywołań narzędzi lub narzędzia wykonują żądania sieciowe zależne od operacji wejścia-wyjścia, proszę definiować asynchroniczne funkcje narzędzi, aby uniknąć blokowania pętli zdarzeń. Executor agentów LangChain natywnie obsługuje narzędzia asynchroniczne — wystarczy użyć async def w funkcji narzędzia.
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)}'Porządkowanie narzędzi w zestaw narzędzi
Jeśli mają Państwo wiele powiązanych narzędzi, proszę zgrupować je w toolkit — klasę zwracającą listę narzędzi. Zestawy narzędzi LangChain korzystają ze wspólnego wzorca: przyjmują w konstruktorze konfigurację, taką jak klucze API, i udostępniają metodę get_tools(). Ułatwia to przejrzyste zarządzanie narzędziami i ponowne wykorzystywanie ich przez różnych agentów.
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')Ograniczanie dostępu do narzędzi według roli użytkownika
Nie każdy użytkownik powinien mieć dostęp do każdego narzędzia. Użytkownik z uprawnieniami tylko do odczytu nie powinien uruchamiać narzędzia send_email ani delete_record. Należy zaimplementować dostęp do narzędzi oparty na rolach, wybierając narzędzia przekazywane agentowi na podstawie uprawnień uwierzytelnionego użytkownika.
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 searchNajlepsze praktyki dotyczące dokumentowania narzędzi
Dobrze udokumentowane narzędzia znacznie ograniczają liczbę błędów agenta. Należy stosować następujące dobre praktyki: używać jasnej nazwy zaczynającej się od czasownika (search_web, a nie websearch), wyraźnie opisywać oczekiwany format danych wejściowych, wskazywać kiedy NIE używać narzędzia, aby uniknąć fałszywych trafień, oraz opisywać wygląd danych wyjściowych, aby model mógł je poprawnie przetworzyć.
Szybkie sprawdzenie
Sprawdź swoją wiedzę na temat definiowania narzędzi dla agentów LangChain.
Podsumowanie lekcji
W tej lekcji nauczyłeś się, że: dekorator @tool przekształca funkcje języka Python w narzędzia, które agent może wywoływać, używając ich docstringów jako opisów, schematy Pydantic dodają typowane i walidowane dane wejściowe, a narzędzia powinny obsługiwać błędy w kontrolowany sposób, zwracając opisowe ciągi znaków z komunikatami o błędach. Następnie zbudujemy pełnego agenta ReAct za pomocą LangChain i prześledzimy jego kroki rozumowania.
Ucz się Python dzięki korepetycjom AI — za darmo
Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.
- Kursy
- 30
- Lekcje
- 120
Często zadawane pytania
Czy lekcja „Definiowanie narzędzi dla agenta” jest bezpłatna?
Tak — pełny tekst „Definiowanie narzędzi dla agenta” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Engineering Academy, przejdź na CoddyKit PRO. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Definiowanie narzędzi dla agenta”?
Uczestnicy utworzą niestandardowe narzędzia za pomocą dekoratora @tool, napiszą jasne opisy używane przez LLM do decydowania, kiedy wywołać dane narzędzie, oraz dodadzą walidację danych wejściowych z… Ćwiczysz AI Engineering Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć AI Engineering Academy?
Nie wymagamy żadnego doświadczenia. AI Engineering Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.
Ile czasu zajmuje lekcja „Definiowanie narzędzi dla agenta”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji AI Engineering Academy?
Tak. Każda lekcja AI Engineering Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Framework ReAct: myślenie, działanie, obserwacja
- Definiowanie narzędzi dla agenta
- Tworzenie agenta ReAct za pomocą LangChain
- Obsługa awarii i pętli agentów