Skip to content

valkryhx/google_adk_agent / skills/programmatic-tool-calling

programmatic-tool-calling

Verified

编程化工具调用指南。允许 Agent 编写并执行 Python 代码,从而能够在一个沙箱环境中动态调用其他工具,实现循环、批处理和复杂逻辑。

FileKindSize
SKILL.mdskill md5.2 KB
SKILL.md.metadata.jsonconfig158 B
SKILL.md.resolvedother2.6 KB
assets/example_asset.txtmarkdown865 B
references/api_reference.mdmarkdown976 B
scripts/example.pyscript609 B
tools.pyscript3.9 KB

SKILL.md.resolved

View on GitHub
---
name: programmatic-tool-calling
description: Guide and reference for using Programmatic Tool Calling with Claude, enabling the model to write Python code that invokes other tools.
---

# Programmatic Tool Calling

This skill provides documentation and patterns for "Programmatic Tool Calling", a feature where Claude writes Python code to invoke tools instead of the user (or orchestration layer) calling them directly.

## Overview

Programmatic tool calling allows Claude to:
1.  Write Python code (running in a sandboxed environment).
2.  Call other tools *from within* that Python code.
3.  Process the results programmatically (loops, conditionals, filtering) before returning the final answer.

## Key Concepts

### 1. `allowed_callers`
When defining a tool, you can specify who is allowed to call it via the `allowed_callers` field in the tool definition.

-   `["direct"]`: Only Claude can call this tool directly (standard tool use).
-   `["code_execution_20250825"]`: Only callable from within the code execution sandbox.
-   `["direct", "code_execution_20250825"]`: Callable by both.

**Best Practice**: Choose one or the other to provide clear guidance to the model.

### 2. The `caller` field
When a tool is called, the API response includes a `caller` field:
-   `{"type": "direct"}`: Traditional invocation.
-   `{"type": "code_execution_20250825", "tool_id": "srvtoolu_..."}`: Programmatic invocation from a specific code execution block.

## Workflow

1.  **Orchestrator** sends a message to Claude with tools defined (some with `allowed_callers=["code_execution_20250825"]`).
2.  **Claude** decides to use a tool but realizes it must be called via code.
3.  **Claude** generates a `tool_use` block for `code_execution` (e.g., writing a Python script).
4.  **Orchestrator** executes the Python code.
5.  **Python Code** hits a function call (e.g., `await query_database(...)`).
6.  **Orchestrator** pauses code execution, sends a `tool_use` for `query_database` to the API (or handles it locally if possible).
7.  **System** executes `query_database` and returns the result to the *Python environment*.
8.  **Python Code** resumes with the result.
9.  **Claude** receives the final output from the code execution.

## Example Use Cases

-   **Batch Processing**: Query a database for 100 records and filter them in Python before showing them to the user.
-   **Multi-step Logic**: "If API A returns X, call API B; else call API C."
-   **Data Aggregation**: Call a search tool 5 times in parallel (using async) and summarize the results.

## Reference
See `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling` for full documentation.
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall