Цикълът на агента: план, действие, наблюдение

Код на:JavaC#PythonJavaScript

Накратко: AI агентът е цикъл: моделът казва план и иска действие, програмата го изпълнява и връща наблюдението, докато има отговор, лимит на стъпките или нужда от човек.

Проблем

Асистентът отговаря, но не върши работата

Клиентът пише: „Слушалките от поръчка 1187 са повредени. Искам да ги върна.“

Това не е въпрос с един отговор. Някой трябва да провери дали поръчката е доставена, да отвори заявка за връщане и да каже на клиента какво следва. Ако поръчката още не е доставена, пътят е друг. Ако клиентът иска обезщетение, пак е друг.

Цикълът от урока за инструментите отговаряше на въпрос: моделът иска данни, програмата ги дава, моделът отговаря. Тук трябва няколко действия едно след друго, а кое е следващото се разбира чак след предишното.

Можеш да го напишеш с if за всеки случай. Работи за случаите, които си предвидил. Клиентите пишат и такива, които не си.

Идеята

Агентът: план, действие, наблюдение

Агент е програма, в която моделът избира следващата стъпка към една цел. Всяка стъпка е три неща:

1. План. Моделът казва с думи какво ще направи: „първо проверявам дали поръчката е доставена“.
2. Действие. Моделът иска един инструмент (блок tool_use), а програмата го изпълнява.
3. Наблюдение. Резултатът се връща в историята (блок tool_result). На следващата стъпка моделът го вижда и избира пак.

Това е цикълът на агента. Програмата държи три изхода от него:

• Отговор. Моделът е готов и връща end_turn.
• Лимит на стъпките. След 5 стъпки без отговор програмата спира и предава на служител.
• Трябва човек. Моделът сам иска инструмента hand_to_human. Програмата не го изпълнява, а спира.

Инструментите на агента са безопасни: статус на поръчка, срок при куриера и заявка за връщане. Заявката само чака служител. Парите не минават през агента.

Виж го

Инструментите и данните

Четирите инструмента. Описанието е за модела: по него той избира.

def tool(name, description, field):
    schema = {"type": "object",
              "properties": {field: {"type": "string"}},
              "required": [field]}
    return {"name": name, "description": description,
            "input_schema": schema}


TOOLS = [
    tool("get_order_status",
         "Статус и дата на поръчка по номер.", "order_id"),
    tool("estimate_delivery",
         "Датата на доставка, която куриерът очаква.", "order_id"),
    tool("open_return_request",
         "Отваря заявка за връщане. Служител я одобрява.", "order_id"),
    tool("hand_to_human",
         "Предава разговора на служител, с причината.", "reason"),
]

Програмата изпълнява поисканото срещу своите данни. Заявката за връщане се записва в списък, който гледа служител:

def run_tool(use):
    order_id = use["input"].get("order_id", "")
    order = ORDERS.get(order_id)
    if order is None:
        return result(use, f"няма поръчка {order_id}", error=True)
    delivered = order["status"] == DELIVERED
    if use["name"] == "get_order_status":
        text = f"{order_id} — {order['status']}, доставка {order['date']}"
    elif use["name"] == "estimate_delivery":
        if delivered:
            text = f"{order_id} — вече е доставена"
        else:
            text = f"{order_id} — очаквана доставка {order['date']}, няма ново сканиране"
    elif use["name"] == "open_return_request":
        if not delivered:
            return result(use, f"{order_id} още не е доставена", error=True)
        request = f"R-{len(REQUESTS) + 1} за {order_id}"
        REQUESTS.append(request)
        text = f"{request} — чака одобрение от служител"
    else:
        return result(use, f"няма инструмент {use['name']}", error=True)
    return result(use, text)


def result(use, text, error=False):
    block = {"type": "tool_result", "tool_use_id": use["id"], "content": text}
    if error:
        block["is_error"] = True
    return block

hand_to_human го няма тук. Той не е действие, а изход от цикъла.

Виж го

Цикълът

def run_agent(model, task):
    print(f"задача: {task}")
    first = {"type": "text", "text": task}
    history = [{"role": "user", "content": [first]}]
    for step in range(1, MAX_STEPS + 1):
        reply = model.create(SYSTEM, history, TOOLS)
        head = f"  стъпка {step}. "
        text = text_of(reply)
        if reply["stop_reason"] != "tool_use":
            print(f"{head}край: {text}")
            return
        use = tool_use_of(reply)
        print(f"{head}план: {text}")
        action = describe(use)
        print(f"    действие: {action}")
        if use["name"] == "hand_to_human":
            print("  спирам: трябва човек —",
                  use["input"]["reason"])
            return
        history.append({"role": "assistant",
                        "content": reply["content"]})
        result = run_tool(use)
        print(f"    наблюдение: {result['content']}")
        history.append({"role": "user",
                        "content": [result]})
    print(f"  спирам: {MAX_STEPS} стъпки без отговор",
          "→ към служител")

