Tworzenie z agentami AI

Jeśli do tworzenia rozwiązań na platformie DUST używasz agenta AI do programowania (Claude Code, Cursor, Copilot lub podobnego), ta strona jest jego punktem wejścia. Wszystko, co się tu znajduje, to stabilne publiczne adresy URL, które możesz przekazać agentowi.

Zacznij tutaj

Przekaż agentowi	Do czego
/skills/dice-api-integration/SKILL.md	Wywoływanie DUST API: uwierzytelnianie, nagłówki kontekstu, rekordy, identyfikatory, pliki, udostępnianie, przesyłki
/skills/dust-go-connect-integration/SKILL.md	Dodawanie skanowania DUST do aplikacji internetowej działającej w aplikacji mobilnej DUST Go
/llms.txt	Mapa wszystkich stron, z której agent może wybrać to, czego potrzebuje
/llms-full.txt	Cała dokumentacja jako jeden dokument tekstowy
/openapi.json	Dokładny kontrakt żądań i odpowiedzi

Cztery fakty, w których agenci się mylą

Jeśli nie umieścisz w kontekście agenta niczego innego, umieść te informacje. Każdy z tych punktów dotyczy żądania, które API odrzuca, zamiast po cichu je tolerować, więc pomyłka powoduje natychmiastowe niepowodzenie integracji.

1. Pole zakresu skanowania przy identyfikacji to searchTeamIds — tablica JSON z UUID zespołów. W żądaniu nie ma pola searchGroupIds. Ładunki identyfikacji odrzucają niezadeklarowane właściwości, więc błędna pisownia powoduje niepowodzenie całego żądania z kodem 400 INVALID_REQUEST. Jedyną zachowaną starszą nazwą z group jest nagłówek Dust-Ctx-Grp-Id, akceptowany alias nagłówka Dust-Ctx-Team-Id.
2. Pole tags przy weryfikacji jest wymagane i jest tablicą obiektów: [{"tagId": "…", "tagType": "DUST"}], a nie tablicą ciągów z ID. W treściach multipart jest zakodowane jako JSON.
3. Nieudana identyfikacja to odpowiedź ze statusem błędu. 404 IDENTIFIER_NOT_FOUND oznacza, że nic nie pasuje; 503 SCAN_SEARCH_INCOMPLETE oznacza, że nie udało się ukończyć wyszukiwania i należy ponowić próbę; 400 SCAN_LOW_KEYPOINTS oznacza konieczność ponownego skanowania. Wygenerowany kod, który traktuje każdy status spoza zakresu 2xx jako wyjątek, zgłasza awarie, do których nigdy nie doszło. Wzorcowa tabela znajduje się w artykule Błędy i wyniki skanowania.
4. Dane uwierzytelniające pozostają na serwerze. Token Bearer DUST zapewnia pełny dostęp konta usługi i nic nie zawęża go na potrzeby sesji przeglądarki. Obsługiwany układ to przeglądarka → backend klienta → DUST API. Nigdy nie generuj komponentu, który przyjmuje token DUST jako prop.

Wzorcowe przykłady

To są struktury do skopiowania. Oba bloki są wykonywane na serwerze.

// Identify: which Thread does this capture belong to?
const form = new FormData();
form.set("tagType", "DUST");
form.set("data", captureBlob);                              // binary, not base64
form.set("searchTeamIds", JSON.stringify(allowedTeamIds));  // NOT searchGroupIds

const response = await fetch(`${apidUrl}/api/v1/tags/identify`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Dust-Ctx-Org-Id": organizationId,
    // "Dust-Ctx-Team-Id": teamId,  // optional; omit for the org's root Team
  },
  body: form,
});
const body = await response.json();

if (response.ok) {
  // body.type is "identified" | "matches" | "label"
} else if (body.code === "IDENTIFIER_NOT_FOUND") {
  // An answer: nothing matched. Not a failure.
} else if (body.code === "SCAN_SEARCH_INCOMPLETE") {
  // Retry — the item may well be enrolled.
}

// Verify: is this capture the item it claims to be?
const form = new FormData();
form.set("threadId", threadId);
form.set("tagType", "DUST");
form.set("data", captureBlob);
form.set("tags", JSON.stringify([{ tagId, tagType: "DUST" }])); // required, objects

const response = await fetch(`${apidUrl}/api/v1/tags/verify`, {
  method: "POST",
  headers: { Authorization: `Bearer ${token}`, "Dust-Ctx-Org-Id": organizationId },
  body: form,
});
const body = await response.json();

// One candidate: a mismatch is an error status.
// Two or more: a mismatch is HTTP 200 with { success: false } — read `success`.

Kompletna, gotowa do uruchomienia sekwencja end-to-end (wymiana tokenu, wykrywanie organizacji, wykrywanie zespołów, tworzenie, ponowny odczyt) bez zależności od pakietów znajduje się w przewodniku szybkiego startu API.

llms.txt

Zgodnie z konwencją llms.txt katalog główny witryny udostępnia:

Plik	Zawartość
/llms.txt	Mapa witryny: każda strona z jednowierszowym opisem oraz odnośniki do specyfikacji OpenAPI, interaktywnej dokumentacji referencyjnej i pakietów npm
/llms-full.txt	Pełna treść dokumentacji jako jeden dokument tekstowy
/llms-small.txt	Zminimalizowany wariant dla mniejszych okien kontekstu

Wskaż agentowi /llms.txt, aby sam wybrał strony, lub przekaż mu /llms-full.txt, gdy potrzebuje pełnego obrazu. Linki w połączonych plikach są bezwzględnymi adresami URL prowadzącymi z powrotem do strony i sekcji, z których pochodzą, dzięki czemu agent może zacytować wykorzystane źródło.

