Tool calling loop

সহজ ভাষায়

LLM লিখতে পারে, কিন্তু নিজে কিছু করতে পারে না। আজকের আবহাওয়া জানে না, তোমার database দেখতে পারে না, ইমেইল পাঠাতে পারে না। Tool calling এই দরজা খোলে। তুমি model-কে কিছু function-এর বিবরণ দাও, আর model ঠিক করে কখন কোনটা দরকার।

user:       ঢাকায় এখন কয় ডিগ্রি?
model:      [tool_use] get_weather(city="Dhaka")        ← model শুধু চায়
তোমার code: get_weather("Dhaka") চালাও → 31             ← তুমি চালাও
তুমি:       [tool_result] 31
model:      ঢাকায় এখন ৩১°C।

কেন দরকার?

এটাই AI agent-এর ভিত্তি। Claude Code-এর মতো coding agent, customer support bot যেটা order দেখতে পারে, data analyst bot যেটা SQL চালায়: সবই এই loop। Model সিদ্ধান্ত নেয়, তোমার code কাজ করে।

ধাপ ১: Tool-এর বিবরণ

প্রতিটা tool-এর একটা নাম, বিবরণ আর input-এর JSON schema থাকে। Model এই বিবরণ পড়েই ঠিক করে কখন tool-টা ব্যবহার করবে, তাই বিবরণ পরিষ্কার হওয়া জরুরি।

tools = [{
    "name": "get_price",
    "description": "একটা বাজার পণ্যের আজকের দাম (টাকা প্রতি কেজি) দেয়।",
    "input_schema": {
        "type": "object",
        "properties": {"item": {"type": "string", "description": "পণ্যের নাম, যেমন চাল"}},
        "required": ["item"],
    },
}]

response = client.messages.create(
    model="claude-opus-5-5", max_tokens=1024, tools=tools,
    messages=[{"role": "user", "content": "চালের দাম কত?"}],
)

ধাপ ২: Model-এর উত্তরে tool_use

Model tool চাইলে stop_reason হয় "tool_use", আর content-এ একটা tool_use block থাকে:

ধাপ ৩: চালাও আর ফেরত পাঠাও

তোমার code function চালায়। তারপর ফলাফল একটা tool_result block হিসেবে user message-এ পাঠায়। tool_use_id দিয়ে কোন call-এর ফলাফল সেটা মেলানো হয়।

messages:
  user       "চালের দাম কত?"
  assistant  [text "দাম দেখছি।", tool_use id=toolu_01 get_price(চাল)]
  user       [tool_result tool_use_id=toolu_01 content="75"]
  assistant  "১ কেজি চালের দাম ৭৫ টাকা।"        ← stop_reason: end_turn

Model এক উত্তরে একাধিক tool চাইতে পারে। তখন সব ফলাফল একসাথে একটা user message-এ পাঠাতে হয়।

Agent loop

সব মিলিয়ে একটা loop: যতক্ষণ model tool চায়, ততক্ষণ চালাও আর ফেরত দাও।

         ┌────────────────────────────────────────┐
         ▼                                        │
  model call ──► stop_reason == "tool_use"? ──yes──► tool চালাও, ফলাফল যোগ করো
         │
         no
         ▼
   final উত্তর

নিরাপত্তা: সবচেয়ে গুরুত্বপূর্ণ অংশ

Model-এর tool call হলো অবিশ্বস্ত input:

• Model ভুল argument দিতে পারে, অথবা prompt injection-এর শিকার হয়ে ক্ষতিকর argument দিতে পারে
• তাই প্রতিটা tool-এর input যাচাই করো (আগের lesson)
• বিপজ্জনক কাজে (টাকা পাঠানো, ডেটা মোছা, ইমেইল পাঠানো) মানুষের অনুমোদন (human-in-the-loop) নাও
• Tool-কে শুধু ততটুকু ক্ষমতা দাও যতটুকু দরকার (least privilege)

Exercise

Exercise

একটা tool call চালাও

+20 XP

Model একটা tool_use block দেয়, যেমন {"type": "tool_use", "id": "t1", "name": "add", "input": {"a": 2, "b": 3}}।

run_tool(block, tools) লেখো। tools হলো {নাম: Python function} dict। Return করবে একটা tool_result block:

• সফল হলে: {"type": "tool_result", "tool_use_id": block-এর id, "content": str(ফলাফল)}
• নাম অচেনা হলে বা function exception দিলে: একই block, কিন্তু "content"-এ error message (string), আর অতিরিক্ত "is_error": True

Function call হবে input dict-কে keyword argument হিসেবে দিয়ে।

solution.pyশুধু RunSubmit

