Agent Skills a Claude API-ban: hogyan használjunk kész skillt Claude Code nélkül

További útmutatást az Ailoot dokumentációjában talál.

Amire szüksége lesz#

Ez az útmutató arra szolgál, hogyan hívja meg közvetlenül egy programból az API-t, nem pedig arra, hogyan telepítsen skillt a Claude Code-ba. Szüksége lesz egy Claude API-kulcsra, hozzáférésre a kiválasztott modellhez és Python 3-ra. Az alábbi kód a Python szabványos könyvtárát és a HTTP-t használja, így nem függ attól, hogy az SDK melyik verzióját telepítette. A kulcs az ANTHROPIC_API_KEY környezeti változón keresztül kerül átadásra; ne írja bele a program szövegébe vagy egy beszélgetésbe.

Az API kész Anthropic skilleket kínál: pptx prezentációkhoz, xlsx táblázatokhoz, docx Word-dokumentumokhoz és pdf PDF-ekhez. Ezeket a type: "anthropic" megadásával lehet csatlakoztatni. Ez az útmutató kész skillt használ, egyéni skill feltöltése nélkül.

Az hivatalos gyorsútmutató, amelyet az anyag összeállításakor nyitottak meg, a claude-opus-5-5 és a code_execution_20260521 párost használja. Az alábbi példa is ezt a párost alkalmazza. A példát ellenőriztük a dokumentáció alapján; nem egy fizetős API-hívásról szóló beszámoló.

Milyen béta fejlécekre van szükség#

A példa a gyorsútmutató jelenlegi HTTP-szerződését követi: a fejlécek x-api-key, anthropic-version: 2023-06-01 és content-type: application/json; anthropic-beta fejlécet nem küld. Ne kombináljon különböző dokumentációs generációkból származó modellt, hívási módszert és válaszformátumot.

A Files API dokumentációja azt is kimondja, hogy az API már nem béta. A régi files-api-2025-04-14 fejléc megtartja a régi válaszformátumokat; a fejléc eltávolításával a jelenlegi formátumokra vált. Ezért nem lehet egyszerűen összekombinálni egy régi, client.beta.files-t használó példát egy újjal.

Itt nem egy meglévő szolgáltatást állítunk át a régi béta-szerződésről. Ha már van ilyen szolgáltatása, először ellenőrizze a fejléceket és a válaszformátumokat. Az SDK-metódus nevében szereplő beta önmagában nem elegendő: a Files API dokumentációja külön ismerteti, hogyan viselkednek a különböző SDK-verziók.

Prezentáció létrehozása és a fájl letöltése#

A példa feladatot küld egy öt diából álló, megújuló energiáról szóló prezentáció létrehozására, a teljes választ a skill-response.json fájlba menti, majd kinyeri a létrehozott fájlok azonosítóit. Nem a modell válaszából veszi a mentési útvonalat: a fájlokat egy új, skill-output nevű helyi mappába menti. Ha a mappa már létezik, a program leáll, hogy ne írja felül az előző eredményt. A mappa az API-hívás előtt jön létre, ezért sikertelen hívás után is megmarad. Újabb lépés előtt vizsgálja meg és őrizze meg az adott próbálkozást; ne törölje pusztán azért, hogy az ismételt futtatás továbbjusson.

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": "Készítsen egy 5 diás prezentációt a megújuló energiáról az általam előnyben részesített nyelven.",
    }],
    "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)

A result-1.pptx és az utána következő nevek ehhez a prezentációs feladathoz lettek kiválasztva. A fájlkiterjesztés nem bizonyítja, hogy mi van a fájlban: nyissa meg a letöltött dokumentumot, és ellenőrizze a formátumát, a diák számát és a szöveget. Ne tekintse sikeres eredménynek önmagában a HTTP 200-at vagy egy file_id jelenlétét.

A program kiírja a stop_reason értékét, vagyis hogy miért állt le a válasz, és ellenőrzés céljából elmenti a teljes választ. Nem folytatja a beszélgetést, és nem ismétli meg automatikusan a fizetős kérést. A letöltött fájl megléte nem jelenti azt, hogy a teljes feladat elkészült: mielőtt eldöntené, szükség van-e újabb kérésre, ellenőrizze az elmentett választ és magát a dokumentumot is.