Стъпка по стъпка, с думи

1. Задачата е първото съобщение. Агентът има 5 стъпки (MAX_STEPS) и четири инструмента.
2. Стъпка 1. Моделът казва план и иска едно действие: get_order_status(1187).
3. Не е hand_to_human, затова програмата го изпълнява. Наблюдението влиза в историята.
4. Стъпка 2. Моделът вижда „доставена“ и планът е друг: open_return_request(1187).
5. Инструментът само отваря заявка R-1. Тя чака служител: агентът не връща пари.
6. Стъпка 3. Моделът отговаря с end_turn: цикълът спира на отговор, след 3 от 5 стъпки.
7. Още два изхода чакат: лимитът на стъпките и hand_to_human. Без тях агентът може да върти безкрай.

Помощните функции намират плана (текстовия блок) и действието (блока tool_use):

def text_of(reply):
    return next((b["text"] for b in reply["content"] if b["type"] == "text"), "")


def tool_use_of(reply):
    return next(b for b in reply["content"] if b["type"] == "tool_use")


def describe(use):
    return f"{use['name']}({', '.join(use['input'].values())})"

def run_agent(model, task):
    print(f"задача: {task}")
    first = {"type": "text", "text": task}
    history = [{"role": "user", "content": [first]}]
    for step in range(1, MAX_STEPS + 1):
        reply = model.create(SYSTEM, history, TOOLS)
        head = f"  стъпка {step}. "
        text = text_of(reply)
        if reply["stop_reason"] != "tool_use":
            print(f"{head}край: {text}")
            return
        use = tool_use_of(reply)
        print(f"{head}план: {text}")
        action = describe(use)
        print(f"    действие: {action}")
        if use["name"] == "hand_to_human":
            print("  спирам: трябва човек —",
                  use["input"]["reason"])
            return
        history.append({"role": "assistant",
                        "content": reply["content"]})
        result = run_tool(use)
        print(f"    наблюдение: {result['content']}")
        history.append({"role": "user",
                        "content": [result]})
    print(f"  спирам: {MAX_STEPS} стъпки без отговор",
          "→ към служител")

model = FakeModel()
run_agent(model, "Слушалките от поръчка 1187 са повредени. Искам да ги върна.")
print("чака одобрение:", ", ".join(REQUESTS))

Изход

задача: Слушалките от поръчка 1187 са повредени. Искам да ги върна.
  стъпка 1. план: Първо проверявам дали поръчката е доставена.
    действие: get_order_status(1187)
    наблюдение: 1187 — доставена, доставка 26.10
  стъпка 2. план: Доставена е. Отварям заявка за връщане.
    действие: open_return_request(1187)
    наблюдение: R-1 за 1187 — чака одобрение от служител
  стъпка 3. край: Отворих заявка R-1 за връщане на 1187. Служител ще я одобри и ще ви пише.
чака одобрение: R-1 за 1187

Никъде в кода не пише „след статуса отвори заявка“. Моделът го избира, защото наблюдението казва „1187 — доставена, доставка 26.10“. Програмата пази лимита, изпълнява и записва.

Моделът тук е фалшив клиент като в предишните уроци: по думите на задачата и по наблюденията досега избира следващата стъпка. Правилото му е в „По-точно“.

Пробвай

Попълни

Кое действие програмата не изпълнява, а спира цикъла?

if use["name"] == "":

Провери

Идеята

Когато агентът не спира

Клиентът пише „Кога пристига 1042? Куриерът каза, че е днес.“. Куриерът няма ново сканиране, а моделът пита пак и пак:

model = FakeModel()
run_agent(model, "Кога пристига 1042? Куриерът каза, че е днес.")

Изход

