{"id":"3d734d39-ecff-4050-a29d-be48da5dd059","shortId":"nfDhRP","kind":"skill","title":"programmatic-tool-calling","tagline":"编程化工具调用指南。允许 Agent 编写并执行 Python 代码，从而能够在一个沙箱环境中动态调用其他工具，实现循环、批处理和复杂逻辑。","description":"# 编程化工具调用 (Programmatic Tool Calling) - ADK 增强版\n\n本技能赋予了 Agent 编写并在沙箱中执行 Python 代码的能力。最强大的特性是：**可以在 Python 代码中动态调用 Agent 的其他工具**。\n\n## 核心工具: `run_programmatic_task`\n\n这是本技能提供的唯一工具。\n\n### 何时使用 (Best Practice)\n\n当遇到以下情况时，**必须**使用此工具，而不是尝试通过多轮对话来解决：\n\n1.  **批处理任务 (Batch Processing)**: 例如 \"搜索 10 个不同的关键词并汇总结果\"。如果分 10 次调用 `web_search`，会浪费大量 Token 和时间。\n2.  **数据聚合与处理 (Aggregation)**: 例如 \"获取 A、B、C 三个文件，提取其中的数据，计算平均值，并画图\"。\n3.  **复杂逻辑控制 (Control Flow)**: 需要使用循环 (`for`/`while`)、条件判断 (`if`/`else`) 或重试逻辑来控制工具调用。\n4.  **长输出处理**: 需要处理大量文本或数据，且中间过程不需要展示给用户。\n\n### 何时不使用\n\n- **简单直线性任务**: 如 \"查询北京的天气\"。直接调用 `web_search` 即可。\n- **纯计算任务**: 如 \"计算 1+1\"。直接输出结果。\n\n### 🚨 禁止使用的模式 (Forbidden Patterns)\n\n**严禁使用 `bash` 工具来运行 Python 脚本以完成此类任务！**\n- ❌ 错误:调用 `bash` 执行 `python -c \"import requests...\"`\n  - 原因: 无法访问 Agent 的工具链 (`call_tool` 不可用)，无法复用 Session 状态，且难以处理异步逻辑。\n- ✅ 正确: 直接调用 `run_programmatic_task` 工具，将代码作为参数传入。\n\n---\n\n## 编写代码指南\n\n你编写的代码不仅是标准的 Python 代码，还运行在一个预配置的 `async` 环境中。\n\n### 关键函数: `await call_tool(...)`\n\n环境内置了一个特殊函数 `call_tool`，用于调用 Agent 已加载的其他工具。\n\n```python\nawait call_tool(tool_name: str, **kwargs) -> Any\n```\n\n- **tool_name**: 工具的名称（字符串）。必须是 Agent 当前已加载的工具（如 `web_search`, `codebase_search`, `bash` 等）。\n- **kwargs**: 传递给目标工具的参数。\n\n### 可用库 (Pre-installed Libraries)\n\n沙箱环境预装了以下数据科学和异步库：\n- `pandas` (已导入为 `pd`)\n- `matplotlib.pyplot` (已导入为 `plt`)\n- `asyncio` (已导入为 `asyncio`)\n- 标准库 (`json`, `os`, `re`, `math` 等)\n\n---\n\n## 示例 (Examples)\n\n### 示例 1: 批量搜索并汇总 (Batch Search)\n\n**任务**: \"搜索 Python, JavaScript, Go 的最新特性，并统计结果长度。\"\n\n```python\n# 注意：代码无需包裹在 def 中，但建议使用 main 函数保持整洁\n# 必须使用 await 调用 call_tool\n\nasync def main():\n    queries = [\n        \"Python 3.13 new features\",\n        \"JavaScript ES2024 features\",\n        \"Go 1.22 new features\"\n    ]\n    \n    results = {}\n    print(f\"开始批量搜索 {len(queries)} 个主题...\")\n    \n    for q in queries:\n        print(f\"正在搜索: {q}\")\n        # 调用 web_search 工具 (假设该工具已加载)\n        # 如果不确定工具名，可以使用 bash 调用脚本\n        try:\n            # 方式 A: 直接调用工具 (推荐)\n            output = await call_tool('web_search', query=q)\n        except:\n            # 方式 B:降级使用 bash\n            output = await call_tool('bash', command=f'echo \"Search failed for {q}\"')\n            \n        results[q] = len(str(output))\n        print(f\"  -> 结果长度: {len(str(output))}\")\n\n    print(\"\\n统计结果:\")\n    print(pd.Series(results))\n\n# 启动执行\nawait main()\n```\n\n### 示例 2: 数据处理与绘图 (Data Analysis)\n\n**任务**: \"生成一组随机数据并画图。\"\n\n```python\nimport numpy as np\n\n# 生成数据\nx = np.linspace(0, 10, 100)\ny = np.sin(x)\n\n# 绘图\nplt.figure(figsize=(10, 6))\nplt.plot(x, y, label='Sin(x)')\nplt.title('Demo Plot')\nplt.grid(True)\n\n# 这一步不是必须的，但在某些环境中可以保存图片\nplt.savefig('sine_wave.png')\nprint(\"图表已生成: sine_wave.png\")\n\n# 在 pandas 中处理\ndf = pd.DataFrame({'x': x, 'y': y})\nprint(\"\\n数据摘要:\")\nprint(df.describe())\n```\n\n---\n\n## ⚠️ 重要注意事项 (Critical Notes)\n\n1.  **必须使用 `await`**: 调用 `call_tool` 时必须加 `await`，否则会返回协程对象而不是结果。\n2.  **打印结果**: 工具会捕获标准输出 (`stdout`) 作为返回值。**如果你不 `print()`，你将看不到任何结果**。\n3.  **不要使用 `asyncio.run()`**: 代码是在一个已经在运行的事件循环中执行的。使用 `asyncio.run()` 会报错。直接 `await` 你的异步函数即可。\n4.  **工具名准确性**: 调用 `call_tool` 前，请确认 Agent 加载了哪些工具。如果不确定，可以先调用 `get_tools` 或查看系统提示。\n5.  **防止超时**: 如果任务非常耗时（超过 5 分钟），请分批执行或申请更多时间。\n6.  **UI 交互**: 生成代码需要时间。在调用此工具前，**请先输出一段思考文本**（如 \"正在编写脚本进行批量处理...\"），以免用户觉得界面卡死。","tags":["programmatic","tool","calling","google","adk","agent","valkryhx","agent-development","agent-skills","agent-swarm","agent-team","agentic-ai"],"capabilities":["skill","source-valkryhx","skill-programmatic-tool-calling","topic-agent-development","topic-agent-skills","topic-agent-swarm","topic-agent-team","topic-agentic-ai","topic-dynamic-skills","topic-google-adk","topic-vibe-coding"],"categories":["google_adk_agent"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/valkryhx/google_adk_agent/programmatic-tool-calling","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add valkryhx/google_adk_agent","source_repo":"https://github.com/valkryhx/google_adk_agent","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 6 github stars · SKILL.md body (3,223 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:45.809Z","embedding":null,"createdAt":"2026-05-18T13:22:14.425Z","updatedAt":"2026-05-18T19:14:45.809Z","lastSeenAt":"2026-05-18T19:14:45.809Z","tsv":"'+1':98 '0':327 '1':43,97,200,372 '1.22':236 '10':49,52,328,336 '100':329 '2':59,313,381 '3':71,389 '3.13':229 '4':82,399 '5':413,417 '6':337,420 'adk':18 'agent':7,21,29,118,149,165,406 'aggreg':61 'analysi':316 'async':139,224 'asyncio':188,190 'asyncio.run':391,394 'await':142,152,220,269,282,310,374,379,397 'b':65,278 'bash':104,110,172,261,280,285 'batch':45,202 'best':37 'c':66,113 'call':4,17,120,143,146,153,222,270,283,376,402 'codebas':170 'command':286 'control':73 'critic':370 'data':315 'def':214,225 'demo':345 'df':359 'df.describe':368 'echo':288 'els':80 'es2024':233 'exampl':198 'except':276 'f':241,251,287,299 'fail':290 'featur':231,234,238 'figsiz':335 'flow':74 'forbidden':101 'get':410 'go':208,235 'import':114,320 'instal':179 'javascript':207,232 'json':192 'kwarg':158,174 'label':341 'len':243,295,301 'librari':180 'main':217,226,311 'math':195 'matplotlib.pyplot':185 'name':156,161 'new':230,237 'note':371 'np':323 'np.linspace':326 'np.sin':331 'numpi':321 'n数据摘要':366 'n统计结果':305 'os':193 'output':268,281,297,303 'panda':182,357 'pattern':102 'pd':184 'pd.dataframe':360 'pd.series':307 'plot':346 'plt':187 'plt.figure':334 'plt.grid':347 'plt.plot':338 'plt.savefig':351 'plt.title':344 'practic':38 'pre':178 'pre-instal':177 'print':240,250,298,304,306,353,365,367,387 'process':46 'programmat':2,15,33,130 'programmatic-tool-cal':1 'python':9,23,27,106,112,136,151,206,211,228,319 'q':247,253,275,292,294 'queri':227,244,249,274 're':194 'request':115 'result':239,293,308 'run':32,129 'search':55,92,169,171,203,256,273,289 'session':124 'sin':342 'sine_wave.png':352,355 'skill' 'skill-programmatic-tool-calling' 'source-valkryhx' 'stdout':384 'str':157,296,302 'task':34,131 'token':57 'tool':3,16,121,144,147,154,155,160,223,271,284,377,403,411 'topic-agent-development' 'topic-agent-skills' 'topic-agent-swarm' 'topic-agent-team' 'topic-agentic-ai' 'topic-dynamic-skills' 'topic-google-adk' 'topic-vibe-coding' 'tri':263 'true':348 'ui':421 'web':54,91,168,255,272 'x':325,332,339,343,361,362 'y':330,340,363,364 '三个文件':67 '不可用':122 '不要使用':390 '且中间过程不需要展示给用户':85 '且难以处理异步逻辑':126 '严禁使用':103 '个不同的关键词并汇总结果':50 '个主题':245 '中':215 '中处理':358 '交互':422 '从而能够在一个沙箱环境中动态调用其他工具':11 '代码':10,137 '代码中动态调用':28 '代码无需包裹在':213 '代码是在一个已经在运行的事件循环中执行的':392 '代码的能力':24 '以免用户觉得界面卡死':428 '任务':204,317 '会报错':395 '会浪费大量':56 '传递给目标工具的参数':175 '但在某些环境中可以保存图片':350 '但建议使用':216 '何时不使用':86 '何时使用':36 '作为返回值':385 '你将看不到任何结果':388 '你的异步函数即可':398 '你编写的代码不仅是标准的':135 '使用':393 '使用此工具':41 '例如':47,62 '假设该工具已加载':258 '允许':6 '关键函数':141 '函数保持整洁':218 '分钟':418 '前':404 '加载了哪些工具':407 '即可':93 '原因':116 '可以使用':260 '可以先调用':409 '可以在':26 '可用库':176 '否则会返回协程对象而不是结果':380 '启动执行':309 '和时间':58 '图表已生成':354 '在':356 '在调用此工具前':424 '增强版':19 '复杂逻辑控制':72 '如':88,95,167,426 '如果不确定':408 '如果不确定工具名':259 '如果任务非常耗时':415 '如果你不':386 '如果分':51 '字符串':163 '实现循环':12 '将代码作为参数传入':133 '工具':132,257 '工具会捕获标准输出':383 '工具名准确性':400 '工具来运行':105 '工具的名称':162 '已加载的其他工具':150 '已导入为':183,186,189 '并画图':70 '并统计结果长度':210 '开始批量搜索':242 '当前已加载的工具':166 '当遇到以下情况时':39 '必须':40 '必须使用':219,373 '必须是':164 '或查看系统提示':412 '或重试逻辑来控制工具调用':81 '打印结果':382 '执行':111 '批处理任务':44 '批处理和复杂逻辑':13 '批量搜索并汇总':201 '推荐':267 '提取其中的数据':68 '搜索':48,205 '数据处理与绘图':314 '数据聚合与处理':60 '方式':264,277 '无法复用':123 '无法访问':117 '时必须加':378 '最强大的特性是':25 '本技能赋予了':20 '条件判断':78 '查询北京的天气':89 '标准库':191 '核心工具':31 '次调用':53 '正在搜索':252 '正在编写脚本进行批量处理':427 '正确':127 '沙箱环境预装了以下数据科学和异步库':181 '注意':212 '状态':125 '环境中':140 '环境内置了一个特殊函数':145 '生成一组随机数据并画图':318 '生成代码需要时间':423 '生成数据':324 '用于调用':148 '的其他工具':30 '的工具链':119 '的最新特性':209 '直接':396 '直接调用':90,128 '直接调用工具':266 '直接输出结果':99 '示例':197,199,312 '禁止使用的模式':100 '等':173,196 '简单直线性任务':87 '纯计算任务':94 '结果长度':300 '绘图':333 '编写代码指南':134 '编写并在沙箱中执行':22 '编写并执行':8 '编程化工具调用':14 '编程化工具调用指南':5 '而不是尝试通过多轮对话来解决':42 '脚本以完成此类任务':107 '获取':63 '计算':96 '计算平均值':69 '请先输出一段思考文本':425 '请分批执行或申请更多时间':419 '请确认':405 '调用':109,221,254,375,401 '调用脚本':262 '超过':416 '还运行在一个预配置的':138 '这一步不是必须的':349 '这是本技能提供的唯一工具':35 '重要注意事项':369 '错误':108 '长输出处理':83 '防止超时':414 '降级使用':279 '需要使用循环':75 '需要处理大量文本或数据':84","prices":[{"id":"d0e54feb-a306-45b7-b349-33d57f1093b7","listingId":"3d734d39-ecff-4050-a29d-be48da5dd059","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"valkryhx","category":"google_adk_agent","install_from":"skills.sh"},"createdAt":"2026-05-18T13:22:14.425Z"}],"sources":[{"listingId":"3d734d39-ecff-4050-a29d-be48da5dd059","source":"github","sourceId":"valkryhx/google_adk_agent/programmatic-tool-calling","sourceUrl":"https://github.com/valkryhx/google_adk_agent/tree/main/skills/programmatic-tool-calling","isPrimary":false,"firstSeenAt":"2026-05-18T13:22:14.425Z","lastSeenAt":"2026-05-18T19:14:45.809Z"}],"details":{"listingId":"3d734d39-ecff-4050-a29d-be48da5dd059","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"valkryhx","slug":"programmatic-tool-calling","github":{"repo":"valkryhx/google_adk_agent","stars":6,"topics":["agent-development","agent-skills","agent-swarm","agent-team","agentic-ai","dynamic-skills","google-adk","vibe-coding"],"license":null,"html_url":"https://github.com/valkryhx/google_adk_agent","pushed_at":"2026-04-23T07:34:09Z","description":"a startup but not simple agent demo using  google adk.","skill_md_sha":"bde84eecaf1e9b800697c3ffe8f65326fcb34ef6","skill_md_path":"skills/programmatic-tool-calling/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/valkryhx/google_adk_agent/tree/main/skills/programmatic-tool-calling"},"layout":"multi","source":"github","category":"google_adk_agent","frontmatter":{"name":"programmatic-tool-calling","description":"编程化工具调用指南。允许 Agent 编写并执行 Python 代码，从而能够在一个沙箱环境中动态调用其他工具，实现循环、批处理和复杂逻辑。"},"skills_sh_url":"https://skills.sh/valkryhx/google_adk_agent/programmatic-tool-calling"},"updatedAt":"2026-05-18T19:14:45.809Z"}}