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

# 工具

> 定义经过验证的本地工具、手动工具和可报告进度的工具。

当智能体需要读取应用数据、调用内部服务或执行操作时，请使用工具。Agent SDK 会验证工具边界，并在应用内运行工具代码。

## 定义本地工具

`defineTool()` 接受描述、可选的 JSON 参数、运行时验证器、超时时间以及 `execute()` 函数。

```typescript theme={null}
import { defineTool } from "@phaseo/agent-sdk";

const fetchTicket = defineTool({
  id: "fetch-ticket",
  description: "Load one internal support ticket.",
  parameters: {
    type: "object",
    properties: {
      ticketId: { type: "string" },
    },
    required: ["ticketId"],
    additionalProperties: false,
  },
  timeoutMs: 3_000,
  async execute(input: { ticketId: string }, context) {
    const response = await fetch(
      `https://internal.example/tickets/${input.ticketId}`,
      { signal: context.signal },
    );

    return response.json();
  },
});
```

超时后，运行时会中止 `context.signal`，将运行标记为失败，并重新抛出超时错误。

Schema 可以是函数，也可以是公开 `parse()` 或 `safeParse()` 的对象。无效的模型参数和工具结果会在越过工具边界之前报错。

## 在应用中执行工作

如果由应用而非 SDK 进程执行工作，请设置 `execute: false`。在 `toolOutputs` 中提供结果，即可继续已暂停的运行。

对于交互式工具，请从 `onToolCalled` 返回 `null`。继续运行后，`onResponseReceived` 可以验证或转换传入的响应。

## 报告进度

异步生成器可以先返回中间结果，最后再返回一个最终结果：

```typescript theme={null}
const indexRepository = defineTool({
  id: "index-repository",
  async *execute(input: { path: string }) {
    yield { phase: "scan" };
    yield { phase: "embed" };
    return { indexed: 248 };
  },
});
```

可以通过 `tool.preliminary_result` 事件和步骤的 `preliminaryResults` 获取进度。

## 并发运行互不依赖的工具

如果一个模型轮次可以安全地调用多个互不依赖的工具，请设置并发上限：

```typescript theme={null}
const agent = createAgent({
  id: "research-agent",
  toolExecution: {
    toolConcurrency: 3,
  },
  tools: [fetchDocs, fetchStatus, fetchIncidents],
});
```

即使本地执行存在重叠，运行时仍会保留工具结果消息的顺序。

## 相关指南

* [暂停、批准并继续运行](./agent-sdk-state-and-approval.mdx)
* [流式传输智能体结果](./agent-sdk-streaming.mdx)
* [并发调用多个本地工具](../../cookbook/agent-sdk-parallel-tools.mdx)


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