Sikertelen próbálkozásnál vizsgálja meg a skill-error.json fájlt, ha létezik. Ez a HTTP-státuszt, a szolgáltatótól kapott kérésazonosítót és egy korlátozott hosszúságú hibaüzenetet rögzít, amelyből a beállított API-kulcs értéke ki van takarva. Megosztás előtt ellenőrizze, nincs-e benne más személyes adat. A hitelesítési, jogosultsági/modell-, számlázási korlát- és kérésformátum-hibákat vesse össze a hivatalos hibareferenciával; nem minden hiba indokol újabb fizetős generálást.

Ha a skill-response.json már tartalmaz létrehozott file_id értékeket, és csak a letöltés hibázott, őrizze meg a választ, és ugyanazzal az engedélyezett munkaterület-hozzáféréssel vizsgálja a fájlmetaadatok/letöltés lépését. Egy meglévő kimenet letöltéséért ne futtassa újra a generáló blokkot. Ha a kérés eredménye ismeretlen, őrizze meg a kérésazonosítót, és tisztázza az állapotát, mielőtt új generálást küld. Csak ha már eldöntötte, hogy új generálás szükséges, módosítsa a helyi kimeneti sort egy még nem használt útvonalra, például out = Path("skill-output-attempt-2"), és tartsa meg az exist_ok=False értéket. Az új mappa a felülírást akadályozza meg; az ismételt API-díjat nem.

Milyen fájlengedélyekre van szükség#

A Files API a fájlokat egy munkaterülethez rendeli, nem az alkalmazása egyes felhasználóihoz vagy egy beszélgetéshez. A dokumentáció szerint az adott munkaterülethez hozzáférő bármely API-kulccsal elérhetők az ott feltöltött fájlok. A példa ugyanazt a kulcsot használja a letöltéshez, mint a létrehozáshoz. Soha ne fogadjon el file_id-t végfelhasználóktól vagy más nem megbízható forrásból. Tárolja ezeket az azonosítókat a szerveren, és saját alkalmazásában tartsa fenn a felhasználók és fájljaik közötti megfeleltetést.

A fájl metaadatait külön ellenőrizze: tartalmaznia kell a downloadable: true értéket. A dokumentáció lehetővé teszi a skillek vagy a kódvégrehajtási eszköz által létrehozott fájlok letöltését; az Ön által feltöltött fájloknál downloadable: false szerepel, és a letöltési kísérlet 400-as hibát ad vissza. A munkaterülethez való hozzáférés és egy adott fájl letöltésének lehetősége két külön követelmény.

Többfelhasználós alkalmazás esetén a Files API dokumentációja ügyfelenként külön munkaterületet javasol a fájlok elkülönítésére. Ez az ajánlás kifejezetten a fájlokra vonatkozik; ne terjessze ki minden entitásra és engedélyre anélkül, hogy ellenőrizné a vonatkozó API-t.

Kész skillek és egyéni skillek#

A kész skillek azonosítói: pptx, xlsx, docx és pdf. A skillek listájának referenciájában a custom forrás a munkaterületre korlátozottként, míg az anthropic megosztottként és csak olvashatóként van leírva.

Az első példában szereplő version: "latest" a skill legutóbb közzétett verzióját jelenti. Reprodukálható integrációnál vegye figyelembe, hogy ez a kiválasztás változhat; rögzített verzióra váltáshoz a használt skill egy létező verzióját kell kiválasztania, nem pedig egy példából kitalált azonosítót.

Korlátok és következő lépés#

A példa csak egy prezentáció kész skilllel való létrehozását és letöltését mutatja be. Egyéni skillek feltöltését, törlését és harmadik fél szolgáltatásaihoz való hozzáférést itt nem teszteltük. Ezekhez külön ellenőrizni kell a vonatkozó API-t.

Ha a feladata a Claude felületén lévő fájlokat érinti, külön útmutató szól arról, hogyan tölthet fel fájlt Claude-ba. Közvetlen hívásokhoz olvassa el, hogyan számítható ki az API tokenhasználata. Terminálügynökben végzett munkához olvassa el, hogyan válasszon Claude Code skilleket: ezeket más módon kell csatlakoztatni.

Az első ellenőrzéshez elegendő egyetlen kész pptx skill: vizsgálja meg a választ, töltsön le egy olyan fájlt, amelynek letöltése engedélyezett, majd nyissa meg. Az ellenőrzés után adjon hozzá egyéni skilleket, és alakítson ki hozzáférés-elkülönítést az ügyfelek között.

Ha készen áll, ismerkedjen meg az Ailoot szolgáltatással.