Chapterبەش 4 · Lectureوانە 4.1

AI Agents and Loop Engineeringئەیجێنتەکانی ژیریی دەستکرد و ئەندازیاریی خول

How an AI agent works and how to design its loop: tool use (the model asks, the program runs), tool definitions, the agent loop and ReAct, a runnable toy agent in Python, loop engineering, stop conditions and the endless-loop mistake, checking results and tool errors, human approval and least privilege, workflows versus agents, keeping the context clean, and the Model Context Protocol (MCP).

چۆن کار دەکات و چۆن دیزاین دەکرێت: ( داوا دەکات، جێبەجێ دەکات)، پێناسەی ئامراز، و ReAct، یاریی کارپێکراو لە Pythonـدا، ، و هەڵەی ، پشکنینی ئەنجام و هەڵەکانی ئامراز، ڕەزامەندیی مرۆڤ و ، بەرامبەر ، پاک هێشتنەوەی کۆنتێکست و ⁦(MCP)⁩.

24 min read24 خولەک خوێندنەوە · 22 stepsهەنگاو

What you will learnچی فێر دەبیت

Explain tool use: the model asks for a tool, the program runs it and returns the result.
Write a clear tool definition with a name, a description and an input schema.
Trace an agent loop in Python and give it stop conditions: done, step limit, budget, repeated failure.
Make a loop safe: check results in code, return tool errors as results, require approval for risky actions, give least privilege.
Choose between one call, a workflow and an agent, and explain context engineering and MCP.

ڕوون بکەیتەوە: داوای ئامرازێک دەکات، جێبەجێی دەکات و ئەنجامەکە دەگەڕێنێتەوە.
پێناسەیەکی ڕوونی ئامراز بە ناو، وەسف و بنووسیت.
بەدوای لە Pythonـدا بچیت و بدەیتێ: تەواوبوون، سنووری هەنگاو، بودجە، هەڵەی دووپاتە.
سەلامەت بکەیت: ئەنجامەکان لە کۆددا بپشکنیت، هەڵەکانی ئامراز وەک ئەنجام بگەڕێنیتەوە، بۆ کردەوە مەترسیدارەکان داوای ڕەزامەندی بکەیت، پەیڕەو بکەیت.
لە نێوان یەک بانگکردن، و هەڵبژێریت و و MCP ڕوون بکەیتەوە.

Taste, add salt, taste againتام بکە، خوێی تێبکە، دووپاتە تام بکەرەوە

Dilan is cooking lentil soup for her guests. She tastes it, adds a little salt, stirs and tastes again. She repeats this until the soup tastes right. If the guests arrive first, she serves it anyway: she cannot keep tasting for ever.

دیلان شۆربای نیسک بۆ میوانەکانی لێدەنێت. تامی دەکات، کەمێک خوێی تێدەکات، تێکی دەدات و دووپاتە تامی دەکاتەوە. ئەمە دووپاتە دەکاتەوە تا تامەکەی ڕێک دەبێت. ئەگەر میوانەکان زووتر گەیشتن، هەر وا پێشکەشی دەکات: ناتوانێت هەتاهەتایە تام بکات.

An AI agent works the same way. A language model decides the next step, a program carries it out with a tool, the result is checked, and the model decides again. This repeating cycle is the agent loop. Designing it well (what the agent may do, how each result is checked, when it must stop) is what this course calls loop engineering: the topic of this lesson.

بە هەمان شێوە کار دەکات. هەنگاوی داهاتوو بڕیار دەدات، بە ئامرازێک جێبەجێی دەکات، ئەنجامەکە دەپشکنرێت و دووپاتە بڕیار دەداتەوە. ئەم خولە، کە هەر دووپاتە دەبێتەوە، . دیزاینکردنی بە باشی (کە چی بۆی هەیە بکات، هەر ئەنجامێک چۆن دەپشکنرێت و کەی دەبێت بوەستێت) ئەوەیە کە ئەم کۆرسە پێی دەڵێت : بابەتی ئەم وانەیە.

Every loop needs a goal and a way out.هەر پێویستی بە ئامانج و ڕێگایەکی دەرچوون هەیە.CêIT

From chatbot to agentلە چاتبۆتەوە بۆ ئەیجێنت

You met AI agents in From chatbot to AI agent: a chatbot answers one message; an agent takes a goal and carries out many steps with tools, checking the results as it goes. The classic AI words still fit: the tools are the agent's actuators, the tool results are its percepts, and the language model together with the loop code around it is the agent program.

لە وانەی لە چاتبۆتەوە بۆ ئەیجێنتی ژیریی دەستکردـدا ناسی: وەڵامی یەک نامە دەداتەوە؛ ئامانجێک وەردەگرێت و بە ئامرازەکان چەندین هەنگاو جێبەجێ دەکات و لە ڕێگادا ئەنجامەکان دەپشکنێت. وشە کۆنەکانی هێشتا دەگونجێن: ئامرازەکان ، ئەنجامی ئامرازەکان ئەون و لەگەڵ کۆدی دەوروبەری بەرنامەی ئەیجێنتە.

What is new is who chooses the next step. In a classic agent, a programmer wrote every rule. In an agent built on a large language model, the model chooses the next step from the goal and from everything that has happened so far.

ئەوەی نوێیە ئەوەیە کە کێ هەنگاوی داهاتوو هەڵدەبژێرێت. لە کلاسیکدا، بەرنامەنووس هەموو یاسایەکی نووسیبوو. لە کە لەسەر دروست کراوە، هەنگاوی داهاتوو لە ئامانجەکە و لە هەموو ئەوەی تا ئێستا ڕوویداوە هەڵدەبژێرێت.

A chatbot answers; an agent works towards a goal. وەڵام دەداتەوە؛ بەرەو ئامانجێک کار دەکات.CêIT

Tool use: the model asks, the program runsبەکارهێنانی ئامراز: مۆدێلەکە داوا دەکات، بەرنامەکە جێبەجێ دەکات

A language model only writes text. By itself it cannot open a database, look up today's price or send an order. Tool use, also called function calling, solves this. The program tells the model which tools exist. When the model needs one, it does not answer in prose: it writes a structured request such as get_price(item="notebook"). The program runs the function and sends the result back, and the model continues with the result in front of it.

تەنیا دەق دەنووسێت. خۆی بە تەنیا ناتوانێت بکاتەوە، نرخی ئەمڕۆ بدۆزێتەوە یان داواکردنێک بنێرێت. ئەمە چارەسەر دەکات؛ هەندێک دابینکەر پێی دەڵێن . بە دەڵێت چ ئامرازێک هەیە. کاتێک پێویستی بە یەکێکیان دەبێت، بە پەخشان وەڵام ناداتەوە: داوایەکی ڕێکخراو دەنووسێت وەک get_price(item="notebook"). جێبەجێ دەکات و ئەنجامەکە دەگەڕێنێتەوە و بە ئەنجامەکەوە بەردەوام دەبێت.

Keep the order of work in mind: the model asks, your code runs. Anthropic's documentation stresses that the model never runs anything on its own. So your code decides what really happens, and your code is responsible for it.

ڕیزبەندیی کارەکە لە بیر بێت: داوا دەکات، کۆدەکەت جێبەجێ دەکات. بەڵگەنامەکانی Anthropic جەخت دەکەنەوە کە هەرگیز خۆی شتێک جێبەجێ ناکات. بۆیە کۆدەکەت بڕیار دەدات چی بەڕاستی ڕوو دەدات و کۆدەکەت بەرپرسیارە لێی.

One tool call is a round trip: model → program → tool → program → model.هەر بانگکردنێکی ئامراز گەشتێکی چوون و گەڕانەوەیە: ← ← ئامراز ← ← .CêIT

Tool use: the model asks, the program runsبەکارهێنانی ئامراز: مۆدێلەکە داوا دەکات، بەرنامەکە جێبەجێ دەکات

Three APIs, one ideaسێ API، یەک بیرۆکە

