Zbuduj działającego agenta AI: praktyczny słownik

Agent AI to program, który bierze cel, określa sekwencję działań i wykonuje te działania za pomocą narzędzi aż do osiągnięcia celu lub rezygnacji. To różni się od chatbota, który tylko odpowiada na wiadomości. Agent planuje, wywołuje funkcje, sprawdza wyniki i dostosowuje się. Jeśli używałeś tylko ChatGPT przez przeglądarkę, zbudowanie pierwszego agenta to moment, gdy model przestaje być generatorem tekstu i zaczyna być komponentem w większym systemie.

Główna pętla

Każdy agent, bez względu na to, jak jest reklamowany, uruchamia jakąś wersję tej samej pętli: obserwuj, myśl, działaj, powtórz. W praktyce:

1. Agent otrzymuje zadanie ("znajdź najtańszy lot do Lizbony w przyszłym miesiącu i przygotuj streszczenie e-mailem").
2. Wywołuje LLM z zadaniem i opisem dostępnych narzędzi.
3. Model zwraca albo ostateczną odpowiedź, albo wywołanie narzędzia, takie jak search_flights(destination="Lisbon", month="2025-06").
4. Twój kod wykonuje tę funkcję, otrzymuje prawdziwy wynik i wprowadza go z powrotem do kontekstu modelu.
5. Model decyduje, co robić dalej: wywołać inne narzędzie, poprosić o wyjaśnienie lub zakończyć.

Ten wzorzec jest często nazywany pętlą ReAct (reasoning plus acting) i jest fundamentem frameworków takich jak agenty LangChain, agenty LlamaIndex i API function-calling OpenAI. Cały system można zaimplementować samemu w mniej niż 100 linii Python'a ze zwykłym API LLM i pętlą while — frameworki dodają wygodę, nie magię.

Narzędzia to to, co czyni to agentem

Model bez narzędzi może tylko rozmawiać. Daj mu funkcje, a będzie mógł działać. Narzędzia to zazwyczaj zwykłe funkcje Python'a opakowane schematem opisującym ich nazwę, parametry i cel, aby model wiedział, kiedy i jak je wywołać. Przykład:

def get_weather(city: str) -> str:
    """Return current weather for a given city."""
    resp = requests.get(f"https://api.weather.example/v1/{city}")
    return resp.json()["summary"]

W function-calling OpenAI przekazujesz schemat JSON obok tej funkcji, a model zwraca uporządkowane wywołanie takie jak {"name": "get_weather", "arguments": {"city": "Lisbon"}} zamiast tekstu swobodnego. Twój kod to analizuje, uruchamia rzeczywistą funkcję i zwraca wynik jako nową wiadomość w konwersacji. Powtarzaj, aż model będzie miał wystarczająco informacji, aby odpowiedzieć.

Pamięć i stan

Jedno wywołanie API nie ma pamięci poza oknem kontekstu. Agenty potrzebują wyraźnego stanu: bieżącej listy wiadomości (historia konwersacji) i często oddzielnego magazynu dla długoterminowych faktów. Do krótkich zadań wystarczy lista słowników Python'a reprezentujących konwersację. Dla agentów, które muszą pamiętać rzeczy między sesjami, sięgniesz po bazę wektorową (Chroma, Pinecone, Qdrant), aby przechowywać i pobierać odpowiednie poprzednie informacje za pośrednictwem embeddingów.

Nie przesadzaj z inżynierią na tym etapie. Zaskakująco wiele projektów "agentów" zawodzi nie dlatego, że LLM jest słaby, ale dlatego, że zarządzanie stanem jest niedbałe: zduplikowane wiadomości, nieskończony wzrost kontekstu lub utrata śladu, które wywołanie narzędzia odpowiada któremu wynikowi.

Minimalny działający przykład

Tak wygląda kształt schematycznego agenta używającego API OpenAI, bez frameworku:

messages = [{"role": "user", "content": "What's the weather in Lisbon?"}]

while True:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=[weather_tool_schema],
    )
    msg = response.choices[0].message
    if msg.tool_calls:
        for call in msg.tool_calls:
            result = get_weather(**json.loads(call.function.arguments))
            messages.append(msg)
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": result,
            })
    else:
        print(msg.content)
        break

To rzeczywisty, działający agent. Wszystko inne — strategie planowania, koordynacja wielu agentów, potoki pobierania — opiera się na tej pętli.

Gdzie się psuje

Agenty ulegają awarii w przewidywalny sposób: nieskończone pętle wywołań narzędzi, gdy model nie potrafi stwierdzić sukcesu, halucynowane argumenty funkcji i uciekające koszty z powodu ponownego wywoływania drogich narzędzi. Ochrona przed pętlami za pomocą twardego limitu iteracji (powiedzmy, 10 kroków) i logowanie każdego wywołania narzędzia podczas rozwoju. Zwaliduj argumenty przed wykonaniem czegokolwiek, co dotyka rzeczywistego systemu — agent, który może wysyłać e-maile lub uruchamiać polecenia powłoki, potrzebuje takiej samej sanacji wejścia, którą zastosowałbyś do kodu przeznaczonego dla użytkownika, ponieważ LLM jest w efekcie niezaufanym użytkownikiem generującym to wejście.

Dokąd iść dalej

Kiedy pętla działa, zaczynają się ciekawe problemy: wybór między projektami z jednym agentem a wieloma agentami, decydowanie, ile autonomii udzielić, i niezawodne testowanie agentów, gdy ich output nie jest deterministyczny. Ścieżki AI i Python w Korra Studio szczegółowo opisują retrieval-augmented generation, projektowanie promptów i wzorce tool-calling, jeśli chcesz dalej budować.