Specyfikacja OpenAPI

Wiążącym opisem interfejsu API jest dokument OpenAPI 3:

• Na żywo z serwera API: https://apid.dustid.io/api/openapi.json
• Kopia utworzona podczas kompilacji w tej witrynie: /openapi.json
• Interaktywna dokumentacja referencyjna (Scalar): https://apid.dustid.io/api/docs

Kopia w tej witrynie obejmuje publiczny interfejs: usunięto z niej operacje wewnętrzne DUST. Korzystaj z dokumentu na żywo, gdy musisz mieć pewność, że opisujesz serwer, który faktycznie wywołujesz.

Umiejętności integracyjne

Umiejętność (skill) to pojedynczy plik Markdown w formacie SKILL.md (frontmatter YAML z polami name i description, a po nim instrukcje), który uczy agenta jednej integracji od początku do końca — uwierzytelniania, nagłówków, podstawowych przepływów i sposobów obsługi błędów. Umiejętności są samowystarczalne: agent, który ma tylko plik umiejętności, może ukończyć integrację.

dice-api-integrationUwierzytelnianie (klucz API → bearer), ustawianie nagłówków kontekstu i obsługa podstawowych przepływów API: tworzenie rekordów, wiązanie identyfikatorów, przesyłanie plików, udostępnianie, wysyłka.PobierzKopia

dust-go-connect-integrationSkanowanie identyfikatorów DUST z poziomu aplikacji internetowej działającej w aplikacji mobilnej DUST Go za pomocą @dustid/dust-go-connect.PobierzKopia

Instalowanie umiejętności

1. Pobierz plik umiejętności ze stabilnego adresu URL podanego powyżej (np. /skills/dice-api-integration/SKILL.md).

2. W przypadku Claude Code umieść go w swoim projekcie w lokalizacji .claude/skills/dice-api-integration/SKILL.md (nazwa katalogu odpowiada wartości name umiejętności). Claude wykrywa go automatycznie i wczytuje, gdy zadanie do niego pasuje.

3. W przypadku innych agentów dołącz plik do kontekstu lub promptu systemowego agenta — plik jest zwykłym, samowystarczalnym dokumentem Markdown.

Co oznacza, a czego nie oznacza „wygenerowany”

Każdy plik umiejętności zawiera blok pochodzenia, który podaje wersję dokumentacji, wersję specyfikacji OpenAPI, liczbę zawartych w niej ścieżek oraz skrót dokładnej publicznej specyfikacji, na podstawie której zbudowano plik. Te cztery informacje pozwalają ustalić, który etap rozwoju API opisuje twoja kopia i czy dwie kopie pochodzą z tej samej specyfikacji.

Warto dokładnie rozumieć, co to daje:

Część umiejętności	Pochodzenie	Co może stać się nieaktualne
Indeks punktów końcowych w dice-api-integration	Generowany z publicznej specyfikacji OpenAPI podczas kompilacji	Nic — są to ścieżki, metody i podsumowania z samej specyfikacji
Wiersze z wersją i skrótem	Generowane podczas kompilacji	Nic
Cała reszta: instrukcje uwierzytelniania, nazwy parametrów, struktury ładunków, zachowanie SDK, obsługa błędów	Pisana ręcznie	Wszystko, co API zmieni bez odpowiadającej temu zmiany w dokumentacji

Sygnatura kompilacji nie jest wynikiem testu

Aktualny baner wersji świadczy o tym, że plik został zbudowany, a nie o tym, że zawarte w nim przykłady zostały wykonane na wdrożonym API. Traktuj wygenerowany indeks punktów końcowych jako pomoc w odkrywaniu — dowód, że dana ścieżka istnieje — a każdy przykład jako coś, co przed wdrożeniem trzeba zweryfikować ze specyfikacją OpenAPI lub w jednorazowym środowisku testowym. Jeśli przykład i specyfikacja są ze sobą sprzeczne, rozstrzyga specyfikacja; daj nam też znać, abyśmy mogli poprawić opis.

Sprawdzanie wygenerowanego kodu

Krótka lista kontrolna dla osoby przeglądającej to, co wygenerował agent:

• Każda ścieżka i metoda występuje w specyfikacji. Brak wymyślonych punktów końcowych.
• Wywołania /api/v1/* zawierają Authorization: Bearer; każde wywołanie w zakresie organizacji zawiera też Dust-Ctx-Org-Id.
• Identyfikacja wysyła searchTeamIds, nigdy searchGroupIds.
• Weryfikacja wysyła tags jako tablicę obiektów { tagId, tagType }.
• Obsługa błędów rozgałęzia się według pola code, nigdy według tekstu message, i odróżnia „brak dopasowania” od „spróbuj ponownie” i od „zeskanuj ponownie”.
• Żaden klucz API ani token Bearer nie trafia do niczego, co jest wysyłane do przeglądarki lub klienta mobilnego.
• Raporty skanu (scan.scanId lub detail.scan.scanId w przypadku niepowodzenia) są zapisywane.
• Kod 401 wywołuje jedno odświeżenie i ponowienie próby, a nie pętlę.

Pakiety npm

• @dustid/dust-go-connect — most skanowania DUST Go dla aplikacji internetowych (zobacz Integracja z DUST Go).
• @dustid/apid-client — typowany klient API w języku TypeScript. Nie jest dostępny w publicznym rejestrze npm; informacje o dostępności i wymaganiach wstępnych znajdziesz w artykule Klient TypeScript. Agent nie powinien generować polecenia instalacji tego pakietu.