> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 智能體循環與工具執行

> Theo 如何在迭代循環中執行多步驟工具調用。

當有工具可用時（來自技能、連接器或內聯定義），Theo 會進入一個迭代式智能體循環：模型可以進行推理、調用工具、觀察結果，並持續進行直到任務完成。

## 工作原理

```
Iteration 0: LLM reads prompt + system prompt + tool definitions
             → Responds with text AND a tool call:
               {"tool": "check_stock", "arguments": {"sku": "ABC123"}}
             → Theo executes the tool, gets result

Iteration 1: LLM reads the tool result + previous context
             → Responds with text (no more tool calls)
             → Final response returned
```

## 配置

你可以通過 `max_iterations` 參數控制每個請求的智能體循環最多運行多少輪迭代：

```typescript theme={null}
const res = await theo.complete({
  prompt: "Check stock and reorder if low",
  tools: [/* ... */],
  max_iterations: 4,  // Limit to 4 tool calls
});
```

## 工具來源

工具可以來自三種來源，它們會被合併為一個統一的可用工具集：

1. **技能工具** — 定義在已安裝或按請求提供的技能清單中
2. **內聯工具** — 通過補全請求中的 `tools[]` 直接傳入
3. **內置工具** — Theo 的系統工具（網頁搜索、代碼執行等）

## 內聯工具示例

```typescript theme={null}
const res = await theo.complete({
  prompt: "Look up the customer and update their email",
  tools: [
    {
      name: "lookup_customer",
      description: "Search CRM for a customer by name or ID",
      input_schema: {
        type: "object",
        properties: {
          query: { type: "string" },
        },
        required: ["query"],
      },
    },
    {
      name: "update_customer",
      description: "Update a customer field",
      input_schema: {
        type: "object",
        properties: {
          customer_id: { type: "string" },
          field: { type: "string" },
          value: { type: "string" },
        },
        required: ["customer_id", "field", "value"],
      },
    },
  ],
});
```

## 響應中的工具執行情況

響應中的 `tools_used` 數組會顯示哪些工具被調用過：

```json theme={null}
{
  "tools_used": [
    { "name": "lookup_customer", "status": "success" },
    { "name": "update_customer", "status": "success" }
  ]
}
```

## 護欄

* **迭代次數限制** — 防止循環失控（可按請求配置）
* **額度檢查點** — 每輪迭代前都會校驗餘額是否充足
* **超時** — 可通過 SDK 的 `timeoutMs` 按請求配置
* 如果引擎達到迭代次數上限，Theo 會強制生成一個最終的綜合回覆


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.