Agent Skills Claude API: kaip naudoti paruoštą įgūdį be Claude Code

Papildomų instrukcijų rasite Ailoot dokumentacijoje.

Ko reikės#

Šis vadovas skirtas tiesiogiai kviesti API iš programos, o ne įdiegti įgūdį Claude Code. Jums reikės Claude API rakto, prieigos prie pasirinkto modelio ir Python 3. Toliau pateiktame kode naudojama standartinė Python biblioteka ir HTTP, todėl jis nepriklauso nuo to, kurią SDK versiją esate įdiegę. Raktas perduodamas per aplinkos kintamąjį ANTHROPIC_API_KEY; nedėkite jo į programos tekstą ar pokalbį.

API siūlo paruoštus Anthropic įgūdžius: pptx pristatymams, xlsx skaičiuoklėms, docx Word dokumentams ir pdf PDF failams. Jie prijungiami naudojant type: "anthropic". Šiame vadove naudojamas paruoštas įgūdis, neįkeliant pasirinktinio įgūdžio.

Oficialiajame greitojo paleidimo vadove, atvertame rengiant šią medžiagą, naudojamas derinys claude-opus-5-5 ir code_execution_20260521. Toliau naudojamas būtent šis derinys. Šis pavyzdys patikrintas pagal dokumentaciją; tai nėra pranešimas apie atliktą mokamą API užklausą.

Kurių beta antraščių reikia#

Pavyzdys atitinka dabartinę greitojo paleidimo vadovo HTTP sąsają: antraštės yra x-api-key, anthropic-version: 2023-06-01 ir content-type: application/json; antraštė anthropic-beta nesiunčiama. Nederinkite modelio, iškvietimo būdo ir atsakymo formato iš skirtingų dokumentacijos versijų.

Files API dokumentacijoje taip pat nurodyta, kad API nebėra beta versijos. Senoji antraštė files-api-2025-04-14 išsaugo senuosius atsakymo formatus; ją pašalinus pereinama prie dabartinių formatų. Todėl seno pavyzdžio, kuriame naudojamas client.beta.files, negalima tiesiog sujungti su nauju pavyzdžiu.

Šiame vadove esamos paslaugos nemigruojame iš senosios beta sąsajos. Jei tokią paslaugą jau turite, pirmiausia patikrinkite jos antraštes ir atsakymo formatus. Vien žodžio beta SDK metodo pavadinime nepakanka: Files API dokumentacijoje atskirai paaiškinta, kaip veikia skirtingos SDK versijos.

Pristatymo kūrimas ir failo atsisiuntimas#

Pavyzdyje siunčiama užduotis sukurti penkias skaidres apie atsinaujinančiąją energiją, visas atsakymas išsaugomas faile skill-response.json, o tada ištraukiami sugeneruotų failų ID. Išsaugojimo kelias neimamas iš modelio atsakymo: failai įrašomi į naują vietinį aplanką skill-output. Jei toks aplankas jau yra, programa sustoja, kad neperrašytų ankstesnio rezultato. Aplankas sukuriamas prieš API iškvietimą, todėl lieka ir jam nepavykus. Prieš ką nors kartodami patikrinkite ir išsaugokite tą bandymą; neištrinkite jo vien tam, kad programa vėl pasileistų.

import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

API = "https://api.anthropic.com/v1"
KEY = os.environ["ANTHROPIC_API_KEY"]
HEADERS = {
    "x-api-key": KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
}

def request(path, payload=None, binary=False):
    data = None if payload is None else json.dumps(payload).encode("utf-8")
    req = Request(API + path, data=data, headers=HEADERS)
    try:
        with urlopen(req, timeout=600) as result:
            body = result.read()
    except HTTPError as error:
        try:
            details = json.loads(error.read().decode("utf-8"))
        except (ValueError, UnicodeError):
            details = {}
        info = details.get("error", {})
        request_id = error.headers.get("request-id") or details.get("request_id")
        diagnostic = {
            "http_status": error.code,
            "request_id": request_id,
            "error_type": info.get("type"),
            "message": str(info.get("message", "No JSON error message")).replace(KEY, "[REDACTED]")[:1000],
        }
        (out / "skill-error.json").write_text(
            json.dumps(diagnostic, ensure_ascii=False, indent=2), encoding="utf-8"
        )
        raise RuntimeError(
            f"Claude API HTTP {error.code}; request_id={request_id}; inspect skill-error.json"
        ) from None
    return body if binary else json.loads(body)

out = Path("skill-output")
out.mkdir(exist_ok=False)
response = request("/messages", {
    "model": "claude-opus-5-5",
    "max_tokens": 16000,
    "container": {
        "skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]
    },
    "messages": [{
        "role": "user",
        "content": "Sukurkite 5 skaidrių pristatymą apie atsinaujinančiąją energiją mano pageidaujama kalba.",
    }],
    "tools": [{"type": "code_execution_20260521", "name": "code_execution"}],
})
(out / "skill-response.json").write_text(
    json.dumps(response, ensure_ascii=False, indent=2), encoding="utf-8"
)
print("stop_reason:", response.get("stop_reason"))

file_ids = []
for block in response["content"]:
    if block["type"] == "bash_code_execution_tool_result":
        result = block["content"]
        if result["type"] == "bash_code_execution_result":
            for item in result["content"]:
                file_id = item.get("file_id")
                if file_id and file_id not in file_ids:
                    file_ids.append(file_id)
if not file_ids:
    raise RuntimeError("No generated file_id; inspect skill-response.json")

for index, file_id in enumerate(file_ids, start=1):
    from urllib.parse import quote
    file_path = "/files/" + quote(file_id, safe="")
    metadata = request(file_path)
    if metadata.get("downloadable") is not True:
        raise RuntimeError("This file cannot be downloaded through Files API")
    target = out / f"result-{index}.pptx"
    target.write_bytes(request(file_path + "/content", binary=True))
    print("Saved:", target)

