agentsop-http-tool-wrapping
Decision protocol for wrapping a REST / GraphQL / RPC API as a tool an LLM agent can call. The load-bearing premise: the *tool surface* is an LM-friendly subset of the *API surface* — one tool per user intent, not one per endpoint. Activates when a coder agent must expose an external HTTP API to a model (function calling, tool_use, MCP, LangChain `@tool`, CrewAI `BaseTool`). Encodes the *what to surface, how to name, how to shape, how to fail* — not any single framework's API. ~80% of agent tools in production are HTTP wrappers; this is the SOP for getting them right.
agentsope · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add agentsope/SkillAlchemy --skill agentsop-http-tool-wrapping技能说明
name: agentsop-http-tool-wrapping
version: 0.1.0
description: |
Decision protocol for wrapping a REST / GraphQL / RPC API as a tool an LLM
agent can call. The load-bearing premise: the tool surface is an
LM-friendly subset of the API surface — one tool per user intent, not one
per endpoint. Activates when a coder agent must expose an external HTTP API
to a model (function calling, tool_use, MCP, LangChain @tool, CrewAI
BaseTool). Encodes the what to surface, how to name, how to shape, how to
fail — not any single framework's API. ~80% of agent tools in production are
HTTP wrappers; this is the SOP for getting them right.
domain: coder-agent / tool-construction
audience: engineers wiring external APIs into LLM agents
trigger_keywords:
- "wrap an API as a tool"
- "expose REST endpoint to agent"
- "function calling for my API"
- "MCP server for existing API"
- "tool returns too much JSON"
- "agent rate limited / 429"
- "GraphQL / RPC as agent tool" when_to_use:
- "exposing a third-party or internal HTTP API to an LLM agent"
- "deciding which of N endpoints deserve to become tools"
- "an existing tool dumps raw JSON and the model hallucinates fields"
- "tool calls fail on rate limits, timeouts, or pagination"
- "porting the same tool across OpenAI / Anthropic / MCP / LangChain / CrewAI" when_not_to_use:
- "the API is already an MCP server you only consume (just connect)"
- "no external I/O — pure local computation (write a plain function tool)"
- "designing the upstream API itself (that's API design, not tool wrapping)"
HTTP / External API → Agent Tool · SOP
Source posture: every non-trivial claim is cited inline with short tags like
[oai/fc],[anthropic/tooluse],[lc/tools],[mcp/spec],[apxml/schema]. Resolve them againstreferences/R1-source-evidence.mdfor full URLs. Reusable code shapes live inreferences/R2-pattern-library.md.
1. 何时激活 (When to Activate)
Activate when a coder agent must make an external HTTP API callable by an LLM. Concrete triggers:
- The task says "give the agent access to ", "add a tool that calls ", "wrap our REST/GraphQL/RPC endpoint as a function the model can use".
- You are choosing which of N endpoints become tools, or how to name them.
- An existing tool returns a huge JSON blob and the model hallucinates field names, or burns context re-reading it.
- Tool calls die on
429, timeouts, or unpaginated list endpoints. - You need the same tool to run under OpenAI function calling, Anthropic
tool_use, an MCP server, LangChain@tool, and CrewAIBaseTool.
Do not activate when: the API is already exposed as an MCP server you merely consume (just connect it); the "tool" is pure local computation with no network I/O (write a plain typed function); or you are designing the upstream API itself.
This is a tool-construction skill — sibling to the framework SOPs
(langgraph-sop, crewai-sop) which decide whether/where tools run. Once you
know you need a tool, this skill decides what shape it takes.
2. 核心心智模型 (Core Mental Model)
The tool surface is an LM-friendly subset of the API surface. One tool per intent, not one per endpoint.
A REST API is designed for programmers who read docs, hold a mental model of resources, and compose calls. An agent tool is designed for a language model that sees only a name, a description, and a JSON schema — and must decide, mid-reasoning, whether this is the thing to call. These are different audiences, so the surface must be re-cut, not mirrored.
"Tool descriptions are often more important than code comments because the LLM directly uses them for reasoning."
[apxml/schema]
Four load-bearing consequences:
-
Intent, not CRUD. The unit of a tool is a thing the agent wants to accomplish (
cancel_order,find_customer_by_email), not an HTTP verb on a resource (DELETE /orders/{id}). One intent may compose several endpoints; one endpoint may serve zero intents (admin/batch/webhook-out endpoints get dropped). Surface intent, not the verb table[zuplo/agent-ready]. -
The schema is the prompt. The model never sees your code. It sees the tool name, the description, and each field's
description=. Every field needs units, format, enum values, and an example aimed at the model — "if a field is a date, specify ISO 8601 vs Unix timestamp"[apxml/schema]. A typed schema (Pydantic / JSON Schema) is non-negotiable because it is both the validation layer and the documentation the model reads[lc/tools]. -
The response is context, and context is scarce. A 10 MB JSON payload is not "data the agent has" — it is tokens the agent must pay for, re-read, and can misquote. Shape the response down to the fields the agent needs to reason or act on. Returning raw upstream JSON is the second most common anti-pattern after 1:1 mapping.
-
The model cannot promise call discipline. It may emit zero, one, or several calls — "best practice [is] to assume there are several"
[oai/fc]— retry on its own, or be resumed by the framework. So the wrapper owns reliability (timeout, retry, rate-limit) and safety (idempotency on mutations). You cannot prompt these guarantees into existence; you build them into the tool. (Side-effect safety is deep enough to be its own skill — cross-linkllm-tool-idempotencyfor any mutating tool.)
The pre-LLM analog: you are writing an SDK for a non-deterministic, amnesiac junior dev who reads only the function signature — generous docstrings, narrow typed inputs, small clean returns, and total robustness to being called wrong.
3. SOP 工作流 (Standard Operating Procedure)
Walk top-down. Each step has a gate — if it fails, fix it before adding surface.
Step 1 · Triage: which endpoints deserve to be tools?
List every endpoint × verb. For each, ask
阅读完整来源 ↗