> ## 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.