задача: Кога пристига 1042? Куриерът каза, че е днес.
  стъпка 1. план: Питам куриера за срока.
    действие: estimate_delivery(1042)
    наблюдение: 1042 — очаквана доставка 03.11, няма ново сканиране
  стъпка 2. план: Няма промяна. Питам пак.
    действие: estimate_delivery(1042)
    наблюдение: 1042 — очаквана доставка 03.11, няма ново сканиране
  стъпка 3. план: Няма промяна. Питам пак.
    действие: estimate_delivery(1042)
    наблюдение: 1042 — очаквана доставка 03.11, няма ново сканиране
  стъпка 4. план: Няма промяна. Питам пак.
    действие: estimate_delivery(1042)
    наблюдение: 1042 — очаквана доставка 03.11, няма ново сканиране
  стъпка 5. план: Няма промяна. Питам пак.
    действие: estimate_delivery(1042)
    наблюдение: 1042 — очаквана доставка 03.11, няма ново сканиране
  спирам: 5 стъпки без отговор → към служител

Всяка стъпка праща цялата история, затова всяка следваща е по-скъпа от предишната (сметката е в урока за цената). Без лимита програмата върти, докато свършат парите. С него клиентът стига до човек след 5 стъпки.

Лимитът е последната защита, не единствената. Тук моделът пита за едно и също пет пъти, а програмата можеше да го види още на втората стъпка. Това е упражнението на урока.

Пробвай

Предвиди изхода

Клиентът иска обезщетение. Какво печата runAgent?

model = FakeModel()
run_agent(model, "Искам 20 € обезщетение, защото 1042 закъснява.")

Отговор

задача: Искам 20 € обезщетение, защото 1042 закъснява.
  стъпка 1. план: Проверявам поръчката.
    действие: get_order_status(1042)
    наблюдение: 1042 — изпратена, доставка 03.11
  стъпка 2. план: Проверявам поръчката.
    действие: get_order_status(1042)
    наблюдение: 1042 — изпратена, доставка 03.11
  стъпка 3. план: Проверявам поръчката.
    действие: get_order_status(1042)
    наблюдение: 1042 — изпратена, доставка 03.11
  стъпка 4. план: Проверявам поръчката.
    действие: get_order_status(1042)
    наблюдение: 1042 — изпратена, доставка 03.11
  стъпка 5. план: Проверявам поръчката.
    действие: get_order_status(1042)
    наблюдение: 1042 — изпратена, доставка 03.11
  спирам: 5 стъпки без отговор → към служител

задача: Искам 20 € обезщетение, защото 1042 закъснява.
  стъпка 1. план: Проверявам поръчката.
    действие: get_order_status(1042)
    наблюдение: 1042 — изпратена, доставка 03.11
  стъпка 2. план: Обезщетение решава служител, не аз.
    действие: hand_to_human(обезщетение за 1042)
  спирам: трябва човек — обезщетение за 1042

задача: Искам 20 € обезщетение, защото 1042 закъснява.
  стъпка 1. план: Проверявам поръчката.
    действие: get_order_status(1042)
    наблюдение: 1042 — изпратена, доставка 03.11
  стъпка 2. план: Доставена е. Отварям заявка за връщане.
    действие: open_return_request(1042)
    наблюдение: 1042 още не е доставена
  стъпка 3. край: Поръчката още не е доставена. Ще можете да я върнете след доставката.

Провери

Пробвай

Намери грешката

Колега пише runAgent и всеки разговор свършва със „5 стъпки без отговор“, дори когато клиентът е получил отговор. На кой ред е грешката?

Избери реда с грешката.

1def run_agent(model, task):2 print(f"задача: {task}")3 first = {"type": "text", "text": task}4 history = [{"role": "user", "content": [first]}]5 for step in range(1, MAX_STEPS + 1):6 reply = model.create(SYSTEM, history, TOOLS)7 head = f" стъпка {step}. "8 text = text_of(reply)9 if reply["stop_reason"] != "tool_use":10 print(f"{head}край: {text}")11 break12 use = tool_use_of(reply)13 print(f"{head}план: {text}")14 action = describe(use)15 print(f" действие: {action}")16 if use["name"] == "hand_to_human":17 print(" спирам: трябва човек —",18 use["input"]["reason"])19 return20 history.append({"role": "assistant",21 "content": reply["content"]})22 result = run_tool(use)23 print(f" наблюдение: {result['content']}")24 history.append({"role": "user",25 "content": [result]})26 print(f" спирам: {MAX_STEPS} стъпки без отговор",27 "→ към служител")

Провери

Идеята

Пусни при теб

Тази програма не е в проверката на урока: трябва ти профил при доставчик на модели, ключ и пари за всяко извикване. Ключът е в LLM_API_KEY, никога в кода. Доставчиците имат официални SDK-та за Java, C#, Python и JavaScript със същата форма (съобщения, роли, токени, инструменти); точните имена на класовете и методите са в документацията на доставчика.

