Agenci AI dla przyszłych inżynierów: pamięć, narzędzia i pętle sterujące
Praktyczna mapa elementów budulcowych agenta — planowanie, narzędzia, pamięć i ocena — bez przechwalającej się terminologii zastępującej koncepcję projektowania.
To przewodnik pokazuje, jak odbudować funkcjonalną ścieżkę dla tematu: Wszystko, co przyszli inżynierowie AI muszą wiedzieć o agentach AI. Skupiamy się na kontraktach, sprawdzaniach oraz kodzie, który można umieścić w repozytorium bez konieczności domyślania się intencji. Aby uzyskać ogólny obraz, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Lepiej używać małych, testowalnych jednostek niż rozbudowanych skryptów. Gdy dany krok zawiedzie, powód awarii powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany proces.
Jak agenci podejmują działania
Aby określić, w jaki sposób agenci podejmują działania, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć przypadkowe, częściowe ukończenie zadań. Ściśle określ schematy narzędzi. Zbyt szerokie pola tekstowe sprzyjają wstrzykiwaniu złośliwego kodu i sprawiają, że audyty są kosztowne.
import requests
def search_web(query: str) -> list[dict]:
response = requests.get(
"https://serpapi.com/search",
params={"q": query, "api_key": "YOUR_API_KEY", "num": 5},
)
results = response.json()["organic_results"]
return [
{"title": r["title"], "url": r["link"], "snippet": r["snippet"]}
for r in results
]
results = search_web("best sourdough recipe")
for r in results:
print(r["title"], "-", r["url"])
import anthropic
client = anthropic.Anthropic()
# The menu of tools the model can choose from
tools = [
{
"name": "web_search",
"description": "Search the web for current information.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "The search query"}
},
"required": ["query"],
},
}
]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in Seattle right now?"}],
)
print(response.content)
# [ToolUseBlock(name='web_search', input={'query': 'Seattle weather today'})]
# 1. Parse the LLM response to find the tools it wants to run
tool_calls = [block for block in response.content if block.type == "tool_use"]
# 2. Run the functions directly, OUTSIDE of the LLM
# (this is our search_web function from earlier -- plain Python,
# the model never sees this code)
tool_results = []
for call in tool_calls:
if call.name == "web_search":
output = search_web(call.input["query"])
tool_results.append(
{
"type": "tool_result",
"tool_use_id": call.id,
"content": str(output),
}
)
# 3. Hand the results back -- from the model's perspective,
# the answer just shows up in the chat
final = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "What's the weather in Seattle right now?"},
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results},
],
)
print(final.content[0].text)
# "It's 62 and cloudy in Seattle."
Zadania wieloetapowe
Dla zadań wieloetapowych należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany etap oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany etap na podstawie znanej punktacji kontrolnej, bez konieczności zgadywania ukrytego stanu. Należy rejestrować czasy wykonywania i koszty obok wyników funkcjonalnych. Wczesna widoczność zapobiega nieoczekiwanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. Schematy narzędzi muszą być ściśle określone. Szersze pola tekstowe umożliwiają wstrzykiwanie danych i sprawiają, że audyty są kosztowne.
# The ReAct loop
while True:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
# If the model didn't ask for any tools, it's done -- that's its final answer
if response.stop_reason != "tool_use":
break
# Otherwise: run the tools, append the results, and go around again
tool_results = []
for block in response.content:
if block.type == "tool_use":
output = run_tool(block.name, block.input)
tool_results.append(
{"type": "tool_result", "tool_use_id": block.id, "content": str(output)}
)
messages.append({"role": "user", "content": tool_results})
print(response.content[0].text)
# "Booked it into your calendar -- cheapest flight was the 9:15am Alaska
# departure Friday at $138. Event added from 9:15am to 11:30am."
Niezawodne wyniki
Aby uzyskać niezawodne wyniki, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Konfigurację należy przechowywać poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury. Schematy narzędzi należy ściśle określić. Szersze argumenty tekstowe sprzyjają iniekcjom i utrudniają audyt. Aby uzyskać niezawodne wyniki, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę przepływu.
system_prompt = """You have access to a web_search tool.
To use it, respond with JSON in this format:
{"name": "web_search", "input": {"query": "..."}}
CRITICAL: You MUST respond with ONLY valid JSON. NO other text.
NO markdown. NO code fences. NO explanations before or after.
Your ENTIRE response must be parseable by json.loads().
DO NOT FORGET THE COMMAS. CHECK YOUR BRACKETS.
If you output anything that is not valid JSON, the system WILL CRASH.
THIS IS EXTREMELY IMPORTANT. VALID JSON ONLY.
"""
Jakościowe dane wejściowe
Dla danych wejściowych wysokiej jakości należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany etap oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten etap od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Ustaw punkt kontrolny po kosztownych wywołaniach modelu, aby ponowna próba nie generowała dodatkowych opłat za tę samą pracę.
tools = [
{
"name": "web_search",
"description": "Search the web for current information.",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
{
"name": "add_calendar_event",
"description": "Add an event to the user's calendar.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start_time": {"type": "string"},
},
"required": ["title", "start_time"],
},
},
# ...plus read_email, send_email, get_flights, book_flight,
# read_file, write_file, run_code, and 20 more
]
Zaufanie do swojego agenta
Aby zaufać swojemu agentowi, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Zapisuj czas trwania i koszty obok wyników funkcjonalnych. Wczesna widoczność zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk. Ustal punkt kontrolny po drogich wywołaniach modelu, aby ponowna próba nie generowała dodatkowych opłat za tę samą pracę.
Lista kontrolna operacyjna
Dla listy kontrolnej operacyjnej należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, mechanizmy ludzkiej kontroli oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później.
Punkt kontrolny po drogich wywołaniach modeli, aby ponowna próba nie generowała dodatkowych opłat za tę samą pracę.
Dodaj test sprawdzający, który symuluje kluczową ścieżkę w procesie CI przy użyciu fixitów, jeśli budżet na to pozwala.
Niechaj przeważać będą małe, testowalne jednostki nad rozbudowanymi skryptami. Gdy jakaś etap zawiedzie, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji.
Punkt kontrolny po drogich wywołaniach modeli, aby ponowna próba nie generowała dodatkowych opłat za tę samą pracę.
Zanim wdrożysz nowy zestaw narzędzi, zamroź wersje, utwórz dokumentację stanu idealnego dla kluczowej ścieżki i potwierdź kroki odwracające zmiany. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji dostępności oraz wyraźnego odpowiedzialnego za rotację haseł. Wolisz nudną niezawodność od pomysłowych, jednorazowych demonstracji.
Dla uwagi dotyczącej wzmocnienia bezpieczeństwa nr 0 należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zapisuj czas trwania i koszty obok wyników funkcjonalnych. Wczesna widoczność zapobiega niespodziewanym rachunkom, gdy proces przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.
Schematy narzędzi należy ściśle ograniczyć. Szerokie pola tekstowe umożliwiają iniekcje i sprawiają, że audyty są kosztowne.
Dla uwagi dotyczącej wzmocnienia bezpieczeństwa nr 1 należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Dokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później.
Punkt kontrolny po drogich wywołaniach modeli, aby ponowna próba nie generowała dodatkowych opłat za tę samą pracę.
Zgodnie z uwagą 2 dotyczącą wzmocnienia bezpieczeństwa, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania.
Rozdziel planowanie od wykonywania zadań za pomocą narzędzi. Planista proponuje rozwiązania; wykonawca je wdraża; sprawdzający porównuje wyniki z założonym celem.
Zgodnie z uwagą 3 dotyczącą wzmocnienia bezpieczeństwa, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zachowaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.
Schematy narzędzi muszą być ściśle określone. Szerokie argumenty tekstowe sprzyjają iniekcjom i utrudniają audyty.
Aby wdrożyć zalecenie nr 4 dotyczące wzmacniania bezpieczeństwa, zdefiniuj dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Niech preferowane będą małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy dany krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę przepływu.
Zrób punkt kontrolny po kosztownych wywołaniach modeli, aby ponowna próba nie generowała dodatkowych kosztów za tę samą pracę.
Dla uwagi dotyczącej wzmocnienia bezpieczeństwa nr 5 należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie wykonać ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zapisuj czas trwania i koszty obok wyników funkcjonalnych. Wczesna widoczność zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.
Rozdziel planowanie od wykonywania zadań za pomocą narzędzi. Planista proponuje; wykonawca wprowadza zmiany; sprawdzający porównuje wyniki z założonym celem.
Dla uwagi dotyczącej wzmocnienia bezpieczeństwa nr 6 należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie wykonać ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, mechanizmy kontroli ludzkiej oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później.
Schematy narzędzi muszą być ściśle skonstruowane. Szerokie pola tekstowe umożliwiają iniekcje i sprawiają, że audyty są kosztowne.
Zgodnie z zaleceniem 7 dotyczącym wzmocnienia bezpieczeństwa, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij pliki artefaktów, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań.
Ustaw punkt kontrolny po kosztownych wywołaniach modeli, aby ponowna próba nie generowała dodatkowych opłat za tę samą pracę.
Zgodnie z zaleceniem 8 dotyczącym wzmocnienia bezpieczeństwa, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zachowaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.
Rozdziel planowanie od wykonywania narzędzi. Planer proponuje rozwiązania; wykonawca je wdraża; sprawdzacz porównuje wyniki z założonym celem.
W celu wzmocnienia bezpieczeństwa zgodnie z zasadą nr 9, określ dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Niech preferowane będą małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę procesów.
Sztywno określ schematy narzędzi. Szerokie pola tekstowe umożliwiają iniekcje i sprawiają, że audyty stają się kosztowne.
Dla uwagi dotyczącej wzmocnienia bezpieczeństwa nr 10 należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zapisuj czas trwania i koszty obok wyników funkcjonalnych. Wczesna widoczność zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.
Ustal punkt kontrolny po kosztownych wywołaniach modelu, aby ponowna próba nie generowała dodatkowych opłat za tę samą pracę.
Dla uwagi dotyczącej wzmocnienia bezpieczeństwa nr 11 należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponowne, mechanizmy kontroli ludzkiej oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później.
Rozdziel planowanie od wykonywania narzędzia. Planista proponuje; wykonawca wprowadza zmiany; weryfikator sprawdza wyniki pod kątem celu.
W odniesieniu do uwagi 12 dotyczącej wzmocnienia bezpieczeństwa, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij powstałe artefakty, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania.
Sztywno ogranicz schematy narzędzi. Szerokie pola tekstowe umożliwiają iniekcje i sprawiają, że audyty są kosztowne.
W odniesieniu do uwagi 13 dotyczącej wzmocnienia bezpieczeństwa, należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zachowaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury.
Zrób punkt kontrolny po kosztownych wywołaniach modelu, aby ponowna próba nie powodowała ponownego naliczenia za tę samą pracę.
Zgodnie z zaleceniem 14 dotyczącym wzmocnienia bezpieczeństwa, zdefiniuj dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić dany krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Niech lepszą opcją będą małe, testowalne jednostki niż rozbudowane skrypty. Gdy dany krok zawiedzie, powód awarii powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę procesów.
Rozdziel planowanie od wykonywania zadań za pomocą narzędzi. Planista proponuje rozwiązania; wykonawca je wdraża; sprawdzający porównuje wyniki z założonym celem.
Dla uwagi nr 15 dotyczącej wzmocnienia bezpieczeństwa należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu.
Zapisuj czas trwania i koszty obok wyników funkcjonalnych. Wczesna widoczność zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do współdzielonych środowisk.
Schematy narzędzi należy ściśle określić. Szerokie pola tekstowe umożliwiają iniekcje i sprawiają, że audyty są kosztowne.