Agentsop HTTP 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 against references/R1-source-evidence.md for full URLs. Reusable code shapes live in references/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 <some API>", "add a tool that calls <service>", "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 CrewAI BaseTool.

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:

1. 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].

2. 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].

3. 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.

4. 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-link llm-tool-idempotency for 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: "what user/agent intent does this serve?" Drop endpoints with no agent-facing intent (internal admin, batch jobs, outbound webhooks). The MCP guidance is a useful first cut: GET-style data reads often map to resources; create/update/delete map to tools [gun/mcp]. Target ≤10 surfaced operations for a first pass.

Gate: if you are about to create one tool per endpoint, stop — that is AP-1. Auto-generated 1:1 servers from an OpenAPI spec "routinely under-perform hand-curated tools" [stainless/mcp].

Step 2 · Name from intent

Tool name = verb_object describing intent: search_orders, cancel_order, get_order_status. Not post_orders_v2, delete_orders_id. Test: a model that has never seen your API, reading only the name, should guess when to call it. The name should be a verb; the description should explain when to call, not how [oai/prompting].

Step 3 · Flatten params into a typed schema

Define a Pydantic model (or JSON Schema). Rules:

• Type-annotated fields, each with a model-facing description= (units, format, enum, example) [lc/tools] [apxml/schema].
• Flatten the API's wire format: filter[status]=open → status: Literal["open","closed"]. The model should never construct a query-string fragment.
• Explicit required vs optional. Defaults where the API has sensible ones.
• Hide pagination/auth/internal knobs from the schema (Steps 5–6).

Gate: every field the model can set has a description=. Untyped **kwargs or a free-form body: str is a smell — the model will fill it wrong.

Step 4 · Error handling: translate, never leak

Catch HTTPStatusError / ValidationError / network errors. Return a structured, LM-readable error, never a raw stack trace:

{"error": "rate_limited", "message": "...", "retryable": true, "hint": "wait and retry"}

Use a small closed set of error codes (not_found, invalid_input, auth_failed, rate_limited, server_error). LangChain's ToolException converts a raised error into an LM-visible string for the same reason [lc/structured]. The model reasons over the error like any other tool output — give it something it can act on.

Step 5 · Shape the output

Define an output model with only the fields the agent needs. Drop audit timestamps, internal mirrors, deprecated fields, ETags. Summarize blobs into strings. Aim for a compact payload per call (rule of thumb: keep it small enough that re-reading it 5 times in a loop is cheap). For lists, return items + a next_cursor, not the whole dataset (Step 5b).

Step 5b · Pagination. Default: fetch one page, return items + next_cursor, let the agent decide to continue. Prefer cursor over offset — "cursor-based pagination is more reliable than offset/limit for agentic scrolling" [techops/rest]. Auto-loop only when total is small and bounded (≤200); never loop unbounded — a single agent can "burst 20 sequential API calls to complete one task" [zuplo/agent-ready] (cross-link bounded-loop skill).

Step 6 · Auth & secrets at the wrapper boundary

Read the key/token from env or a secret store inside the wrapper. Never expose api_key as a tool parameter and never put a secret in the description — the model doesn't need it and traces would leak it. Per-tenant tokens flow via a closure or context object, not via tool args [northflank/mcp].

Gate: grep your tool schema and description for key, token, secret, password. Zero hits.

Step 7 · Idempotency on mutations

If the tool does POST/PUT/DELETE, it will be retried by the model or the framework. Generate an idempotency key per logical operation and pass it (Idempotency-Key header) when the API supports it — the canonical Stripe pattern [stripe/idem]. Tag the tool metadata mutating=True. For the full decision tree (key derivation, dedup store, at-least-once vs exactly-once), defer to the llm-tool-idempotency skill — that is its entire domain.

4. 操作模型 (Operation Models)

Format: Trigger → Action → Output → Evidence. (Full JSON in intermediate/operation_candidates.json.)

OP-1 · Endpoint triage

• Trigger: New API, >3 endpoints.
• Action: Enumerate endpoint × verb; label each with the agent intent it serves; drop the intent-less ones. Cap at ~10.
• Output: Triaged candidate list with intent labels.
• Evidence: [zuplo/agent-ready] [stainless/mcp].

OP-2 · Name by intent

• Trigger: Naming a surfaced operation.
• Action: verb_object; name-only readability test.
• Output: Intent-named tool.
• Evidence: [oai/prompting].

OP-3 · Typed input schema

• Trigger: Each surfaced tool.
• Action: Pydantic model; per-field model-facing description=; flatten wire params; explicit required/optional.
• Output: args_schema on the tool.
• Evidence: [lc/tools] [oai/fc] [anthropic/tooluse] [apxml/schema].

OP-4 · Inject auth at boundary

• Trigger: Tool needs a key/token.
• Action: Read secret inside the wrapper from env/secret store; never a tool param; per-tenant via closure/context.
• Output: Tool that authenticates with no secret in schema.
• Evidence: [northflank/mcp].

OP-5 · Timeout + retry + jittered backoff

• Trigger: Any outbound HTTP from a tool.
• Action: Explicit per-attempt timeout=. Retry only on 429/5xx/network, max 3–5, exponential backoff with jitter, honor Retry-After. Never retry other 4xx.
• Output: Resilient client inside the tool.
• Evidence: [apxml/rate] [boldsign/retry] [getknit/rate].

OP-6 · Pagination — cursor first

• Trigger: List endpoint with next/cursor/Link.
• Action: Return one page + next_cursor; agent decides to continue; bounded auto-loop only for small totals.
• Output: Paginated tool with explicit cursor surface.
• Evidence: [techops/rest] [zuplo/agent-ready].

OP-7 · Response shaping

• Trigger: API returns large/deep JSON.
• Action: Output Pydantic model with only reason/act-relevant fields; drop audit/internal/deprecated; summarize blobs.
• Output: Trimmed structured output.
• Evidence: [apxml/schema] [gun/mcp].

OP-8 · Error → readable feedback

• Trigger: Non-2xx or local exception.
• Action: Catch; return {error, message, retryable, hint} from a closed code set; never raw traces.
• Output: LM-readable error contract.
• Evidence: [lc/structured] [mighty/fault].

OP-9 · Idempotency key on mutations

• Trigger: POST/PUT/DELETE side effect.
• Action: Per-operation idempotency key via header; tag mutating=True. Defer full protocol to llm-tool-idempotency.
• Output: Mutation-safe tool with idempotency contract.
• Evidence: [stripe/idem] [techops/rest] [mighty/fault].

OP-10 · Framework binding

• Trigger: Implementation done; deploy into an agent.
• Action: One Pydantic schema → all targets. LangChain/LangGraph: @tool with args_schema. CrewAI: subclass BaseTool._run. OpenAI: tools=[{type: "function", function:{...}}]. Anthropic: {name, description, input_schema}. MCP: @mcp.tool(). Derive each via Model.model_json_schema().
• Output: Framework-bound tool.
• Evidence: [lc/tools] [crewai/tools] [mcp/spec] [oai/fc] [anthropic/tooluse].

5. 困境决策案例 (Dilemma Cases)