Pavadinimai result-1.pptx ir toliau pasirinkti šiai pristatymo užduočiai. Failo plėtinys neįrodo, kas jame yra: atidarykite atsisiųstą dokumentą ir patikrinkite jo formatą, skaidrių skaičių bei tekstą. Vien HTTP 200 atsakymo ar file_id buvimo nelaikykite sėkmingu rezultatu.

Programa išveda stop_reason – priežastį, dėl kurios atsakymas buvo sustabdytas, ir išsaugo visą atsakymą peržiūrai. Ji netęsia pokalbio ir automatiškai nekartoja mokamos užklausos. Atsisiųstas failas nereiškia, kad visa užduotis baigta: prieš nuspręsdami, ar reikia kitos užklausos, patikrinkite išsaugotą atsakymą ir patį dokumentą.

Jei bandymas nepavyko, patikrinkite skill-error.json, jei jis yra. Jame įrašyta HTTP būsena, užklausos ID, jei pateiktas, ir apriboto ilgio tiekėjo klaidos pranešimas, iš kurio pašalintas sukonfigūruotas API raktas. Prieš dalydamiesi pranešimu patikrinkite, ar jame nėra kitų privačių duomenų. Autentifikavimo, teisių ar modelio, mokėjimo limitų ir užklausos formato klaidas palyginkite su oficialiu klaidų aprašu; nemanykite, kad kiekvienai klaidai reikia naujos mokamos generacijos.

Jei skill-response.json jau yra sugeneruotų file_id reikšmių ir nepavyko tik atsisiuntimas, išsaugokite atsakymą ir failo metaduomenų ar atsisiuntimo etapą diagnozuokite naudodami tą pačią autorizuotą darbo srities prieigą. Nekartokite generavimo bloko vien tam, kad atsisiųstumėte esamą rezultatą. Jei užklausos baigtis nežinoma, išsaugokite jos ID ir išsiaiškinkite būseną prieš siųsdami kitą generavimo užklausą. Tik nusprendę, kad nauja generacija būtina, vietinio aplanko eilutėje nurodykite dar nenaudotą kelią, pavyzdžiui, out = Path("skill-output-attempt-2"), ir palikite exist_ok=False. Naujas aplankas apsaugo nuo failų perrašymo, bet ne nuo pakartotinio API mokesčio.

Kokios failų prieigos teisės reikalingos#

Files API susieja failus su darbo sritimi, o ne su atskiru jūsų programos naudotoju ar pokalbiu. Dokumentacijoje teigiama, kad bet kuris API raktas, turintis prieigą prie tos darbo srities, gali pasiekti joje įkeltus failus. Pavyzdyje atsisiuntimui naudojamas tas pats raktas kaip ir generavimui. Niekada nepriimkite file_id iš galutinių naudotojų ar kitų nepatikimų šaltinių. Saugokite šiuos ID serveryje ir savo programoje tvarkykite naudotojų bei jų failų sąsają.

Failo metaduomenis tikrinkite atskirai: juose turi būti downloadable: true. Dokumentacija leidžia atsisiųsti įgūdžių arba kodo vykdymo įrankio sugeneruotus failus; jūsų įkeltiems failams nustatyta downloadable: false, o bandant juos atsisiųsti grąžinama 400 klaida. Prieiga prie darbo srities ir galimybė atsisiųsti konkretų failą yra atskiri reikalavimai.

Daugelio naudotojų programai Files API dokumentacijoje kaip failų izoliavimo ribą rekomenduojama kiekvienam klientui skirti atskirą darbo sritį. Ši rekomendacija konkrečiai susijusi su failais; netaikykite jos visoms esybėms ir teisėms, nepatikrinę atitinkamos API.

Paruošti ir pasirinktiniai įgūdžiai#

Paruoštų įgūdžių ID yra pptx, xlsx, docx ir pdf. Įgūdžių sąrašo nuorodoje šaltinis custom apibūdinamas kaip privatus darbo sričiai, o anthropic – kaip bendrinamas ir tik skaitomas.

Pirmajame pavyzdyje version: "latest" reiškia naujausią paskelbtą įgūdžio versiją. Jei siekiate atkuriamos integracijos, turėkite omenyje, kad šis pasirinkimas gali pasikeisti; norėdami naudoti fiksuotą versiją, pasirinkite esamą naudojamo įgūdžio versiją, o ne išgalvotą ID iš pavyzdžio.

Apribojimai ir tolesnis žingsnis#

Pavyzdyje aptariamas tik pristatymo kūrimas naudojant paruoštą įgūdį ir jo atsisiuntimas. Pasirinktinių įgūdžių įkėlimas, jų ištrynimas ir prieiga prie trečiųjų šalių paslaugų čia nebuvo išbandyti. Šioms užduotims reikia atskirai patikrinti atitinkamą API.

Jei jūsų užduotis susijusi su failais Claude sąsajoje, skaitykite atskirą vadovą kaip įkelti failą į Claude. Tiesioginiams iškvietimams žr. kaip apskaičiuoti API žetonų naudojimą. Jei dirbate su terminalo agentu, skaitykite kaip pasirinkti Claude Code įgūdžius: jie prijungiami kitu būdu.

Pirmajam patikrinimui pakanka vieno paruošto pptx įgūdžio: patikrinkite atsakymą, atsisiųskite failą, kurį leidžiama atsisiųsti, ir jį atidarykite. Pasirinktinius įgūdžius ir klientų prieigos atskyrimą pridėkite po šio patikrinimo.

Kai būsite pasiruošę, susipažinkite su Ailoot.