Every big provider offers tool use, with its own field names. The idea is the same in all three: a tool definition goes in, a tool request comes out, and a result goes back with the same id.

هەموو دابینکەرە گەورەکان پێشکەش دەکەن، هەریەکە بە ناوی خانەی خۆی. بیرۆکەکە لە هەر سێکیاندا یەکە: پێناسەی ئامراز دەچێتە ژوورەوە، داوای ئامراز دێتە دەرەوە و ئەنجامێک بە هەمان ناسێنەر دەگەڕێتەوە.

Tool use in three APIs (as of November 2026) لە سێ APIـدا (تا تشرینی دووەمی ⁦2026⁩)
Provider (API)دابینکەر ⁦(API)⁩	Nameناو	The model asks with بەمە داوا دەکات	The program answers with بەمە وەڵام دەداتەوە
Anthropic (Claude API)	tool use	`tool_use`	`tool_result`
OpenAI (Responses API)	function calling	`function_call`	`function_call_output`
Google (Gemini API)	function calling	`function_call`	`function_result`

Check the current documentationبەڵگەنامەی ئێستا بپشکنە

Field names change between API versions. As of November 2026 all three providers describe the same steps: send the tool list, receive a call, run it in your code, send the result back, repeat if the model asks for more. Check the provider's own documentation before you build.

ناوی خانەکان لە نێوان وەشانەکانی APIـدا دەگۆڕێن. تا تشرینی دووەمی ⁦2026⁩ هەر سێ دابینکەرەکە هەمان هەنگاوەکان وەسف دەکەن: لیستی ئامرازەکان بنێرە، داوایەک وەربگرە، لە کۆدەکەتدا جێبەجێی بکە، ئەنجامەکە بگەڕێنەوە و ئەگەر داوای زیاتری کرد دووپاتەی بکەرەوە. پێش دروستکردن بەڵگەنامەی خودی دابینکەرەکە بخوێنەوە.

Describing a tool to the modelوەسفکردنی ئامرازێک بۆ مۆدێل

The model can use only the tools it is told about, and it knows them only from their definitions. A definition has three parts: a name, a description in plain words (what the tool does, when to use it, what it returns) and an input schema: a JSON Schema that lists the inputs, their types and which are required.

تەنیا دەتوانێت ئەو ئامرازانە بەکار بهێنێت کە پێی گوتراون و تەنیا لە ڕێگەی پێناسەکانیانەوە دەیانناسێت. پێناسەیەک سێ بەشی هەیە: ناو، وەسف بە وشەی سادە (ئامرازەکە چی دەکات، کەی بەکار بێت، چی دەگەڕێنێتەوە) و : کە ، جۆرەکانیان و ئەوانەی پێویستن دەژمێرێت.

One tool definition (Claude API format)یەک پێناسەی ئامراز (شێوازی Claude API)JSON

{
  "name": "get_stock",
  "description": "Returns how many copies of one book are on the shelves of Shilan's bookshop. Use it before promising a book to a customer.",
  "input_schema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "The exact book title, for example Mem u Zin"}
    },
    "required": ["title"]
  }
}

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 2

A short, specific name with no spaces.

ناوێکی کورت و دیاریکراو بێ بۆشایی.

Lineدێڕی 3

The model reads this like a note to a new shop assistant: say what it does and when to use it.

ئەمە وەک یاداشتێک بۆ فرۆشیارێکی نوێ دەخوێنێتەوە: بڵێ چی دەکات و کەی بەکار بێت.

Lineدێڕی 4-10

The inputs as a JSON Schema. OpenAI and Google call this part parameters.

وەک . OpenAI و Google بەم بەشە دەڵێن parameters.

