api-caller-subagent
Sous-agent spécialisé dans les appels API REST/GraphQL avec retry, auth et transformation de données. Se déclenche avec "sous-agent API", "API caller agent", "agent qui appelle une API", "REST agent", "HTTP agent", "API integration subagent", "external API agent". Also triggers on "subagent that calls an API", "API calling agent", "agent HTTP requests".
khalilbenaz · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add khalilbenaz/claude-skills-collection --skill api-caller-subagent技能说明
name: api-caller-subagent description: Sous-agent spécialisé dans les appels API REST/GraphQL avec retry, auth et transformation de données. Se déclenche avec "sous-agent API", "API caller agent", "agent qui appelle une API", "REST agent", "HTTP agent", "API integration subagent", "external API agent". Also triggers on "subagent that calls an API", "API calling agent", "agent HTTP requests".
API Caller Sub-Agent
Quand utiliser ce skill
Déléguer à ce sous-agent tout appel réseau sortant depuis un agent parent : intégration d'APIs tierces, scraping structuré via API, agrégation multi-sources, synchronisation de données.
Critères de décision :
- Plusieurs APIs différentes dans le même workflow → sous-agent par API ou sous-agent unique réutilisé
- Auth complexe (OAuth2, rotation de token) → toujours isoler dans ce sous-agent
- Pagination ou rate limiting → laisser le sous-agent gérer, l'agent parent ne voit qu'un tableau plat
- Requête unique simple GET sans auth → acceptable en direct si le contexte est simple
Workflow en 10 étapes
1. Validation des inputs
Avant toute connexion réseau, valider :
from urllib.parse import urlparse
def validate_input(inp: dict) -> None:
parsed = urlparse(inp["url"])
assert parsed.scheme in ("https", "http"), "Schéma invalide"
assert parsed.netloc, "URL sans hôte"
assert inp["method"].upper() in (
"GET","POST","PUT","PATCH","DELETE","HEAD","GRAPHQL"
), f"Méthode inconnue: {inp['method']}"
if inp.get("auth", {}).get("type") not in (
None,"none","api_key","bearer","oauth2","jwt","basic"
):
raise ValueError("auth.type non supporté")
Retourner immédiatement un output d'erreur formaté sans lever d'exception non catchée.
2. Résolution de l'authentification
Choisir le handler selon auth.type :
| Type | Implémentation |
|---|---|
api_key | Header X-Api-Key ou query param ?api_key= |
bearer | Authorization: Bearer {token} |
basic | Authorization: Basic {b64(user:pass)} |
oauth2 | Client Credentials : POST /token, stocker + rafraîchir |
jwt | PyJWT.encode(payload, secret, algorithm="HS256") |
import base64, httpx, jwt, time
def build_auth_headers(auth: dict) -> dict:
t = auth.get("type", "none")
c = auth.get("credentials", {})
if t == "bearer":
return {"Authorization": f"Bearer {c['token']}"}
if t == "basic":
raw = base64.b64encode(f"{c['username']}:{c['password']}".encode()).decode()
return {"Authorization": f"Basic {raw}"}
if t == "api_key":
return {c.get("header_name", "X-Api-Key"): c["key"]}
if t == "jwt":
token = jwt.encode(
{"sub": c.get("sub","agent"), "exp": int(time.time()) + 3600},
c["secret"], algorithm="HS256"
)
return {"Authorization": f"Bearer {token}"}
return {}
Refresh OAuth2 : stocker (access_token, expires_at) en mémoire ; re-demander un token si expires_at - now < 60s.
3. Construction de la requête
import httpx
def build_request(inp: dict, auth_headers: dict) -> dict:
headers = {
"Content-Type": "application/json",
"Accept": "application/json",
"User-Agent": "APICallerSubAgent/1.0",
"X-Request-ID": str(uuid.uuid4()),
**auth_headers,
**(inp.get("params", {}).get("headers", {})),
}
method = inp["method"].upper()
if method == "GRAPHQL":
method = "POST"
body = {"query": inp["graphql_query"], "variables": inp.get("params", {}).get("body", {})}
else:
body = inp.get("params", {}).get("body")
return dict(
method=method, url=inp["url"],
params=inp.get("params", {}).get("query"),
json=body, headers=headers,
timeout=inp.get("timeout", 30),
)
4. Exécution avec retry et circuit breaker
from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
RETRYABLE = (httpx.TimeoutException, httpx.ConnectError)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=1, max=8),
retry=retry_if_exception_type(RETRYABLE),
reraise=True,
)
def execute(req: dict) -> httpx.Response:
with httpx.Client() as client:
resp = client.request(**req)
if resp.status_code >= 500:
resp.raise_for_status() # force un retry via tenacity
return resp
Circuit breaker : utiliser circuitbreaker (pip) ou un compteur local ; ouvrir après 5 erreurs 5xx consécutives, demi-ouverture après 60s.
5. Rate limiting proactif
import time
def respect_rate_limit(resp: httpx.Response) -> None:
remaining = int(resp.headers.get("X-RateLimit-Remaining", 1))
reset_ts = int(resp.headers.get("X-RateLimit-Reset", 0))
retry_after = int(resp.headers.get("Retry-After", 0))
if resp.status_code == 429 or remaining == 0:
wait = max(retry_after, reset_ts - int(time.time()), 1)
time.sleep(wait)
6. Pagination automatique
def paginate(inp: dict, first_resp: dict) -> list:
results = first_resp.get("data", [])
cursor = first_resp.get("next_cursor") or first_resp.get("meta", {}).get("next")
page = 2
max_r = inp.get("max_records", 1000)
while cursor and len(results) < max_r:
paged_inp = dict(inp)
q = dict(inp.get("params", {}).get("query") or {})
q["cursor"] = cursor # adapter selon l'API : page=page, offset=len(results)
paged_inp.setdefault("params", {})["query"] = q
resp = execute(build_request(paged_inp, {}))
body = resp.json()
results.extend(body.get("data", []))
cursor = body.get("next_cursor")
page += 1
return results[:max_r]
Stratégies supportées : offset/limit, cursor, page, Link header (RFC 5988).
7. Parsing de la réponse
import json
from lxm
阅读完整来源 ↗