Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions docs/content/docs/framework/tools/builtin.en.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,17 @@ Built-in tools depend on Volcengine services. Enable the corresponding service a
| `image_edit` | [Edit images](https://www.volcengine.com/docs/82379/1541523) (image-to-image) | `from veadk.tools.builtin_tools.image_edit import image_edit` |
| `video_generate` | [Generate videos](https://www.volcengine.com/docs/82379/1520757) from text | `from veadk.tools.builtin_tools.video_generate import video_generate` |
| `text_to_speech` | Text-to-speech (TTS) | `from veadk.tools.builtin_tools.tts import text_to_speech` |
| `speech_to_text` | Speech recognition (ASR) for local files or public audio URLs | `from veadk.tools.builtin_tools.speech_to_text import speech_to_text` |
| `http_request` | Generic HTTP requests with SSRF guards and a response-size cap | `from veadk.tools.builtin_tools.http_request import http_request` |
| `document_parse` | Extract text from PDF / Word / Excel / CSV / HTML documents | `from veadk.tools.builtin_tools.document_parse import document_parse` |
| `doc_generate` | Generate Word / Excel / CSV / Markdown documents | `from veadk.tools.builtin_tools.doc_generate import doc_generate` |
| `mindmap_generate` | Generate a mind map (Mermaid + SVG) from a Markdown outline | `from veadk.tools.builtin_tools.mindmap_generate import mindmap_generate` |
| `qrcode_generate` | Generate a QR code PNG | `from veadk.tools.builtin_tools.qrcode_generate import qrcode_generate` |
| `image_transform` | Resize, crop, rotate, flip, and convert images | `from veadk.tools.builtin_tools.image_transform import image_transform` |
| `image_understand` | Understand images with the configured model | `from veadk.tools.builtin_tools.image_understand import image_understand` |
| `ocr` | Extract image text with the configured model | `from veadk.tools.builtin_tools.ocr import ocr` |
| `calculator` | Safe arithmetic evaluation | `from veadk.tools.builtin_tools.calculator import calculator` |
| `datetime` | Parse, format, convert, and calculate dates and times | `from veadk.tools.builtin_tools.datetime_tool import datetime` |
| `run_code` | Execute code in an AgentKit sandbox | `from veadk.tools.builtin_tools.run_code import run_code` |
| `execute_skills` | Run an `agent.py` workflow in a prebuilt skills sandbox | `from veadk.tools.builtin_tools.execute_skills import execute_skills` |
| `coding` | Run a code-generation workflow in a prebuilt OpenCode sandbox | `from veadk.tools.builtin_tools.coding import coding` |
Expand Down Expand Up @@ -469,6 +480,40 @@ Environment variables:
- `TOOL_VESPEECH_SPEAKER`: voice, defaults to `zh_female_vv_uranus_bigtts`
- `TOOL_VESPEECH_AUDIO_OUTPUT_PATH`: audio output directory, defaults to the system temp directory

## General-purpose tools

These tools cover general data processing, office documents, and multimodal work without binding to one business service. None require extra credentials except `speech_to_text`; `image_understand` and `ocr` reuse the current agent's model configuration.

```python
from veadk import Agent
from veadk.tools.builtin_tools.calculator import calculator
from veadk.tools.builtin_tools.datetime_tool import datetime
from veadk.tools.builtin_tools.http_request import http_request

agent = Agent(
name="utility_agent",
instruction="Use the available tools to answer precisely.",
tools=[calculator, datetime, http_request],
)
```

- `http_request(url, method="GET", headers=None, params=None, json_body=None, body=None, timeout=30, max_bytes=5_000_000, follow_redirects=False)`: make an HTTP(S) request. Only http/https is allowed; private, loopback, link-local, and cloud-metadata addresses are rejected. Redirects are off by default; when enabled, every hop is revalidated and at most three hops are followed. Bodies larger than `max_bytes` are truncated with `truncated: true`. A header value of `env:NAME` reads a secret from the environment so it never enters model arguments. Credentials (`Authorization`, `Cookie`, `Proxy-Authorization`, and every `env:`-resolved header) are dropped when a redirect changes origin or downgrades to http; a same-host http→https upgrade keeps them. Set `TOOL_HTTP_ALLOWLIST=api.example.com,cdn.example.com` to restrict target hosts.
- `document_parse(source, format=None, max_chars=200000)`: parse a local file or public URL as pdf, docx, xlsx, csv, txt, md, json, or html. Scanned PDFs return `needs_ocr: true`; pass them to `ocr`. A local file larger than 20,000,000 bytes fails instead of being read into memory; a URL download larger than that is truncated and flagged in `metadata.download_truncated`.
- `doc_generate(format, title, content="", sheets=None, rows=None, filename=None)`: generate docx, xlsx, csv, or md and save it as an artifact. PDF generation is not supported. String cells starting with `=`, `+`, `-`, or `@` are written as text (CSV adds a `'` prefix) to prevent formula injection, and the result sets `truncated: true` when sheet, row, or column caps cut the input.
- `mindmap_generate(title, markdown, filename=None)`: build Mermaid text and an SVG from headings and indented bullets; no Node.js is required.
- `qrcode_generate(content, filename="qrcode.png", box_size=10, border=4, fill_color="black", back_color="white")`: generate a PNG QR code. Decoding is not supported.
- `image_transform(source, operations, output_format=None, quality=90, filename=None)`: apply `resize`, `crop`, `rotate`, `flip`, `thumbnail`, `grayscale`, and `convert` in order and output png, jpeg, or webp. Local paths and public URLs are accepted. The output canvas, including the expanded size after `rotate`, may not exceed 40,000,000 pixels.
- `image_understand(images, prompt="Describe the image in detail.", model_name=None)`: understand one to eight local or public images; `model_name` overrides the vision model. Local images are capped at 20,000,000 bytes each and 40,000,000 bytes total. Public URLs pass the same SSRF check as `http_request` before they are sent to the model provider.
- `ocr(image, language="auto", model_name=None)`: extract text from an image. `language` is a hint only; `auto` adds no constraint. Public URLs are SSRF-checked as well; local images carry the same per-image and total size caps.
- `speech_to_text(audio, timeout=300)`: call Volcengine flash ASR for wav, mp3, ogg, or opus audio up to 100 MB, from a local path or a public URL.
- `calculator(expression, precision=10)`: arithmetic, powers, modulo, and a small function set such as `sqrt`, `log`, and `sin`. Arbitrary Python is rejected.
- `datetime(action, value=None, value2=None, timezone=None, target_timezone=None, format=None, amount=None, unit=None)`: `action` is `now`, `parse`, `format`, `convert`, `diff`, or `add`; timezones use IANA names.

Environment variables:

- `TOOL_SPEECH_TO_TEXT_API_KEY`: ASR API key; falls back to `TOOL_VESPEECH_API_KEY`. Used only by `speech_to_text`.
- `TOOL_HTTP_ALLOWLIST`: optional comma-separated host allowlist, used only by `http_request`.

## Code sandboxes

VeADK provides a set of tools that run tasks remotely in an [AgentKit sandbox](https://console.volcengine.com/agentkit):
Expand Down
45 changes: 45 additions & 0 deletions docs/content/docs/framework/tools/builtin.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,17 @@ agent = Agent(tools=[web_search])
| `image_edit` | [编辑图片](https://www.volcengine.com/docs/82379/1541523)(图生图) | `from veadk.tools.builtin_tools.image_edit import image_edit` |
| `video_generate` | 根据文本描述[生成视频](https://www.volcengine.com/docs/82379/1520757) | `from veadk.tools.builtin_tools.video_generate import video_generate` |
| `text_to_speech` | 语音合成(TTS) | `from veadk.tools.builtin_tools.tts import text_to_speech` |
| `speech_to_text` | 语音识别(ASR),支持本地文件或公网音频 URL | `from veadk.tools.builtin_tools.speech_to_text import speech_to_text` |
| `http_request` | 带 SSRF 防护与体积上限的通用 HTTP 请求 | `from veadk.tools.builtin_tools.http_request import http_request` |
| `document_parse` | 解析 PDF / Word / Excel / CSV / HTML 等文档文本 | `from veadk.tools.builtin_tools.document_parse import document_parse` |
| `doc_generate` | 生成 Word / Excel / CSV / Markdown 文档 | `from veadk.tools.builtin_tools.doc_generate import doc_generate` |
| `mindmap_generate` | 由 Markdown 大纲生成思维导图(Mermaid + SVG) | `from veadk.tools.builtin_tools.mindmap_generate import mindmap_generate` |
| `qrcode_generate` | 生成二维码 PNG | `from veadk.tools.builtin_tools.qrcode_generate import qrcode_generate` |
| `image_transform` | 图片缩放、裁剪、旋转、翻转、格式转换 | `from veadk.tools.builtin_tools.image_transform import image_transform` |
| `image_understand` | 复用当前模型配置理解图片 | `from veadk.tools.builtin_tools.image_understand import image_understand` |
| `ocr` | 复用当前模型配置识别图片文字 | `from veadk.tools.builtin_tools.ocr import ocr` |
| `calculator` | 安全的算术表达式计算 | `from veadk.tools.builtin_tools.calculator import calculator` |
| `datetime` | 日期时间解析、格式化、时区转换与计算 | `from veadk.tools.builtin_tools.datetime_tool import datetime` |
| `run_code` | 在 AgentKit 沙箱中执行代码 | `from veadk.tools.builtin_tools.run_code import run_code` |
| `execute_skills` | 在预制技能沙箱中远程执行 `agent.py` 工作流 | `from veadk.tools.builtin_tools.execute_skills import execute_skills` |
| `coding` | 在预制 OpenCode 沙箱中执行代码生成工作流 | `from veadk.tools.builtin_tools.coding import coding` |
Expand Down Expand Up @@ -466,6 +477,40 @@ if __name__ == "__main__":
- `TOOL_VESPEECH_SPEAKER`:音色,默认为 `zh_female_vv_uranus_bigtts`
- `TOOL_VESPEECH_AUDIO_OUTPUT_PATH`:音频输出目录,默认为系统临时目录

## 通用工具

以下工具面向通用数据处理、办公文档与多模态场景,不绑定单一业务服务。除 `speech_to_text` 外均无需额外凭证;`image_understand`、`ocr` 直接复用当前 Agent 的模型配置。

```python
from veadk import Agent
from veadk.tools.builtin_tools.calculator import calculator
from veadk.tools.builtin_tools.datetime_tool import datetime
from veadk.tools.builtin_tools.http_request import http_request

agent = Agent(
name="utility_agent",
instruction="Use the available tools to answer precisely.",
tools=[calculator, datetime, http_request],
)
```

- `http_request(url, method="GET", headers=None, params=None, json_body=None, body=None, timeout=30, max_bytes=5_000_000, follow_redirects=False)`:发起 HTTP(S) 请求。仅允许 http/https,默认拒绝内网、回环、链路本地和云元数据地址;重定向默认关闭,开启后每一跳都会重新校验,最多 3 跳;响应体超过 `max_bytes` 时截断并返回 `truncated: true`。请求头值写成 `env:NAME` 可从环境变量读取密钥,避免密钥进入模型参数。跨域重定向或 https→http 降级时会自动丢弃 `Authorization`、`Cookie`、`Proxy-Authorization` 以及所有从 `env:` 解析出的请求头(同域 http→https 升级除外),避免凭证泄露给重定向目标。可用 `TOOL_HTTP_ALLOWLIST=api.example.com,cdn.example.com` 限定目标域名。
- `document_parse(source, format=None, max_chars=200000)`:解析本地文件或公网 URL,支持 pdf、docx、xlsx、csv、txt、md、json、html。扫描版 PDF 返回 `needs_ocr: true`,可继续调用 `ocr`。本地文件超过 20,000,000 字节直接报错;URL 下载超过该上限会截断,并在 `metadata.download_truncated` 中标记。
- `doc_generate(format, title, content="", sheets=None, rows=None, filename=None)`:生成 docx、xlsx、csv 或 md 并保存为 artifact;不支持 PDF。以 `=`、`+`、`-`、`@` 开头的字符串单元格会按文本写入(CSV 加 `'` 前缀),防止公式注入;因 sheet/行列上限被截断时返回 `truncated: true`。
- `mindmap_generate(title, markdown, filename=None)`:按标题层级和缩进列表生成 Mermaid 文本与 SVG,无需 Node.js。
- `qrcode_generate(content, filename="qrcode.png", box_size=10, border=4, fill_color="black", back_color="white")`:生成 PNG 二维码;仅支持生成,不支持解码。
- `image_transform(source, operations, output_format=None, quality=90, filename=None)`:按顺序执行 `resize`、`crop`、`rotate`、`flip`、`thumbnail`、`grayscale`、`convert`,输出 png / jpeg / webp;本地路径和公网 URL 均可。输出画布(含 `rotate` 扩展后的尺寸)不得超过 40,000,000 像素。
- `image_understand(images, prompt="Describe the image in detail.", model_name=None)`:理解 1–8 张图片,支持本地路径或公网 URL,可传 `model_name` 覆盖视觉模型。本地图片单张上限 20,000,000 字节、合计上限 40,000,000 字节。公网 URL 会先经过与 `http_request` 相同的 SSRF 校验,再交给模型服务。
- `ocr(image, language="auto", model_name=None)`:提取图片文字;`language` 仅作为提示,`auto` 时不额外约束。公网 URL 同样先做 SSRF 校验;本地图片适用相同的单张与合计大小限制。
- `speech_to_text(audio, timeout=300)`:调用火山引擎录音文件识别极速版,支持 wav / mp3 / ogg / opus,单文件不超过 100 MB,也支持公网音频 URL。
- `calculator(expression, precision=10)`:支持四则运算、幂、取模和 `sqrt` / `log` / `sin` 等少量函数,拒绝任意 Python 代码。
- `datetime(action, value=None, value2=None, timezone=None, target_timezone=None, format=None, amount=None, unit=None)`:`action` 取 `now` / `parse` / `format` / `convert` / `diff` / `add`,时区使用 IANA 名称。

环境变量:

- `TOOL_SPEECH_TO_TEXT_API_KEY`:语音识别 API Key;未设置时回退读取 `TOOL_VESPEECH_API_KEY`。仅 `speech_to_text` 需要。
- `TOOL_HTTP_ALLOWLIST`:可选,逗号分隔的允许域名列表,仅 `http_request` 使用。

## 代码沙箱

VeADK 提供一组在 [AgentKit 沙箱](https://console.volcengine.com/agentkit)中远程执行任务的工具:
Expand Down
Loading
Loading