Първата заявка носи задачата и четирите инструмента. Името на модела е заместител:

{
  "model": "<името на модела>",
  "max_tokens": 1024,
  "system": "Ти си агентът на поддръжката на онлайн магазин. Ползвай инструментите; парите решава служител.",
  "tools": [
    {
      "name": "get_order_status",
      "description": "Статус и дата на поръчка по номер.",
      "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    },
    {
      "name": "estimate_delivery",
      "description": "Датата на доставка, която куриерът очаква.",
      "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    },
    {
      "name": "open_return_request",
      "description": "Отваря заявка за връщане. Служител я одобрява.",
      "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    },
    {
      "name": "hand_to_human",
      "description": "Предава разговора на служител, с причината.",
      "input_schema": {
        "type": "object",
        "properties": {"reason": {"type": "string"}},
        "required": ["reason"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Слушалките от поръчка 1187 са повредени. Искам да ги върна."
    }
  ]
}

Отговорът носи и плана, и действието: текстов блок и блок tool_use в едно съобщение. Числата в usage са груби, по правилото от урока за инструментите:

{
  "content": [
    {
      "type": "text",
      "text": "Първо проверявам дали поръчката е доставена."
    },
    {
      "type": "tool_use",
      "id": "call_1",
      "name": "get_order_status",
      "input": {"order_id": "1187"}
    }
  ],
  "stop_reason": "tool_use",
  "usage": {"input_tokens": 72, "output_tokens": 11}
}

Всяка заявка се праща със стандартния HTTP клиент на езика, а цикълът около нея е runAgent. Адресът е заместител:

# request_json е JSON-ът на заявката отгоре.
# Точната заглавка за ключа е в документацията на доставчика.
import os
import urllib.request

request = urllib.request.Request(
    "https://<доставчик>/messages",
    data=request_json.encode("utf-8"),
    headers={"Authorization": "Bearer " + os.environ["LLM_API_KEY"],
             "Content-Type": "application/json"},
)
with urllib.request.urlopen(request) as response:
    print(response.read().decode("utf-8"))

Идеята

Кога вреди

• Пътят е известен. Ако „статус на поръчка“ винаги е една и съща заявка, напиши я с код. Агентът е по-бавен, по-скъп и всеки път може да избере друго. Той си струва, когато стъпките зависят от това, което се вижда по пътя.
• Действия с последствия. Връщане на пари, отмяна, имейл до всички клиенти. Агентът ги подготвя, човек ги одобрява. Моделът може да сбърка поръчката, а текстът, който чете, може да го подведе. Как става това, е в урока за prompt injection, а проверките около модела са в урока за предпазителите.
• Без граница. Лимит на стъпките, на токените (или еврото) и на времето. Всеки от тях спира агента и предава на човек, вместо да върти.
• Без лог. Когато агентът сбърка, трябва да видиш плана, действието и наблюдението на всяка стъпка. Изходът на runAgent е точно такъв лог.
• Без тестове. Агентът се мери като всяко приложение с модел: тестов набор от задачи и проверки на крайния отговор, но и на пътя (кои действия, колко стъпки).

По-точно, за любопитните

Едно действие на стъпка. Истинският модел може да поиска няколко инструмента в един отговор, както в урока за инструментите. Тук всяка стъпка е едно действие, за да се вижда редът. Програмата с няколко действия изпълнява всичките и връща всички резултати в едно user съобщение.

Планът е текст. Моделът пише „първо проверявам“, но нищо не го задължава да направи точно това. Програмата не вярва на плана, а изпълнява само действието, и то само ако е от списъка с инструменти. Планът е полезен за лога и за човека, който чете след това.

Име от статиите. Редуването „мисъл, действие, наблюдение“ се среща като ReAct (reason + act). Има и библиотеки за агенти, които държат цикъла вместо теб. Отвътре са същите три неща и същите изходи.

Фалшивият модел отвътре. Събира наблюденията от историята и брои колко са. За връщане: първо статус; ако е „доставена“, заявка; после отговор с номера на заявката. За обезщетение: статус, после hand_to_human. За куриера: пита пак при всяка стъпка. Номерата на tool_use са call_1, call_2.

# Стои на мястото на истинския модел: записани отговори,
# без мрежа и всеки път едни и същи.
class FakeModel:
    NOT_DELIVERED = "Поръчката още не е доставена. Ще можете да я върнете след доставката."
    THANKS = "Моля! Пишете, ако имате въпрос."

    def __init__(self):
        self.last_id = 0

    def create(self, system, messages, tools):
        task = messages[0]["content"][0]["text"]
        seen = [b["content"] for m in messages for b in m["content"]
                if b["type"] == "tool_result"]
        n = len(seen)
        order_id = "1187" if "1187" in task else "1042"
        if "върна" in task:
            if n == 0:
                return self.act("Първо проверявам дали поръчката е доставена.",
                                "get_order_status", "order_id", order_id)
            if n == 1 and "доставена" in seen[0]:
                return self.act("Доставена е. Отварям заявка за връщане.",
                                "open_return_request", "order_id", order_id)
            if n == 1:
                return self.say(self.NOT_DELIVERED)
            request = seen[-1].split(" ")[0]
            return self.say(f"Отворих заявка {request} за връщане на {order_id}. Служител ще я одобри и ще ви пише.")
        if "обезщетение" in task:
            if n == 0:
                return self.act("Проверявам поръчката.",
                                "get_order_status", "order_id", order_id)
            return self.act("Обезщетение решава служител, не аз.",
                            "hand_to_human", "reason", f"обезщетение за {order_id}")
        if "Куриерът" in task:
            plan = "Питам куриера за срока." if n == 0 else "Няма промяна. Питам пак."
            return self.act(plan, "estimate_delivery", "order_id", order_id)
        return self.say(self.THANKS)

    # План (текст) и едно действие (tool_use) в един отговор.
    def act(self, plan, tool, key, value):
        self.last_id += 1
        use = {"type": "tool_use", "id": f"call_{self.last_id}",
               "name": tool, "input": {key: value}}
        return {"content": [{"type": "text", "text": plan}, use],
                "stop_reason": "tool_use"}

    @staticmethod
    def say(text):
        return {"content": [{"type": "text", "text": text}],
                "stop_reason": "end_turn"}

Упражнение

Същото действие два пъти

Реши задачата в редактора си.

Клиентът пише „Кога пристига 1042? Куриерът каза, че е днес.“, а агентът пита куриера пет пъти, преди да спре. Добави в runAgent проверка: ако моделът иска същото действие като на предишната стъпка (същото име и същия вход), програмата печата спирам: същото действие два пъти → към служител и спира.

Изход

задача: Кога пристига 1042? Куриерът каза, че е днес.
  стъпка 1. план: Питам куриера за срока.
    действие: estimate_delivery(1042)
    наблюдение: 1042 — очаквана доставка 03.11, няма ново сканиране
  стъпка 2. план: Няма промяна. Питам пак.
    действие: estimate_delivery(1042)
  спирам: същото действие два пъти → към служител

Още задачи

• Бюджет на токени. Брой токените на всяка стъпка (думите × 1,3, както в урока за инструментите) и спри, когато сборът мине 300. На коя стъпка спира задачата с куриера?
• Недоставена поръчка. Пусни задача за връщане на поръчка 1042, която още не е доставена. Кой изход избира агентът и какво казва на клиента?

Тест

Провери се

1. Какво прави цикъла на агента различен от една заявка към модела?

Агентът пуска инструментите сам, без програматаМоделът избира следващата стъпка според наблюденията досега, а програмата я изпълнява и пита пакАгентът ползва по-голям модел

2. Кои са трите изхода от runAgent?

Отговор (end_turn), стъпките свършват (MAX_STEPS), моделът предава на човек (hand_to_human)Отговор, изключение и рестартСамо отговор: моделът винаги стига до края

3. Защо open_return_request само отваря заявка, вместо да върне парите?

Защото връщането на пари е бавноДействие с последствия (пари) иска човек: моделът може да сбърка поръчката или да бъде подведенЗащото API-то на модела не позволява инструменти с пари

4. Моделът иска estimate_delivery(1042) за пети път и наблюдението не се мени. Какво трябва да направи програмата?

Да спре и да предаде на служителДа върне на клиента последния план като отговорДа пита пак, докато куриерът отговори

Провери

Започни урока отначало

Свързани уроци

• Нужно отпреди: Структуриран изход: JSON по схема · Инструменти: моделът пита, програмата прави · Оценяване: тестов набор за асистента · Цена и бавност: бюджет, кеш, по-малък модел
• Продължава в: Prompt injection: писмото, което дава нареждания · Предпазители: проверки преди и след модела · Асистентът на поддръжката
• Задачи по темата: Агенти