def add(a, b): return a + b def divide(a, b): return a / b tools = {"add": add, "divide": divide} def run_tool(block, tools): pass print(run_tool({"type": "tool_use", "id": "t1", "name": "add", "input": {"a": 2, "b": 3}}, tools)) print(run_tool({"type": "tool_use", "id": "t2", "name": "divide", "input": {"a": 1, "b": 0}}, tools))

Hint দেখাওSolution দেখো

Quiz

1. Q1Tool calling-এ function আসলে কে চালায়?

   LLM নিজেতোমার code — model শুধু বলে কোন tool কোন argument দিয়ে চাই; তুমি চালিয়ে ফলাফল ফেরত পাঠাওProvider-এর server
2. Q2Tool-এ exception হলে সবচেয়ে ভালো কী?

   পুরো program crash করানোError-টা tool_result হিসেবে (is_error সহ) model-কে ফেরত পাঠানো — যাতে model বুঝে অন্যভাবে চেষ্টা করতে বা user-কে জানাতে পারেচুপচাপ উপেক্ষা করা
3. Q3Agent loop-এ max_steps কেন দরকার?

   দরকার নেইModel বারবার tool চাইতে থাকলে অসীম loop আর অসীম খরচ আটকাতে

0/3 answeredউত্তর যাচাই করো →

Challenge

Challenge

Agent loop

+50 XP

run_agent(call_model, tools, user_message, max_steps=5) লেখো। call_model(messages) একটা response dict দেয়: {"stop_reason": ..., "content": [block, ...]}।

Loop: 1. messages-এ user message দিয়ে শুরু 2. Model call করো, তারপর তার content একটা assistant message হিসেবে যোগ করো 3. stop_reason যদি "tool_use" না হয়: সব text block-এর লেখা জুড়ে return করো 4. হলে: সব tool_use block run_tool দিয়ে চালাও, আর সব ফলাফল একসাথে একটাই user message-এ যোগ করো (content = tool_result-এর list)। তারপর ২-এ ফেরো। 5. max_steps বার model call করার পরও শেষ না হলে RuntimeError

Return: (final_text, messages)

solution.pyশুধু RunSubmit

def run_tool(block, tools): base = {"type": "tool_result", "tool_use_id": block["id"]} if block["name"] not in tools: return {**base, "content": f"অচেনা tool: {block['name']}", "is_error": True} try: result = tools[block["name"]](**block["input"]) except Exception as e: return {**base, "content": f"{type(e).__name__}: {e}", "is_error": True} return {**base, "content": str(result)} def run_agent(call_model, tools, user_message, max_steps=5): pass # একটা script করা "model": প্রথমে tool চায়, ফলাফল পেলে উত্তর দেয় def scripted_model(messages): last = messages[-1]["content"] if isinstance(last, str): return {"stop_reason": "tool_use", "content": [ {"type": "text", "text": "দাম দেখছি।"}, {"type": "tool_use", "id": "t1", "name": "get_price", "input": {"item": "চাল"}}, ]} return {"stop_reason": "end_turn", "content": [{"type": "text", "text": f"১ কেজি চালের দাম {last[0]['content']} টাকা।"}]} tools = {"get_price": lambda item: {"চাল": 75, "ডাল": 140}[item]} text, messages = run_agent(scripted_model, tools, "চালের দাম কত?") print(text) print(len(messages), "messages")

Hint দেখাওSolution দেখো

বাস্তবে কোথায় ব্যবহার হয়?

তোমার challenge-এর run_agent আর আসল API-র loop প্রায় হুবহু এক। শুধু call_model-এর জায়গায় আসল call বসে:

def call_model(messages):
    response = client.messages.create(
        model="claude-opus-5-5", max_tokens=1024, tools=tool_schemas, messages=messages,
    )
    return {"stop_reason": response.stop_reason, "content": [b.model_dump() for b in response.content]}

Anthropic SDK-তে একটা tool runner-ও আছে, যেটা এই loop নিজে থেকে চালায়। কিন্তু loop-টা একবার নিজে বানিয়ে বুঝে নিলে debug করা সহজ হয়, আর সীমা (max_steps), logging বা অনুমোদন যোগ করতে চাইলে কোথায় কী করতে হবে সেটা জানো।

Interview প্রশ্ন

• Beginner: Tool calling কী? Model কি নিজে function চালায়?
• Intermediate: একটা agent loop কীভাবে কাজ করে? tool_use_id কেন দরকার?
• Advanced: Tool-ব্যবহারকারী agent-এর নিরাপত্তা ঝুঁকি কী (prompt injection, অতিরিক্ত ক্ষমতা)? কীভাবে কমাবে?

এরপর কী?

🎉 LLM API module শেষ: প্রথম call, conversation, validation আর tool-calling agent। এগুলোই যেকোনো AI app-এর মূল উপাদান।

পরের module: AI app বানানো। Streaming (উত্তর শব্দে শব্দে দেখানো), backend-এ integration, আর একটা পূর্ণ AI app-এর architecture।