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

> Kaip prijungti paruoštą pptx įgūdį prie Claude API: container.skills, kodo vykdymo įrankis, atsakymo patikrinimas ir pristatymo atsisiuntimas per Files API.

Source: https://ailoot.ai/blog/lt/claude-api-agent-skills/
Canonical: https://ailoot.ai/blog/lt/claude-api-agent-skills/
Language: lt
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-039
Revision: sha256-b1572dc82ca1c36f2c0d32a22f2a426ff9518b09c43fd1505b51ad4430dc0506


<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Pagrindinė šios skilties mintis">

Pagrindinė mintis

Paruoštus dokumentų Agent Skills galima naudoti tiesiogiai per Claude API: nurodykite įgūdį `container.skills` ir įjunkite `code_execution`. Pirmojoje užklausoje naudokite oficialiame pavyzdyje pateiktą suderinamą modelio ir įrankio derinį. Sugeneruotą failą atsisiųskite atskirai, naudodami jo `file_id`; pavyzdyje užklausai ir atsisiuntimui naudojamas tas pats API raktas.

</div>



Papildomų instrukcijų rasite [Ailoot dokumentacijoje](https://ailoot.ai/docs/).

## 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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/quickstart.md), 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](https://platform.claude.com/docs/en/build-with-claude/files.md) 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ų.

```python
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](https://platform.claude.com/docs/en/api/errors); 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](https://platform.claude.com/docs/en/api/skills/list.md) š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](https://ailoot.ai/blog/lt/claude-file-upload/). Tiesioginiams iškvietimams žr. [kaip apskaičiuoti API žetonų naudojimą](https://ailoot.ai/blog/lt/api-token-usage-calculation/). Jei dirbate su terminalo agentu, skaitykite [kaip pasirinkti Claude Code įgūdžius](https://ailoot.ai/blog/lt/choose-claude-code-skills/): 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](https://ailoot.ai/).

## Klausimai ir atsakymai

### Kodėl vien file_id nepakanka pristatymui laikyti baigtu?

ID rodo, kad grąžintas failas, o ne kad tai tinkamas naudoti pristatymas. Jo metaduomenyse patikrinkite `downloadable: true`, atsisiųskite turėdami darbo srities prieigą ir atverkite, kad patikrintumėte failo formatą, skaidrių skaičių ir tekstą.

### Ar galima atsisiųsti bet kurį į Claude Files API įkeltą failą?

Ne. Vadove skiriami sugeneruoti failai su `downloadable: true` ir įkelti failai su `downloadable: false`. Darbo srities prieiga ir leidimas atsisiųsti konkretų failą yra atskiros patikros; nepriimkite savavališkų failų ID iš galutinių naudotojų.


## Ailoot · Įmonė ir jos projektų portfelis

Ailoot remiasi sukaupta veiklos patirtimi, plačia klientų baze, stabiliomis paslaugomis ir nuolatine KPI kontrole.

Įmonė ir jos projektų portfelis: milijonai klientų; mėnesio pardavimai siekia milijardus.

Ailoot šią veiklos patirtį pritaiko teikdama API prieigą prie DI funkcijų klientų produktuose, agentuose, programose ir automatizavimo sprendimuose.