Vague definitions give vague use. Use specific names and types, explain the edge cases, and keep the set small (Google's guide suggests at most 10 to 20 active tools). Karwan gives Shilan's helper three tools: search_catalogue and get_stock only read data, while send_order spends money, so it is marked risky.

پێناسەی ناڕوون بەکارهێنانی ناڕوون دەهێنێت. ناو و جۆری دیاریکراو بەکار بهێنە، حاڵەتە نائاساییەکان ڕوون بکەرەوە و ژمارەی ئامرازەکان کەم بهێڵەرەوە (ڕێبەرەکەی Google دەڵێت زۆرترین ⁦10⁩ تا ⁦20⁩ ئامرازی چالاک). کاروان سێ ئامراز دەداتە یاریدەدەرەکەی شیلان: search_catalogue و get_stock تەنیا دەخوێننەوە، بەڵام send_order پارە خەرج دەکات، بۆیە وەک مەترسیدار نیشانە دەکرێت.

Three tools, two of them read-only and one risky.سێ ئامراز: دووانیان تەنیا دەخوێننەوە و یەکێکیان مەترسیدارە.CêIT

The agent loopخولی ئەیجێنت

Put tool use inside a loop and you have an agent. Each turn has four parts:

بخە ناو و دەبێت. هەر گەڕێک چوار بەشی هەیە:

Decide: the model reads the goal and everything so far, then chooses: call a tool, or answer.
Act: the program runs the tool the model asked for.
Observe: the tool's result is added to the conversation.
Check: is the goal reached, or has a limit been hit? If neither, go round again.

بڕیاردان: ئامانجەکە و هەموو ئەوەی تا ئێستا ڕوویداوە دەخوێنێتەوە و هەڵدەبژێرێت: ئامرازێک بانگ بکات یان وەڵام بداتەوە.
جێبەجێکردن: ئەو ئامرازە جێبەجێ دەکات کە داوای کردووە.
وەرگرتنی ئەنجام: ئەنجامی ئامرازەکە دەخرێتە سەر گفتوگۆکە.
پشکنین: ئایا گەیشتین بە ئامانج، یان گەیشتینە سنوورێک؟ ئەگەر هیچیان نا، دووپاتە بسووڕێوە.

Researchers named an early form of this pattern ReAct (Yao and others, 2022): the model writes a short thought, takes an action, reads the observation and repeats. Today the providers build the loop into their APIs: as long as Claude's API ends a turn with the stop reason tool_use, the program runs the tool and calls the model again.

توێژەران شێوەیەکی سەرەتایی ئەم ڕێگایەیان ناو نا ReAct (Yao و هاوکارانی، ⁦2022⁩): بیرێکی کورت دەنووسێت، کردەوەیەک دەکات، ئەنجامەکە دەخوێنێتەوە و دووپاتەی دەکاتەوە. ئەمڕۆ دابینکەران دەخەنە ناو خۆیانەوە: تا Claude API گەڕێک بە هۆکاری وەستانی tool_use کۆتایی پێبهێنێت، ئامرازەکە جێبەجێ دەکات و دووپاتە بانگ دەکاتەوە.

Animation of the agent loop for “How much do 3 notebooks cost?”. Four boxes in a circle: decide, act, observe, check. A step counter in the corner goes 1, 2, 3 out of a limit of 8. Step 1: the model decides to call get_price, the program runs it, the result 1500 is added. Step 2: the model calls multiply(1500, 3), the result 4500 is added. Step 3: the model answers “3 notebooks cost 4500 dinars” and the check box turns green: goal reached, the loop stops. — Decide → act → observe → check, until the goal or a limit.بڕیاردان ← جێبەجێکردن ← وەرگرتنی ئەنجام ← پشکنین، تا ئامانج یان سنوورێک.CêIT

A toy agent in Pythonئەیجێنتێکی یاری لە Pythonـدا

Here is the whole loop in plain Python, with no API key and nothing to install. The function fake_model() stands in for the language model: like a real model it reads the history and returns either a tool call or an answer. The tools are ordinary functions, found by name in a dictionary.

ئەمە هەموو بە Pythonـی سادە، بێ و بێ دامەزراندنی هیچ شتێک. fake_model() لە جیاتی کار دەکات: وەک ڕاستەقینە مێژووەکە دەخوێنێتەوە و یان داوای ئامرازێک یان وەڵامێک دەگەڕێنێتەوە. ئامرازەکان ئاسایین و بە ناو لە فەرهەنگێکدا دەدۆزرێنەوە.

The agent loop with a fake modelخولی ئەیجێنت بە مۆدێلێکی ساختەagent_loop.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

# A toy agent loop: a fake "model" decides, ordinary Python functions are the tools.
PRICES = {"notebook": 1500, "pen": 500, "dictionary": 12000}   # dinars (made-up prices)

def get_price(item):
    """Tool: look up the price of one item."""
    return {"item": item, "price": PRICES[item]}

def multiply(a, b):
    """Tool: multiply two numbers exactly."""
    return {"result": a * b}

TOOLS = {"get_price": get_price, "multiply": multiply}

def run_tool(name, args):
    return TOOLS[name](**args)          # find the function by its name and call it

def fake_model(history):
    """Stands in for a language model. A real model would read the goal;
    this fake one always plans the same steps."""
    results = [h["content"] for h in history if h["role"] == "tool"]
    if not results:
        return {"type": "tool_call", "name": "get_price", "args": {"item": "notebook"}}
    last = results[-1]
    if "price" in last:
        return {"type": "tool_call", "name": "multiply", "args": {"a": last["price"], "b": 3}}
    return {"type": "answer", "text": f"3 notebooks cost {last['result']} dinars."}

def run_agent(goal, model, max_steps=5):
    history = [{"role": "user", "content": goal}]
    for step in range(1, max_steps + 1):
        action = model(history)                          # 1. think: the model decides
        if action["type"] == "answer":                   # 4. done? leave the loop
            print(f"step {step}: answer -> {action['text']}")
            return action["text"]
        result = run_tool(action["name"], action["args"])  # 2. act: the PROGRAM runs the tool
        print(f"step {step}: {action['name']}({action['args']}) -> {result}")
        history.append({"role": "tool", "content": result})  # 3. observe: the result goes back
    print("stopped: step limit reached")
    return None

run_agent("How much do 3 notebooks cost?", fake_model)

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 4-10

The tools: ordinary Python functions that return a dictionary.

ئامرازەکان: ئاسایی Python کە دەگەڕێننەوە.

Lineدێڕی 12-15

Look up the function by its name and call it with the model's inputs (**args).

بە ناوەکەی بدۆزەرەوە و بە بانگی بکە (**args).

Lineدێڕی 17-26

The fake model: no tool result yet → ask for the price; a price → ask to multiply; a total → answer.

ساختەکە: هێشتا ئەنجامی ئامراز نییە ← داوای نرخ؛ نرخێک ← داوای لێکدان؛ کۆیەک ← وەڵام.

Lineدێڕی 30

The loop has a built-in limit: at most max_steps turns.

سنوورێکی تێدایە: زۆرترین max_steps گەڕ.

Lineدێڕی 31-37

Decide, check for an answer, act, then add the result to the history.

بڕیاردان، پشکنینی وەڵام، جێبەجێکردن ← زیادکردنی ئەنجامەکە بۆ مێژووەکە.

Read the output as a trace: three model turns, two tool calls, one answer. The multiplication was done by Python, not by the model, so the total is exact. Step through loops like this one in the trace lab.

وەک بخوێنەوە: سێ گەڕی ، دوو بانگکردنی ئامراز، یەک وەڵام. لێکدانەکە Python کردی، نەک ، بۆیە کۆکە ورد و دروستە. لەم جۆرە هەنگاو بە هەنگاو لە تاقیگەی بەدواداچوونـدا ببینە.

The trace of agent_loop.py: the history grows by one item per tool call. ⁦agent_loop.py⁩: مێژووەکە بە هەر بانگکردنێکی ئامراز یەک شت زیاد دەکات.CêIT

A toy agent in Pythonئەیجێنتێکی یاری لە Pythonـدا

The same loop with a real model (example only)هەمان خول بە مۆدێلێکی ڕاستەقینە (تەنیا نموونە)

With a real model, fake_model() becomes a call to the provider's API, and the history becomes the messages list. This sketch follows Anthropic's tool-use documentation. Compare it with the toy: the same four parts, the same step limit.

بە ڕاستەقینە، fake_model() دەبێتە بانگکردنی دابینکەرەکە و مێژووەکە دەبێتە messages. ئەم نموونەیە پەیڕەوی بەڵگەنامەکانی Anthropic دەکات. لەگەڵ یارییەکە بەراوردی بکە: هەمان چوار بەش و هەمان سنووری هەنگاو.

Example only (not run): the loop with the Claude APIتەنیا نموونە (جێبەجێ نەکراوە): خولەکە بە Claude APIreal_loop.pyPYTHON

import anthropic

client = anthropic.Anthropic()        # reads the API key from the environment
tools = [{
    "name": "get_price",
    "description": "Price in Iraqi dinars of one item sold in Shilan's bookshop.",
    "input_schema": {
        "type": "object",
        "properties": {"item": {"type": "string", "description": "Item name, e.g. notebook"}},
        "required": ["item"],
    },
}]
messages = [{"role": "user", "content": "How much do 3 notebooks cost?"}]

for step in range(8):                  # stop rule: at most 8 model calls
    response = client.messages.create(
        model="claude-opus-5-5", max_tokens=1024, tools=tools, messages=messages)
    if response.stop_reason != "tool_use":
        break                          # end_turn, max_tokens, refusal ...: leave the loop
    messages.append({"role": "assistant", "content": response.content})
    results = []
    for block in response.content:
        if block.type == "tool_use":
            output = run_tool(block.name, block.input)       # YOUR code runs the tool
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": str(output)})
    messages.append({"role": "user", "content": results})

if response.stop_reason == "tool_use":
    print("stopped: step limit reached")
else:
    print(next(b.text for b in response.content if b.type == "text"))

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 3

The key is read from the environment, never written in the code.

لە ژینگەی سیستەمەکەوە دەخوێنرێتەوە، هەرگیز لە کۆدەکەدا نانووسرێت.

Lineدێڕی 15

The stop rule: at most 8 calls to the model.

یاسای وەستان: زۆرترین 8 بانگکردنی .

Lineدێڕی 18-19

Any stop reason other than tool_use ends the loop.

هەر هۆکارێکی وەستان جگە لە tool_use کۆتایی پێدەهێنێت.

Lineدێڕی 24-26

run_tool() is your own code, as in the toy; the result goes back with the same tool_use_id.

run_tool() کۆدی خۆتە، وەک لە یارییەکەدا؛ ئەنجامەکە بە هەمان tool_use_id دەگەڕێتەوە.

Same loop, real parts: only the model call changes.هەمان ، بەشی ڕاستەقینە: تەنیا بانگکردنی دەگۆڕێت.CêIT

Loop engineering: designing the loopئەندازیاریی خول: دیزاینکردنی خولەکە

The loop code is short. The hard part is the decisions around it. Loop engineering is making those decisions before the agent runs. Karwan answers seven questions for Shilan's helper:

کۆدی کورتە. بەشە قورسەکە ئەو بڕیارانەیە کە بە دەوریدان. دانانی ئەو بڕیارانەیە پێش ئەوەی کار بکات. کاروان وەڵامی حەوت پرسیار بۆ یاریدەدەرەکەی شیلان دەداتەوە:

Goal: what does “done” look like? (a reply with price and stock, or an order waiting for approval)
Tools: the smallest set that does the job.
What the model sees on each turn: instructions, tools, history, results.
Checks: how each result is tested, by code or data, not by the model's word.
Stop rules: done, step limit, budget, repeated failure.
Approval: which actions wait for a person.
Logs: every call and result is written down, so mistakes can be traced.

ئامانج: «تەواو» چۆنە؟ (وەڵامێک بە نرخ و کۆگاوە، یان داواکردنێک کە چاوەڕێی ڕەزامەندییە)
ئامرازەکان: بچووکترین کۆمەڵە کە کارەکە دەکات.
چی دەبینێت لە هەر گەڕێکدا: ڕێنمایی، ئامراز، مێژوو، ئەنجام.
پشکنین: هەر ئەنجامێک چۆن تاقی دەکرێتەوە، بە کۆد یان ، نەک بە قسەی .
یاساکانی وەستان: تەواوبوون، سنووری هەنگاو، بودجە، هەڵەی دووپاتە.
ڕەزامەندی: کام کردەوە چاوەڕێی مرۆڤێک دەکات.
: هەموو بانگکردنێک و ئەنجامێک دەنووسرێتەوە، بۆ ئەوەی بەدوای هەڵەکاندا بچیت.

Seven decisions to make before an agent runs.حەوت بڕیار کە دەبێت پێش کارکردنی بدرێن.CêIT

About the nameلەبارەی ناوەکە

Loop engineering is the name this course uses for designing agent loops. Since mid-2026 some practitioners use the phrase too (for example Addy Osmani's essay “Loop Engineering”, June 2026), but it is not yet a standard term. Provider documentation speaks of agents, the agentic loop, the harness (the code around the model) and context engineering. The skills are the same, whatever the name.

ئەو ناوەیە کە ئەم کۆرسە بۆ دیزاینکردنی بەکاری دەهێنێت. لە ناوەڕاستی ⁦2026⁩ـەوە هەندێک پسپۆڕیش ئەم دەستەواژەیە بەکار دەهێنن (بۆ نموونە وتارەکەی Addy Osmani بە ناوی «Loop Engineering»، حوزەیرانی ⁦2026⁩)، بەڵام هێشتا زاراوەیەکی ستاندارد نییە. بەڵگەنامەکانی دابینکەران باسی ، ، harness (ئەو کۆدەی بە دەوری ) و دەکەن. لێهاتووییەکان هەمان شتن، ناوەکە هەرچییەک بێت.

When must the loop stop?خولەکە کەی دەبێت بوەستێت؟

A model may never say “done”. It can repeat the same call, follow a wrong idea, or keep trying a tool that keeps failing. So every agent loop needs several stop conditions, and it stops at whichever comes first:

لەوانەیە هەرگیز نەڵێت «تەواو». دەتوانێت هەمان بانگکردن دووپاتە بکاتەوە، بەدوای بیرۆکەیەکی هەڵەدا بچێت، یان بەردەوام ئامرازێک تاقی بکاتەوە کە هەر شکست دێنێت. بۆیە هەموو پێویستی بە چەند هەیە و بە هەرکامیان کە یەکەم جار بێت دەوەستێت:

Done: the model answers, and the answer passes the checks.
Step limit: for example at most 8 model calls.
Budget: tokens, money or time. Every turn sends the whole history again, so the cost of a loop grows fast (history grows).
Repeated failure: the same error three times → stop and ask a person.

تەواوبوون: وەڵام دەداتەوە و وەڵامەکە لە پشکنینەکان دەردەچێت.
سنووری هەنگاو: بۆ نموونە زۆرترین 8 بانگکردنی .
بودجە: ، پارە یان کات. هەر گەڕێک هەموو مێژووەکە دووپاتە دەنێرێتەوە، بۆیە تێچووی خێرا زیاد دەکات (مێژوو گەورە دەبێت).
هەڵەی دووپاتە: هەمان هەڵە سێ جار ← بوەستە و لە مرۆڤێک بپرسە.

It is the rule you met in infinite loops: a loop needs a condition that will surely end it. Here the model controls what happens, so only the program can guarantee that it ends.

ئەمە هەمان ئەو یاسایەیە کە لە خولە بێکۆتاکانـدا بینیت: پێویستی بە کە بە دڵنیاییەوە کۆتایی پێبهێنێت. لێرەدا چی ڕوو دەدات کۆنترۆڵ دەکات، بۆیە تەنیا دەتوانێت دڵنیا بێت کە کۆتایی دێت.

Four ways out; the first one reached wins.چوار ڕێگای دەرچوون؛ یەکەمیان کە پێی بگەیت.CêIT

When must the loop stop?خولەکە کەی دەبێت بوەستێت؟

The step limit at workسنووری هەنگاو لە کاتی کارکردندا

Give the toy loop a stubborn model that keeps asking for the same price. Add these lines to agent_loop.py in place of its last line:

سەرسەخت بدە بە یارییەکە کە هەر داوای هەمان نرخ دەکات. ئەم دێڕانە لە جیاتی دوایین دێڕی agent_loop.py دابنێ:

A model that never answersمۆدێلێک کە هەرگیز وەڵام ناداتەوەagent_loop.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

def stubborn_model(history):
    """A model that keeps checking the same price and never answers."""
    return {"type": "tool_call", "name": "get_price", "args": {"item": "notebook"}}

run_agent("How much do 3 notebooks cost?", stubborn_model, max_steps=4)

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 5

The same loop, now with a limit of 4 turns.

هەمان ، ئێستا بە سنووری 4 گەڕ.

The model never stopped, but the program did. Without the limit, this would run, and cost, for ever.

هەرگیز نەوەستا، بەڵام وەستا. بەبێ سنوورەکە، ئەمە بۆ هەمیشە کار دەکات و تێچووی دەبێت.

When must the loop stop?خولەکە کەی دەبێت بوەستێت؟

Common mistake: a loop with no way outهەڵەی باو: خولێک بێ ڕێگای دەرچوون

A beginner writes the loop as while True and waits for the model to say “answer”. The stubborn model never does. Here one second of time.sleep() stands for waiting for a real model:

سەرەتاکارێک بە while True دەنووسێت و چاوەڕێ دەکات بڵێت «answer». سەرسەختەکە هەرگیز نایڵێت. لێرەدا یەک چرکەی time.sleep() جێگەی چاوەڕێکردنی ڕاستەقینە دەگرێتەوە:

Wrong: no step limit, no budgetهەڵە: نە سنووری هەنگاو، نە بودجەendless.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

import time

def stubborn_model(history):
    return {"type": "tool_call", "name": "get_price", "args": {"item": "notebook"}}

history = []
step = 0
while True:                         # no step limit, no budget: nothing can stop it
    step += 1
    action = stubborn_model(history)
    if action["type"] == "answer":
        break
    time.sleep(1)                   # stands for waiting about a second for a real model
    print(f"step {step}: {action['name']}({action['args']})")

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 8

Nothing in the program can end this loop; only the model could, and it never does.

هیچ شتێک لە ناتوانێت ئەم کۆتایی پێبهێنێت؛ تەنیا دەتوانێت و هەرگیز ناکات.

A real run, stopped by hand with Ctrl+C after four steps. With a real model, every one of those steps would also cost tokens. The fix: loop over range(1, max_steps + 1) as run_agent() does, and add a budget check if each step costs money.

کارکردنێکی ڕاستەقینە کە دوای چوار هەنگاو بە دەست بە ⁦Ctrl+C⁩ وەستێنرا. بە ڕاستەقینە، هەر یەکێک لەو هەنگاوانە تێدەچوو. چارەسەر: وەک run_agent() بەسەر range(1, max_steps + 1)ـدا بکە و ئەگەر هەر هەنگاوێک پارەی تێدەچێت، پشکنینی بودجەش زیاد بکە.

The model decides what happens; only the program can guarantee that it ends. بڕیار دەدات چی ڕوو بدات؛ تەنیا دەتوانێت دڵنیا بێت کە کۆتایی دێت.CêIT

Check results with facts, not trustئەنجامەکان بە ڕاستی بپشکنە، نەک بە متمانە

A model can be wrong in a confident voice, so a good loop checks results against ground truth: data from a database, a sum done in code, a test that passes or fails, a schema the reply must match. Anthropic's “Building effective agents” says the same: an agent should get the facts from its environment at every step. In Shilan's helper, Python computes every total and the stock comes from the shop's database: the model never guesses a number.

دەتوانێت بە دەنگێکی دڵنیاوە هەڵە بێت، بۆیە باش ئەنجامەکان لەگەڵ ڕاستیی سەلمێنراو بەراورد دەکات: لە ، کۆکردنەوەیەک کە کۆد کردوویەتی، تاقیکردنەوەیەک کە دەردەچێت یان شکست دێنێت، کە وەڵامەکە دەبێت لەگەڵیدا یەک بگرێتەوە. وتاری «Building effective agents»ـی Anthropic هەمان شت دەڵێت: دەبێت لە هەموو هەنگاوێکدا ڕاستییەکان لە وەربگرێت. لە یاریدەدەرەکەی شیلاندا Python هەموو کۆیەک دەژمێرێت و کۆگا لە کتێبخانەکەوە دێت: هەرگیز ژمارەیەک مەزەندە ناکات.

Tools fail too: an unknown item, a missing input, a server that is down. Do not let the program crash. Send the error back as the tool's result, with a clear message, so the model can correct itself or tell the user honestly. Claude's API even has a field for this, is_error.

ئامرازەکانیش شکست دێنن: کاڵایەکی نەناسراو، ون، کە کار ناکات. مەهێڵە بتەقێتەوە. هەڵەکە وەک ئەنجامی ئامرازەکە بە پەیامێکی ڕوون بگەڕێنەوە، بۆ ئەوەی خۆی ڕاست بکاتەوە یان بە ڕاستگۆیی بە بڵێت. Claude API تەنانەت خانەیەکی بۆ ئەمە هەیە: is_error.

Facts come from code and data; errors go back to the model as results.ڕاستییەکان لە کۆد و دێن؛ هەڵەکان وەک ئەنجام بۆ دەگەڕێنەوە.CêIT

Check results with facts, not trustئەنجامەکان بە ڕاستی بپشکنە، نەک بە متمانە

Tool errors in Pythonهەڵەکانی ئامراز لە Pythonـدا

Common mistake: the toy run_tool() trusts the model's tool name. A model that asks for a tool nobody gave it crashes the whole program:

هەڵەی باو: run_tool()ـی یارییەکە متمانە بە ناوی ئامرازی دەکات. کە داوای ئامرازێک بکات کە کەس پێی نەداوە، هەموو دەتەقێنێتەوە:

Wrong: an unknown tool name crashes the loopهەڵە: ناوی ئامرازێکی نەناسراو خولەکە دەتەقێنێتەوەagent_loop.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

def guessing_model(history):
    """A model that asks for a tool nobody gave it."""
    return {"type": "tool_call", "name": "get_discount", "args": {"item": "notebook"}}

run_agent("Is there a discount on notebooks?", guessing_model)

The fix: check the name, catch wrong inputs, and turn every problem into a result the model can read. The price tool also reports an unknown item instead of raising KeyError:

چارەسەر: ناوەکە بپشکنە، هەڵە بگرە و هەموو کێشەیەک بکە بە ئەنجامێک کە بتوانێت بیخوێنێتەوە. ئامرازی نرخیش لە جیاتی KeyError ڕاپۆرتی کاڵای نەناسراو دەدات:

Fixed: errors become tool resultsچاککراو: هەڵەکان دەبنە ئەنجامی ئامرازtool_errors.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

PRICES = {"notebook": 1500, "pen": 500, "dictionary": 12000}   # dinars (made-up prices)

def get_price(item):
    if item not in PRICES:
        return {"error": f"no item called '{item}' in the catalogue"}
    return {"item": item, "price": PRICES[item]}

TOOLS = {"get_price": get_price}

def run_tool(name, args):
    """Never crash: every problem goes back to the model as a result."""
    if name not in TOOLS:
        return {"error": f"unknown tool '{name}'; available: {list(TOOLS)}"}
    try:
        return TOOLS[name](**args)
    except TypeError as e:              # wrong or missing arguments
        return {"error": str(e)}

def fake_model(history):
    results = [h["content"] for h in history if h["role"] == "tool"]
    if not results:
        return {"type": "tool_call", "name": "get_price", "args": {"item": "atlas"}}
    last = results[-1]
    if "error" in last:
        return {"type": "answer", "text": "Sorry, I could not find an atlas in the catalogue."}
    return {"type": "answer", "text": f"An atlas costs {last['price']} dinars."}

history = [{"role": "user", "content": "How much is the atlas?"}]
for step in range(1, 6):
    action = fake_model(history)
    if action["type"] == "answer":
        print(f"step {step}: answer -> {action['text']}")
        break
    result = run_tool(action["name"], action["args"])
    print(f"step {step}: {action['name']}({action['args']}) -> {result}")
    history.append({"role": "tool", "content": result})

print(run_tool("get_discount", {"item": "pen"}))
print(run_tool("get_price", {"name": "pen"}))

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 3-6

An unknown item is reported, not crashed on.

کاڵای نەناسراو ڕاپۆرت دەکرێت، نەک تەقینەوە.

Lineدێڕی 10-17

Unknown tool or wrong inputs: return {"error": ...}.

ئامرازی نەناسراو یان هەڵە: {"error": ...} بگەڕێنەوە.

Lineدێڕی 24-25

With the error in front of it, the model answers honestly.

کاتێک هەڵەکە لەبەردەمیدایە، بە ڕاستگۆیی وەڵام دەداتەوە.

Lineدێڕی 38-39

Two more tests: a made-up tool name, and a wrong input name.

دوو تاقیکردنەوەی تر: ناوی ئامرازێکی دروستکراو و ناوی هەڵە.

Approval and permissionsڕەزامەندی و مۆڵەتەکان

Some actions cannot be undone: paying, sending a message, deleting a file, ordering 500 notebooks. For these, keep a human in the loop (in, on or out of the loop): the agent prepares the action, then waits until a person approves it.

هەندێک کردەوە ناگەڕێنەوە: پارەدان، ناردنی نامە، سڕینەوەی ، داواکردنی ⁦500⁩ دەفتەر. بۆ ئەمانە پێویستە (لە ناو، لەسەر یان لە دەرەوەی خول): کردەوەکە ئامادە دەکات ← چاوەڕێ دەکات تا مرۆڤێک ڕەزامەندی لەسەر بدات.

Give the agent only what the task needs (least privilege): read-only access where reading is enough, no delete tool if nothing must be deleted, an allow-list of permitted actions, a sandbox for running code, and a log of every call. The OWASP Top 10 for LLM Applications (2025) names the opposite excessive agency (LLM06): too many tools, too many permissions or too much freedom to act unchecked.

تەنیا ئەوەندە بدە بە کە ئەرکەکە پێویستیەتی (): دەستڕاگەیشتنی تەنیا خوێندنەوە کاتێک خوێندنەوە بەسە، هیچ ئامرازێکی سڕینەوە ئەگەر هیچ شتێک نەبێت بسڕدرێتەوە، بۆ کردەوەکان، بۆ جێبەجێکردنی کۆد و بۆ هەموو بانگکردنێک. لیستی ⁦OWASP Top 10 for LLM Applications (2025)⁩ بە پێچەوانەکەی دەڵێت ⁦(LLM06)⁩: ئامرازی زۆر، زۆر یان ئازادییەکی زۆر بۆ کردەوە بەبێ پشکنین.

Run freely, wait for approval, or never give the tool at all.بە ئازادی جێبەجێ بکە، چاوەڕێی ڕەزامەندی بکە، یان هەرگیز ئامرازەکە مەدە.CêIT

Approval and permissionsڕەزامەندی و مۆڵەتەکان

An approval gate in Pythonدەروازەی ڕەزامەندی لە Pythonـدا

The gate sits inside run_tool(), in the program, not in the prompt. A prompt can be ignored or tricked; an if in your code cannot. Only an exact yes counts:

دەروازەکە لە ناو run_tool()ـدایە، لە ، نەک لە . دەکرێت پشتگوێ بخرێت یان فریو بدرێت؛ ifـێک لە کۆدەکەتدا ناکرێت. تەنیا yesـێکی ڕێک حیساب دەکرێت:

Risky tools wait for Shilanئامرازە مەترسیدارەکان چاوەڕێی شیلان دەکەنapproval.pyPYTHONType in a terminalلە تێرمیناڵدا بینووسە

RISKY = {"send_order"}                      # tools that spend money or change the world

def send_order(item, qty):
    return {"status": f"order sent: {qty} x {item}"}

TOOLS = {"send_order": send_order}

def approve(name, args):
    """Ask the person in charge. Only an exact 'yes' counts."""
    answer = input(f"Shilan, allow {name}({args})? yes/no: ")
    return answer.strip().lower() == "yes"

def run_tool(name, args):
    if name in RISKY and not approve(name, args):
        return {"error": "the shop owner did not approve this action"}
    return TOOLS[name](**args)

print(run_tool("send_order", {"item": "notebook", "qty": 500}))
print(run_tool("send_order", {"item": "notebook", "qty": 50}))

Explain the codeڕوونکردنەوەی کۆدەکە

Lineدێڕی 1

The program, not the model, decides which tools are risky.

، نەک ، بڕیار دەدات کام ئامراز مەترسیدارە.

Lineدێڕی 8-11

Ask the person in charge; anything but yes means no.

لە بەرپرسەکە بپرسە؛ هەر شتێک جگە لە yes واتە نا.

Lineدێڕی 14-15

A refusal goes back to the model as an error result, like any other failure.

ڕەتکردنەوە وەک ئەنجامێکی هەڵە بۆ دەگەڕێتەوە، وەک هەر شکستێکی تر.

A sample run: Shilan typed no to 500 notebooks and yes to 50. In a real app the question would be a button, and every decision would also go into the log.

نموونەیەکی کارکردن: شیلان بۆ ⁦500⁩ دەفتەر noی نووسی و بۆ ⁦50⁩ yes. لە ئەپێکی ڕاستەقینەدا پرسیارەکە دوگمەیەک دەبێت و هەموو بڕیارێکیش دەچێتە ناو .

Start simple: workflows before agentsسادە دەست پێبکە: ڕەوتی کار پێش ئەیجێنت

Not every task needs an agent. Anthropic's “Building effective agents” (December 2024) separates two kinds of system. In a workflow, the programmer fixes the steps in code. In an agent, the model chooses its own steps and tools. The advice: find the simplest solution that works, and add complexity only when it clearly helps. The common workflow patterns are:

هەموو ئەرکێک پێویستی بە نییە. وتاری «Building effective agents»ـی Anthropic (کانوونی یەکەمی ⁦2024⁩) دوو جۆر سیستەم لێک جیا دەکاتەوە. لە بەرنامەنووس هەنگاوەکان لە کۆددا جێگیر دەکات. لە خۆی هەنگاو و ئامرازەکانی هەڵدەبژێرێت. ئامۆژگارییەکە: سادەترین چارەسەر کە کار دەکات بدۆزەرەوە و تەنیا کاتێک ئاڵۆزی زیاد بکە کە بە ڕوونی سوود دەگەیەنێت. شێوازە باوەکانی ئەمانەن:

Prompt chaining: fixed steps one after another, with a check between them (prompt chaining).
Routing: sort the input first, then send it to the right handler.
Parallel calls: several calls at once, then combine the results or let them vote.
Orchestrator and workers: one model splits the job and hands the parts to others.
Evaluator and optimiser: one call writes, another checks and asks for changes, in a loop.

: هەنگاوی جێگیر یەک لە دوای یەک، بە پشکنینێک لە نێوانیاندا (زنجیرەکردنی هەوێن).
ئاڕاستەکردن: سەرەتا پۆل بکە ← بینێرە بۆ چارەسەرکەری گونجاو.
بانگکردنی هاوکات: چەند بانگکردنێک لە یەک کاتدا ← ئەنجامەکان کۆ بکەرەوە یان با دەنگ بدەن.
ڕێکخەر و کارکەران: کارەکە دابەش دەکات و بەشەکان دەداتە ئەوانی تر.
هەڵسەنگێنەر و باشترکەر: بانگکردنێک دەنووسێت، یەکێکی تر دەپشکنێت و داوای گۆڕانکاری دەکات، لە .

Choose an agent when the steps cannot be known in advance, the result is worth the extra cost, and mistakes can be caught by checks or approval. Shilan's “sort this message” is one call, “answer a customer” is a workflow, and only “plan next month's stock order” became an agent.

هەڵبژێرە کاتێک هەنگاوەکان پێشتر نازانرێن، ئەنجامەکە شایەنی تێچووە زیادەکەیە و هەڵەکان بە پشکنین یان ڕەزامەندی دەگیرێن. «ئەم نامەیە پۆل بکە»ـی شیلان یەک بانگکردنە، «وەڵامی کڕیارێک بدەرەوە» و تەنیا «داواکردنی کۆگای مانگی داهاتوو پلان بکە» بوو بە .

Climb the ladder only when the step below is not enough.تەنیا کاتێک بە پەیژەکەدا سەر بکەوە کە پلەی خوارەوە بەس نەبێت.CêIT

Keeping the context clean in long loopsپاک هێشتنەوەی کۆنتێکست لە خولە درێژەکاندا

Every turn adds to the conversation: the model's request, the tool's result, the next request. Ten search results of 3,000 tokens each are 30,000 tokens that the model reads again on every later turn. That costs money (history grows) and, worse, quality drops when the context is long and noisy: the model's recall gets weaker as the context grows (context rot).

هەر گەڕێک شتێک دەخاتە سەر گفتوگۆکە: داوای ، ئەنجامی ئامرازەکە، داوای داهاتوو. دە ئەنجامی گەڕان کە هەریەکەیان ⁦3,000⁩ دەکاتە ⁦30,000⁩ کە لە هەموو گەڕێکی دواتردا دووپاتە دەیخوێنێتەوە. ئەمە پارەی تێدەچێت (مێژوو گەورە دەبێت) و خراپتر ئەوەیە کە کوالیتی دادەبەزێت کاتێک کۆنتێکست درێژ و پڕ لە شتی بێسوود بێت: بیرهێنانەوەی لاواز دەبێت هەرچەندە کۆنتێکستەکە گەورەتر بێت (ڕزینی کۆنتێکست).

So a loop engineer also chooses what the model sees: context engineering, keeping the smallest set of useful tokens. Anthropic's “Effective context engineering for AI agents” (September 2025) describes these ways:

بۆیە ئەندازیاری ئەوەش هەڵدەبژێرێت کە دەیبینێت: ، هێشتنەوەی بچووکترین کۆمەڵەی بەسوود. وتاری «Effective context engineering for AI agents»ـی Anthropic (ئەیلوولی ⁦2025⁩) ئەم ڕێگایانە وەسف دەکات:

Clear old tool results that the agent no longer needs.
Compaction: summarise the history and carry on from the summary.
Notes: the agent writes its progress to a file (such as NOTES.md) and reads it back later.
Sub-agents: a helper agent works in its own clean context and returns a short summary, often 1,000 to 2,000 tokens (multi-agent systems).

سڕینەوەی ئەنجامە کۆنەکانی ئامراز کە چیتر پێویستی پێیان نییە.
: پوختەی مێژووەکە بنووسە و لە پوختەکەوە بەردەوام بە.
یاداشت: پێشکەوتنی خۆی لە دەنووسێت (وەک NOTES.md) و دواتر دەیخوێنێتەوە.
ژێرئەیجێنت: یاریدەدەر لە کۆنتێکستێکی پاکی خۆیدا کار دەکات و پوختەیەکی کورت دەگەڕێنێتەوە، زۆرجار ⁦1,000⁩ تا ⁦2,000⁩ (سیستەمە فرەئەیجێنتەکان).

Animation of a context window drawn as a long bar. Turn 1: instructions and tools fill a small part. Turns 2 to 5: four large orange blocks of search results are added, and the bar nears its limit. Then compaction: the old results shrink into one small green summary block, and a NOTES.md file appears beside the bar. The bar has room again for the next turns. — Tool results fill the window; compaction and notes make room again.ئەنجامی ئامرازەکان پەنجەرەکە پڕ دەکەنەوە؛ و یاداشت دووپاتە جێگا دەکەنەوە.CêIT

Connecting tools: the Model Context Protocolبەستنەوەی ئامرازەکان: پرۆتۆکۆڵی کۆنتێکستی مۆدێل

Each app used to connect each tool in its own way. The Model Context Protocol (MCP) is an open standard for connecting AI apps to outside tools and data. Anthropic introduced it in November 2024 and in December 2025 handed it to the Agentic AI Foundation, part of the Linux Foundation. As of November 2026, Claude, ChatGPT, VS Code and Cursor are among the apps that support it. Its documentation compares it to a USB-C port: one plug shape for many devices.

پێشتر هەر ئەپێک هەر ئامرازێکی بە شێوەی خۆی دەبەستەوە. ⁦(MCP)⁩ ستانداردێکی کراوەیە بۆ بەستنەوەی ئەپەکانی بە ئامراز و دەرەکی. Anthropic لە تشرینی دووەمی ⁦2024⁩ـدا ناساندی و لە کانوونی یەکەمی ⁦2025⁩ـدا دایە Agentic AI Foundation کە بەشێکە لە Linux Foundation. تا تشرینی دووەمی ⁦2026⁩، Claude، ChatGPT، VS Code و Cursor لەو ئەپانەن کە پشتگیریی دەکەن. بەڵگەنامەکەی بە کونی ⁦USB-C⁩ بەراوردی دەکات: یەک شێوەی پلاک بۆ چەندین ئامێر.

An MCP server offers three kinds of things: tools (actions, such as search_catalogue), resources (data to read, such as the catalogue's columns) and prompts (ready-made templates). The AI app opens one connection to each server, asks tools/list to see what is there and tools/call to use a tool (specification version 2026-07-28). Real desktop apps already offer such a server next to their windows: see Case Study: ArtCraft.

MCP سێ جۆر شت پێشکەش دەکات: ئامراز (کردەوە، وەک search_catalogue)، سەرچاوە ( بۆ خوێندنەوە، وەک ستوونەکانی لیستی کتێبەکان) و (قاڵبی ئامادە). ئەپی بۆ هەر یەک پەیوەندی دەکاتەوە، بە tools/list دەپرسێت چی هەیە و بە tools/call ئامرازێک بەکار دەهێنێت (وەشانی تایبەتمەندیی ⁦2026-07-28⁩). ڕاستەقینەی سەر مێز ئێستا MCP لە تەنیشت پەنجەرەکانیان پێشکەش دەکەن: بڕوانە نموونەیەکی ڕاستەقینە: ArtCraft.

One protocol, many servers: like one USB-C port for many devices.یەک ، چەندین : وەک یەک کونی ⁦USB-C⁩ بۆ چەندین ئامێر.CêIT

Trust before you connectپێش بەستنەوە متمانە بپشکنە

An MCP server's tool descriptions and results are text the model reads, and a local server runs with your permissions. Connect only servers you trust, give them the least access they need, and keep human approval for risky actions.

وەسفی ئامرازەکان و ئەنجامەکانی MCP دەقێکن کە دەیانخوێنێتەوە و ناوخۆیی بە تۆ کار دەکات. تەنیا ئەو ببەستەوە کە متمانەت پێیانە، کەمترین دەستڕاگەیشتنیان بدەیە کە پێویستیانە و ڕەزامەندیی مرۆڤ بۆ کردەوە مەترسیدارەکان بهێڵەرەوە.

Common mistakesهەڵە باوەکان

Watch out for theseئاگاداری ئەمانە بە

“The model runs the tool.” It only asks; your code runs it, and your code is responsible.
No step limit or budget: a stubborn model loops for ever and keeps spending.
Vague tool names and descriptions (do_stuff, “gets data”): the model guesses wrong inputs.
Every permission “to be safe”: that is excessive agency; give the least privilege.
Crashing on a tool error instead of returning the error as a result.
Trusting the model's numbers: compute totals, dates and prices in code.
Obeying text found in tool results (a web page that says “ignore your rules”): that is data, not an order (prompt injection).
Building an agent for a job that one call or a fixed workflow can do.

« ئامرازەکە جێبەجێ دەکات.» تەنیا داوا دەکات؛ کۆدەکەت جێبەجێی دەکات و کۆدەکەت بەرپرسیارە.
نە سنووری هەنگاو نە بودجە: سەرسەخت بۆ هەمیشە دەسووڕێتەوە و هەر خەرج دەکات.
ناو و وەسفی ناڕوونی ئامراز (do_stuff، «دراوە دەهێنێت»): هەڵە مەزەندە دەکات.
هەموو «بۆ دڵنیایی»: ئەمە ؛ پەیڕەو بکە.
تەقینەوە بە هەڵەی ئامراز لە جیاتی گەڕاندنەوەی هەڵەکە وەک ئەنجام.
متمانەکردن بە ژمارەکانی : کۆ، ڕێکەوت و نرخ لە کۆددا بژمێرە.
پەیڕەوکردنی دەقێک کە لە ئەنجامی ئامرازدا دۆزراوەتەوە ( کە دەڵێت «یاساکانت پشتگوێ بخە»): ئەوە ، نەک فەرمان (تێخزاندنی هەوێن).
دروستکردنی بۆ کارێک کە یەک بانگکردن یان جێگیر دەتوانێت بیکات.

Exercisesڕاهێنانەکان

ExerciseڕاهێنانDesign Aram's homework plannerدیزاینکردنی پلاندانەری ئەرکی ماڵەوەی ئارام

Aram wants an agent that plans his homework for the week from his college timetable and the due dates his teachers post. Answer the seven loop-engineering questions for it.

ئارام دەوێت کە ئەرکی ماڵەوەی هەفتەکەی لە خشتەی وانەکانی کۆلێژ و ئەو ڕێکەوتانەی مامۆستاکانی بڵاویان دەکەنەوە پلان بکات. وەڵامی حەوت پرسیارەکەی بۆی بدەرەوە.

Show answerوەڵامەکە پیشان بدە

Goal: a day-by-day plan for this week, each task with its due date.
Tools: read the timetable, read the due dates, write to Aram's own calendar. No e-mail, no delete.
What the model sees: the goal, the tool list, today's date, the results so far.
Checks: every date in the plan exists in the timetable; no task is placed after its due date (checked in code).
Stop rules: plan written and checked; at most 10 steps; the same error twice → stop and tell Aram.
Approval: Aram approves before anything is written to his calendar.
Logs: each tool call with its inputs and result, so he can see why a task landed on Tuesday.

ئامانج: پلانێکی ڕۆژ بە ڕۆژ بۆ ئەم هەفتەیە، هەر ئەرکێک بە ڕێکەوتی ڕادەستکردنییەوە.
ئامرازەکان: خوێندنەوەی خشتەی وانەکان، خوێندنەوەی ڕێکەوتەکان، نووسین لە ڕۆژژمێری خودی ئارامدا. نە ، نە سڕینەوە.
چی دەبینێت: ئامانجەکە، لیستی ئامرازەکان، ڕێکەوتی ئەمڕۆ، ئەنجامەکانی تا ئێستا.
پشکنین: هەموو ڕێکەوتێکی پلانەکە لە خشتەکەدا هەیە؛ هیچ ئەرکێک دوای ڕێکەوتی ڕادەستکردنی دانانرێت (بە کۆد دەپشکنرێت).
یاساکانی وەستان: پلانەکە نووسرا و پشکنرا؛ زۆرترین ⁦10⁩ هەنگاو؛ هەمان هەڵە دوو جار ← بوەستە و بە ئارام بڵێ.
ڕەزامەندی: ئارام پێش نووسینی هەر شتێک لە ڕۆژژمێرەکەیدا ڕەزامەندی دەدات.
: هەر بانگکردنێکی ئامراز بە و ئەنجامەکەیەوە، بۆ ئەوەی ببینێت بۆچی ئەرکێک کەوتە سێشەممە.

ExerciseڕاهێنانTrace the loop by handبەدواداچوونی خولەکە بە دەست

In agent_loop.py, Hana changes fake_model() so that it asks for the price of "pen" and multiplies by 4, and the goal becomes “How much do 4 pens cost?”. Without running it, fill a trace table: step, what the model chose, what the program ran, the result. Then write the output.

لە agent_loop.pyـدا هانا fake_model() دەگۆڕێت بۆ ئەوەی داوای نرخی "pen" بکات و لە 4 لێکی بدات و ئامانجەکە دەبێتە «4 پێنووس چەندە؟». بەبێ جێبەجێکردن پڕ بکەرەوە: هەنگاو، چی هەڵبژارد، چی جێبەجێ کرد، ئەنجام. پاشان بنووسە.

Hintئاماژە

The price list says a pen costs 500 dinars.

لیستی نرخەکان دەڵێت پێنووسێک ⁦500⁩ دینارە.

Show answerوەڵامەکە پیشان بدە

Stepهەنگاو	The model chose هەڵیبژارد	The program ran جێبەجێی کرد	Resultئەنجام
1	`get_price(item="pen")`	`get_price`	`{'item': 'pen', 'price': 500}`
2	`multiply(a=500, b=4)`	`multiply`	`{'result': 2000}`
3	answer: “4 pens cost 2000 dinars.”وەڵام: «⁦4 pens cost 2000 dinars⁩.»	nothing: the loop endsهیچ: کۆتایی دێت	—

The real outputدەرخستەی ڕاستەقینە

step 1: get_price({'item': 'pen'}) -> {'item': 'pen', 'price': 500}
step 2: multiply({'a': 500, 'b': 4}) -> {'result': 2000}
step 3: answer -> 4 pens cost 2000 dinars.

ExerciseڕاهێنانFind the missing stop ruleیاسای وەستانی ون بدۆزەرەوە

Rebin's agent loop is written as while response.stop_reason == "tool_use": ... with nothing else. What can go wrong, and how would you fix it?

ڕێبین بەم شێوەیە نووسراوە: while response.stop_reason == "tool_use": ... و هیچی تر. چی دەکرێت هەڵە بێت و چۆن چاکی دەکەیت؟

Show answerوەڵامەکە پیشان بدە

The loop ends only when the model stops asking for tools. A model that keeps calling tools, or a tool that keeps failing, makes it run and spend for ever. Fix: loop over range(max_steps) (or count the steps and break at the limit), add a budget check on tokens or money, stop after the same error repeats, and log every turn.

تەنیا کاتێک کۆتایی دێت کە داوای ئامراز ڕابگرێت. کە هەر ئامراز بانگ بکات، یان ئامرازێک کە هەر شکست بهێنێت، وای لێدەکات بۆ هەمیشە کار بکات و خەرج بکات. چارەسەر: بەسەر range(max_steps)ـدا بکە (یان هەنگاوەکان بژمێرە و لە سنوورەکەدا break بکە)، پشکنینی بودجەی یان پارە زیاد بکە، دوای دووپاتەبوونەوەی هەمان هەڵە بوەستە و هەموو گەڕێک لە تۆمار بکە.

ExerciseڕاهێنانOne call, workflow or agent?یەک بانگکردن، ڕەوتی کار یان ئەیجێنت؟

Choose the simplest design for each: (a) translate a book description into Kurdish; (b) every customer message: sort it, then answer from the matching template; (c) research which new books the shop should stock next term, using sales data, publishers' lists and the web.

سادەترین دیزاین بۆ هەریەکەیان هەڵبژێرە: ⁦(a)⁩ وەرگێڕانی وەسفی کتێبێک بۆ کوردی؛ ⁦(b)⁩ هەموو نامەیەکی کڕیار: پۆلی بکە ← لە قاڵبی گونجاوەوە وەڵامی بدەرەوە؛ ⁦(c)⁩ لێکۆڵینەوە لەوەی کتێبخانەکە کام کتێبی نوێ بۆ وەرزی داهاتوو بهێنێت، بە فرۆش، لیستی بڵاوکەرەوەکان و وێب.

Show answerوەڵامەکە پیشان بدە

(a) One model call: one input, one output, no tools.
(b) A workflow (routing): the steps are fixed and known in advance.
(c) An agent: the steps depend on what each search finds; add a step limit, a budget and Shilan's approval for the final list.

⁦(a)⁩ یەک بانگکردنی : یەک ، یەک ، بێ ئامراز.
⁦(b)⁩ (ئاڕاستەکردن): هەنگاوەکان جێگیرن و پێشتر زانراون.
⁦(c)⁩ : هەنگاوەکان بەستراونەتەوە بەوەی هەر گەڕانێک چی دەدۆزێتەوە؛ سنووری هەنگاو، بودجە و ڕەزامەندیی شیلان بۆ لیستی کۆتایی زیاد بکە.

Summaryپوختە

Tool use: the model asks for a tool by name and inputs; the program runs it and sends the result back.
Tool definitions: name, plain description, input schema; few, clear tools.
Agent loop: decide → act → observe → check, again and again.
Loop engineering: goal, tools, what the model sees, checks, stop rules, approval, logs.
Stop conditions: done, step limit, budget, repeated failure; the program enforces them.
Safety: facts from code and data, errors as results, human approval for risky actions, least privilege, sandbox, logs.
Start simple: one call → workflow → agent, only as far as the task needs.
Context and MCP: keep the context small and clean; connect trusted tools through MCP.

: بە ناو و داوای ئامرازێک دەکات؛ جێبەجێی دەکات و ئەنجامەکە دەگەڕێنێتەوە.
پێناسەی ئامراز: ناو، وەسفی سادە، ؛ ئامرازی کەم و ڕوون.
: بڕیاردان ← جێبەجێکردن ← وەرگرتنی ئەنجام ← پشکنین، جار لە دوای جار.
: ئامانج، ئامراز، ئەوەی دەیبینێت، پشکنین، یاساکانی وەستان، ڕەزامەندی، .
: تەواوبوون، سنووری هەنگاو، بودجە، هەڵەی دووپاتە؛ جێبەجێیان دەکات.
سەلامەتی: ڕاستی لە کۆد و ، هەڵە وەک ئەنجام، ڕەزامەندیی مرۆڤ بۆ کردەوە مەترسیدارەکان، ، ، .
سادە دەست پێبکە: یەک بانگکردن ← ← ، تەنیا تا ئەو شوێنەی ئەرکەکە پێویستیەتی.
کۆنتێکست و MCP: کۆنتێکست بچووک و پاک بهێڵەرەوە؛ ئامرازە متمانەپێکراوەکان لە ڕێگەی MCPـەوە ببەستەوە.

Loop engineering in one picture. لە یەک وێنەدا.CêIT

Next: what can go wrong with generative AI, and how to use it safely and honestly: Limits and safety.

داهاتوو: چی دەکرێت لە هەڵە بڕوات و چۆن بە سەلامەتی و ڕاستگۆیی بەکاری بهێنین: سنوور و سەلامەتی.

Lesson complete!وانەکە تەواو بوو!

Well done. Review the key terms, then go on to the next lesson.دەستخۆش. سەیرێکی زاراوە سەرەکییەکان بکەرەوە، پاشان بڕۆ بۆ وانەی داهاتوو.

Key termsزاراوە سەرەکییەکان

Next lessonوانەی داهاتوو

Limits and Safety: Using Generative AI Responsiblyسنوور و سەلامەتی: بەکارهێنانی بەرپرسیارانەی ژیریی دەستکردی بەرهەمهێنەر

Related lecturesوانە پەیوەندیدارەکان

References and further readingسەرچاوەکان و خوێندنەوەی زیاتر

This lecture is a first edition. The Kurdish text and terminology are waiting for review by Kurdish IT teachers.ئەم وانەیە چاپی یەکەمە. دەقە کوردییەکە و زاراوەکانی چاوەڕێی پێداچوونەوەی مامۆستایانی کوردی بواری IT ن.