valkryhx/google_adk_agent / skills/programmatic-tool-calling
programmatic-tool-calling
Verified编程化工具调用指南。允许 Agent 编写并执行 Python 代码,从而能够在一个沙箱环境中动态调用其他工具,实现循环、批处理和复杂逻辑。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.2 KB |
| SKILL.md.metadata.json | config | 158 B |
| SKILL.md.resolved | other | 2.6 KB |
| assets/example_asset.txt | markdown | 865 B |
| references/api_reference.md | markdown | 976 B |
| scripts/example.py | script | 609 B |
| tools.py | script | 3.9 KB |
SKILL.md
View on GitHub---
name: programmatic-tool-calling
description: 编程化工具调用指南。允许 Agent 编写并执行 Python 代码,从而能够在一个沙箱环境中动态调用其他工具,实现循环、批处理和复杂逻辑。
---
# 编程化工具调用 (Programmatic Tool Calling) - ADK 增强版
本技能赋予了 Agent 编写并在沙箱中执行 Python 代码的能力。最强大的特性是:**可以在 Python 代码中动态调用 Agent 的其他工具**。
## 核心工具: `run_programmatic_task`
这是本技能提供的唯一工具。
### 何时使用 (Best Practice)
当遇到以下情况时,**必须**使用此工具,而不是尝试通过多轮对话来解决:
1. **批处理任务 (Batch Processing)**: 例如 "搜索 10 个不同的关键词并汇总结果"。如果分 10 次调用 `web_search`,会浪费大量 Token 和时间。
2. **数据聚合与处理 (Aggregation)**: 例如 "获取 A、B、C 三个文件,提取其中的数据,计算平均值,并画图"。
3. **复杂逻辑控制 (Control Flow)**: 需要使用循环 (`for`/`while`)、条件判断 (`if`/`else`) 或重试逻辑来控制工具调用。
4. **长输出处理**: 需要处理大量文本或数据,且中间过程不需要展示给用户。
### 何时不使用
- **简单直线性任务**: 如 "查询北京的天气"。直接调用 `web_search` 即可。
- **纯计算任务**: 如 "计算 1+1"。直接输出结果。
### 🚨 禁止使用的模式 (Forbidden Patterns)
**严禁使用 `bash` 工具来运行 Python 脚本以完成此类任务!**
- ❌ 错误:调用 `bash` 执行 `python -c "import requests..."`
- 原因: 无法访问 Agent 的工具链 (`call_tool` 不可用),无法复用 Session 状态,且难以处理异步逻辑。
- ✅ 正确: 直接调用 `run_programmatic_task` 工具,将代码作为参数传入。
---
## 编写代码指南
你编写的代码不仅是标准的 Python 代码,还运行在一个预配置的 `async` 环境中。
### 关键函数: `await call_tool(...)`
环境内置了一个特殊函数 `call_tool`,用于调用 Agent 已加载的其他工具。
```python
await call_tool(tool_name: str, **kwargs) -> Any
```
- **tool_name**: 工具的名称(字符串)。必须是 Agent 当前已加载的工具(如 `web_search`, `codebase_search`, `bash` 等)。
- **kwargs**: 传递给目标工具的参数。
### 可用库 (Pre-installed Libraries)
沙箱环境预装了以下数据科学和异步库:
- `pandas` (已导入为 `pd`)
- `matplotlib.pyplot` (已导入为 `plt`)
- `asyncio` (已导入为 `asyncio`)
- 标准库 (`json`, `os`, `re`, `math` 等)
---
## 示例 (Examples)
### 示例 1: 批量搜索并汇总 (Batch Search)
**任务**: "搜索 Python, JavaScript, Go 的最新特性,并统计结果长度。"
```python
# 注意:代码无需包裹在 def 中,但建议使用 main 函数保持整洁
# 必须使用 await 调用 call_tool
async def main():
queries = [
"Python 3.13 new features",
"JavaScript ES2024 features",
"Go 1.22 new features"
]
results = {}
print(f"开始批量搜索 {len(queries)} 个主题...")
for q in queries:
print(f"正在搜索: {q}")
# 调用 web_search 工具 (假设该工具已加载)
# 如果不确定工具名,可以使用 bash 调用脚本
try:
# 方式 A: 直接调用工具 (推荐)
output = await call_tool('web_search', query=q)
except:
# 方式 B:降级使用 bash
output = await call_tool('bash', command=f'echo "Search failed for {q}"')
results[q] = len(str(output))
print(f" -> 结果长度: {len(str(output))}")
print("\n统计结果:")
print(pd.Series(results))
# 启动执行
await main()
```
### 示例 2: 数据处理与绘图 (Data Analysis)
**任务**: "生成一组随机数据并画图。"
```python
import numpy as np
# 生成数据
x = np.linspace(0, 10, 100)
y = np.sin(x)
# 绘图
plt.figure(figsize=(10, 6))
plt.plot(x, y, label='Sin(x)')
plt.title('Demo Plot')
plt.grid(True)
# 这一步不是必须的,但在某些环境中可以保存图片
plt.savefig('sine_wave.png')
print("图表已生成: sine_wave.png")
# 在 pandas 中处理
df = pd.DataFrame({'x': x, 'y': y})
print("\n数据摘要:")
print(df.describe())
```
---
## ⚠️ 重要注意事项 (Critical Notes)
1. **必须使用 `await`**: 调用 `call_tool` 时必须加 `await`,否则会返回协程对象而不是结果。
2. **打印结果**: 工具会捕获标准输出 (`stdout`) 作为返回值。**如果你不 `print()`,你将看不到任何结果**。
3. **不要使用 `asyncio.run()`**: 代码是在一个已经在运行的事件循环中执行的。使用 `asyncio.run()` 会报错。直接 `await` 你的异步函数即可。
4. **工具名准确性**: 调用 `call_tool` 前,请确认 Agent 加载了哪些工具。如果不确定,可以先调用 `get_tools` 或查看系统提示。
5. **防止超时**: 如果任务非常耗时(超过 5 分钟),请分批执行或申请更多时间。
6. **UI 交互**: 生成代码需要时间。在调用此工具前,**请先输出一段思考文本**(如 "正在编写脚本进行批量处理..."),以免用户觉得界面卡死。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |