Loading...
Loading...
Compare original and translation side by side
| Use code execution when... | Use direct tool calls when... |
|---|---|
| Connecting to 10+ MCP servers or 50+ tools | Few servers with handful of tools |
| Intermediate results are large (>10K tokens) | Results are small and all needed by the model |
| Workflows need loops, retries, or conditionals | Linear sequences of 2-3 tool calls |
| PII must not reach the model context | No sensitive data in tool responses |
| Tasks benefit from state persistence across runs | Stateless, one-shot operations |
| You want agents to accumulate reusable skills | Fixed, predefined workflows |
| 适合使用代码执行模式的场景 | 适合直接调用工具的场景 |
|---|---|
| 需要连接10个以上MCP服务器或50个以上工具 | 仅需对接少量服务器和少数几个工具 |
| 中间结果体积大(超过1万tokens) | 结果体积小,且模型需要完整结果 |
| 工作流需要循环、重试或条件判断逻辑 | 仅需2-3次工具调用的线性流程 |
| PII不得传入模型上下文 | 工具响应中不含敏感数据 |
| 任务需要跨运行保留状态 | 无状态的一次性操作 |
| 需要Agent积累可复用的技能 | 固定的预定义工作流 |
project/
├── servers/
│ ├── google-drive/
│ │ ├── getDocument.ts
│ │ ├── getSheet.ts
│ │ ├── listFiles.ts
│ │ └── index.ts # Re-exports all tools
│ ├── salesforce/
│ │ ├── query.ts
│ │ ├── updateRecord.ts
│ │ └── index.ts
│ └── slack/
│ ├── sendMessage.ts
│ ├── getChannelHistory.ts
│ └── index.ts
├── skills/ # Agent-accumulated reusable functions
│ └── save-sheet-as-csv.ts
├── workspace/ # Persistent state between executions
├── client.ts # MCP client that routes calls to servers
└── sandbox.config.ts # Execution environment configurationproject/
├── servers/
│ ├── google-drive/
│ │ ├── getDocument.ts
│ │ ├── getSheet.ts
│ │ ├── listFiles.ts
│ │ └── index.ts # 重新导出所有工具
│ ├── salesforce/
│ │ ├── query.ts
│ │ ├── updateRecord.ts
│ │ └── index.ts
│ └── slack/
│ ├── sendMessage.ts
│ ├── getChannelHistory.ts
│ └── index.ts
├── skills/ # Agent积累的可复用函数
│ └── save-sheet-as-csv.ts
├── workspace/ # 跨执行的持久化状态存储
├── client.ts # 负责将调用路由到对应服务器的MCP客户端
└── sandbox.config.ts # 执行环境配置// servers/google-drive/getDocument.ts
import { callMCPTool } from "../../client.js";
interface GetDocumentInput {
documentId: string;
}
interface GetDocumentResponse {
content: string;
}
/** Read a document from Google Drive */
export async function getDocument(
input: GetDocumentInput
): Promise<GetDocumentResponse> {
return callMCPTool<GetDocumentResponse>("google_drive__get_document", input);
}import * as gdrive from "./servers/google-drive";
import * as salesforce from "./servers/salesforce";
const transcript = (
await gdrive.getDocument({ documentId: "abc123" })
).content;
await salesforce.updateRecord({
objectType: "SalesMeeting",
recordId: "00Q5f000001abcXYZ",
data: { Notes: transcript },
});// servers/google-drive/getDocument.ts
import { callMCPTool } from "../../client.js";
interface GetDocumentInput {
documentId: string;
}
interface GetDocumentResponse {
content: string;
}
/** 从Google Drive读取文档 */
export async function getDocument(
input: GetDocumentInput
): Promise<GetDocumentResponse> {
return callMCPTool<GetDocumentResponse>("google_drive__get_document", input);
}import * as gdrive from "./servers/google-drive";
import * as salesforce from "./servers/salesforce";
const transcript = (
await gdrive.getDocument({ documentId: "abc123" }
).content;
await salesforce.updateRecord({
objectType: "SalesMeeting",
recordId: "00Q5f000001abcXYZ",
data: { Notes: transcript },
});Agent: "I need to read from Google Drive"
→ ls servers/
→ ls servers/google-drive/
→ cat servers/google-drive/getDocument.ts (reads signature + JSDoc)
→ generates code importing only getDocumentAgent: "我需要从Google Drive读取数据"
→ ls servers/
→ ls servers/google-drive/
→ cat servers/google-drive/getDocument.ts (读取函数签名 + JSDoc注释)
→ 生成仅导入getDocument的代码// Filter in the sandbox — only summary reaches the model
const allRows = await gdrive.getSheet({ sheetId: "abc123" });
const pending = allRows.filter((row) => row["Status"] === "pending");
console.log(`Found ${pending.length} pending orders`);
console.log(pending.slice(0, 5)); // Only first 5 for model review// 在沙箱中完成过滤 —— 仅摘要会传入模型
const allRows = await gdrive.getSheet({ sheetId: "abc123" });
const pending = allRows.filter((row) => row["Status"] === "pending");
console.log(`Found ${pending.length} pending orders`);
console.log(pending.slice(0, 5)); // 仅返回前5条供模型审核// Polling loop — runs entirely in sandbox
let found = false;
while (!found) {
const messages = await slack.getChannelHistory({ channel: "C123456" });
found = messages.some((m) => m.text.includes("deployment complete"));
if (!found) await new Promise((r) => setTimeout(r, 5000));
}
console.log("Deployment notification received");// 轮询循环 —— 完全在沙箱中运行
let found = false;
while (!found) {
const messages = await slack.getChannelHistory({ channel: "C123456" });
found = messages.some((m) => m.text.includes("deployment complete"));
if (!found) await new Promise((r) => setTimeout(r, 5000));
}
console.log("Deployment notification received");// Agent writes this code
for (const row of sheet.rows) {
await salesforce.updateRecord({
objectType: "Lead",
recordId: row.salesforceId,
data: { Email: row.email, Phone: row.phone, Name: row.name },
});
}
console.log(`Updated ${sheet.rows.length} leads`);[
{ salesforceId: "00Q...", email: "[EMAIL_1]", phone: "[PHONE_1]", name: "[NAME_1]" },
{ salesforceId: "00Q...", email: "[EMAIL_2]", phone: "[PHONE_2]", name: "[NAME_2]" }
]
Updated 247 leads// Agent编写的代码
for (const row of sheet.rows) {
await salesforce.updateRecord({
objectType: "Lead",
recordId: row.salesforceId,
data: { Email: row.email, Phone: row.phone, Name: row.name },
});
}
console.log(`Updated ${sheet.rows.length} leads");[
{ salesforceId: "00Q...", email: "[EMAIL_1]", phone: "[PHONE_1]", name: "[NAME_1]" },
{ salesforceId: "00Q...", email: "[EMAIL_2]", phone: "[PHONE_2]", name: "[NAME_2]" }
]
Updated 247 leads// Execution 1: fetch and save
const leads = await salesforce.query({
query: "SELECT Id, Email FROM Lead LIMIT 1000",
});
await fs.writeFile("./workspace/leads.csv", leads.map((l) => `${l.Id},${l.Email}`).join("\n"));
// Execution 2: resume from saved state
const saved = await fs.readFile("./workspace/leads.csv", "utf-8");// 第一次执行:拉取并保存数据
const leads = await salesforce.query({
query: "SELECT Id, Email FROM Lead LIMIT 1000",
});
await fs.writeFile("./workspace/leads.csv", leads.map((l) => `${l.Id},${l.Email}`).join("\
"));
// 第二次执行:从保存的状态恢复工作
const saved = await fs.readFile("./workspace/leads.csv", "utf-8");// skills/save-sheet-as-csv.ts
import * as gdrive from "../servers/google-drive";
import * as fs from "fs/promises";
export async function saveSheetAsCsv(sheetId: string): Promise<string> {
const data = await gdrive.getSheet({ sheetId });
const csv = data.map((row) => row.join(",")).join("\n");
const path = `./workspace/sheet-${sheetId}.csv`;
await fs.writeFile(path, csv);
return path;
}import { saveSheetAsCsv } from "./skills/save-sheet-as-csv";
const csvPath = await saveSheetAsCsv("abc123");// skills/save-sheet-as-csv.ts
import * as gdrive from "../servers/google-drive";
import * as fs from "fs/promises";
export async function saveSheetAsCsv(sheetId: string): Promise<string> {
const data = await gdrive.getSheet({ sheetId });
const csv = data.map((row) => row.join(",")).join("\
");
const path = `./workspace/sheet-${sheetId}.csv`;
await fs.writeFile(path, csv);
return path;
}import { saveSheetAsCsv } from "./skills/save-sheet-as-csv";
const csvPath = await saveSheetAsCsv("abc123");.mcp.jsoncat .mcp.json 2>/dev/null || echo "No MCP config found".mcp.jsoncat .mcp.json 2>/dev/null || echo "No MCP config found"callMCPToolcallMCPToolcallMCPTool// client.ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
const clients = new Map<string, Client>();
export async function callMCPTool<T>(
toolName: string,
input: Record<string, unknown>
): Promise<T> {
const serverName = toolName.split("__")[0];
const client = clients.get(serverName);
if (!client) throw new Error(`No MCP client for server: ${serverName}`);
const result = await client.callTool({ name: toolName, arguments: input });
return result.content as T;
}callMCPTool// client.ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
const clients = new Map<string, Client>();
export async function callMCPTool<T>(
toolName: string,
input: Record<string, unknown>
): Promise<T> {
const serverName = toolName.split("__")[0];
const client = clients.get(serverName);
if (!client) throw new Error(`No MCP client for server: ${serverName}`);
const result = await client.callTool({ name: toolName, arguments: input });
return result.content as T;
}| Concern | Requirement |
|---|---|
| Isolation | Process-level or container-level sandboxing |
| Resource limits | CPU time, memory caps, disk quotas |
| Network | Restrict to MCP server connections only |
| Timeout | Hard execution time limit per run |
| Filesystem | Scoped to |
| Monitoring | Log all executions and MCP calls |
| 关注点 | 要求 |
|---|---|
| 隔离性 | 进程级或容器级沙箱隔离 |
| 资源限制 | CPU时间、内存上限、磁盘配额限制 |
| 网络 | 仅允许连接MCP服务器的网络访问 |
| 超时控制 | 单次执行的硬超时限制 |
| 文件系统 | 仅允许访问 |
| 监控 | 记录所有执行和MCP调用日志 |
1. Receive user request
2. Agent explores servers/ tree to find relevant tools
3. Agent generates TypeScript code using typed wrappers
4. Code executes in sandbox
5. Filtered output returns to agent
6. Agent decides: done, or generate more code?1. 接收用户请求
2. Agent遍历servers/目录查找相关工具
3. Agent基于类型封装函数生成TypeScript代码
4. 代码在沙箱中执行
5. 过滤后的输出返回给Agent
6. Agent判断:任务完成,或继续生成更多代码?| Item | Status |
|---|---|
| Sandboxed execution environment | Required |
| Resource limits (CPU, memory, disk) | Required |
| Network isolation (MCP servers only) | Required |
| Execution timeout | Required |
| PII tokenization in MCP client | Recommended for sensitive data |
| Audit logging of all executions | Recommended |
Read-only access to | Recommended |
Scoped write access to | Recommended |
| 检查项 | 要求 |
|---|---|
| 沙箱化执行环境 | 必须 |
| 资源限制(CPU、内存、磁盘) | 必须 |
| 网络隔离(仅允许访问MCP服务器) | 必须 |
| 执行超时控制 | 必须 |
| MCP客户端PII脱敏 | 敏感数据场景推荐开启 |
| 所有执行操作审计日志 | 推荐 |
| 推荐 |
仅允许向 | 推荐 |
| Context | Approach |
|---|---|
| Many tools (50+) | Use progressive discovery via file tree |
| Large intermediate data | Filter in sandbox, return summaries |
| Multi-step workflows | Generate single code block with control flow |
| Sensitive data pipelines | Enable PII tokenization in MCP client |
| Long-running tasks | Use workspace/ for state persistence |
| Repeated operations | Extract to skills/ for reuse |
| 场景 | 优化方案 |
|---|---|
| 工具数量多(50+) | 使用基于文件树的渐进式发现 |
| 中间数据量大 | 在沙箱中过滤,仅返回摘要 |
| 多步骤工作流 | 生成包含控制流的单个代码块 |
| 敏感数据流水线 | 在MCP客户端开启PII脱敏 |
| 长时间运行任务 | 使用workspace/持久化状态 |
| 重复操作 | 提取到skills/目录复用 |
| Approach | Tool definitions | Intermediate data | Total |
|---|---|---|---|
| Direct tool calls | All loaded upfront | Passes through context | High |
| Code execution | On-demand discovery | Stays in sandbox | Low |
| 方案 | 工具定义加载方式 | 中间数据处理 | 总消耗 |
|---|---|---|---|
| 直接工具调用 | 提前加载所有定义 | 全部经过上下文传递 | 高 |
| 代码执行模式 | 按需发现 | 保留在沙箱中 | 低 |