> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# KI-Agenten

> Betriebsregeln und Workflow-Muster für Agenten, die die Youka-CLI oder -API aufrufen

Youka ist dafür ausgelegt, von Agenten gesteuert zu werden. Jeder CLI-Befehl gibt einen maschinenlesbaren JSON-Umschlag zurück, jeder Schreibvorgang unterstützt Idempotency-Keys, und die öffentliche API bietet dieselbe Oberfläche mit derselben Semantik. Diese Seite sammelt die Betriebsregeln, die ein Agent-Autor benötigt, bevor er Youka in einen Workflow verdrahtet.

## Erste Schritte

Wenn du zum ersten Mal einen Agenten einrichtest, installiere zuerst die Youka CLI und danach die Youka-Karaoke-Skill:

```bash theme={null}
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
```

Damit erhält der Agent eine sofort einsatzbereite Youka-Skill, die durch die CLI unterstützt wird. Sobald das installiert ist, nutze die Workflow-Muster unten, um Karaoke-Videos zu erstellen, den Stil anzupassen und MP4-Dateien sicher zu exportieren.

### Deinen Agenten prompten

Nach der Installation von CLI und Skill kannst du deinem Agenten eine direkte Aufgabe wie diese geben:

<CodeGroup>
  ```text local-file theme={null}
  Use Youka to create a karaoke video from /path/to/song.mp3. Transcribe the lyrics in English, use a clean karaoke subtitle style, export the final video in 1080p, and save it as ./karaoke.mp4.
  ```

  ```text url theme={null}
  Use Youka to create a karaoke video from https://example.com/song.mp4. If URL dependencies are missing, install them first. Then transcribe the lyrics automatically, use a clean karaoke subtitle style, export the final video, and save it as ./karaoke.mp4.
  ```
</CodeGroup>

## Betriebsregeln

<CardGroup cols={2}>
  <Card title="Immer --json verwenden" icon="code">
    In der CLI immer `--json` übergeben. In der API immer `Accept:
            application/json` setzen. Niemals menschenlesbare Ausgabe parsen.
  </Card>

  <Card title="Immer einen Idempotency-Key senden" icon="rotate">
    Jeder Schreibvorgang sollte einen stabilen Idempotency-Key tragen, damit Wiederholungen nach einem Timeout das ursprüngliche Ergebnis zurückgeben, statt Arbeit zu duplizieren.
  </Card>

  <Card title="Dauerhaften Zustand erneut lesen" icon="database">
    Vertraue keinen veralteten Mutationsantworten. Nach einer terminalen Aufgabe das Projekt oder den Export erneut lesen, um den finalen Zustand zu erhalten.
  </Card>

  <Card title="Mit Backoff pollen" icon="hourglass">
    Mit einem Intervall von 2–3 Sekunden starten. Für lange Jobs exponentiell erhöhen. 429-Antworten beachten.
  </Card>
</CardGroup>

## Output-Vertrag

Jeder CLI-Befehl im Modus `--json` schreibt genau einen Umschlag nach stdout.

Erfolg:

```json theme={null}
{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}
```

Fehler:

```json theme={null}
{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}
```

Exit-Codes:

| Code | Bedeutung                                                | Retry?                      |
| ---- | -------------------------------------------------------- | --------------------------- |
| `0`  | Erfolg.                                                  | N/A                         |
| `1`  | Laufzeitfehler (Netzwerk, API, Rendering).               | `error.retryable` prüfen.   |
| `2`  | Ungültige Eingabe (schlechte Flags, unlesbarer Payload). | Nein — Eingabe korrigieren. |

## End-to-end-Workflow

Der kanonische Agent-Workflow ist: Projekt erstellen, warten, exportieren, Ergebnis herunterladen. Hier ist das vollständige Muster mit CLI- und SDK-Implementierungen.

<CodeGroup>
  ```bash CLI theme={null}
  # 1. Create the project and wait for stems + lyrics sync to finish
  PROJECT_JSON=$(youka project create ./song.mp3 \
    --mode transcribe \
    --lang en \
    --wait \
    --idempotency-key "create-song-2026-04-08-001" \
    --json)

  PROJECT_ID=$(echo "$PROJECT_JSON" | jq -r '.data.projectId')

  # 2. Start and wait for an export
  EXPORT_JSON=$(youka export create "$PROJECT_ID" \
    --resolution 1080p \
    --quality high \
    --wait \
    --download \
    --output ./karaoke.mp4 \
    --idempotency-key "export-$PROJECT_ID-v1" \
    --json)

  echo "Done:" "$(echo "$EXPORT_JSON" | jq -r '.data.fileUrl')"
  ```

  ```ts SDK theme={null}
  import { YoukaClient, YoukaRequestError, YoukaTaskError } from "@youka/de/sdk";

  const client = new YoukaClient({ apiKey: process.env.YOUKA_API_KEY! });

  async function createAndExport() {
    // 1. Create the project and wait for stems + lyrics sync
    const created = await client.projects.create(
      {
        source: { type: "path", path: "./song.mp3" },
        lyricsSource: { type: "transcribe", language: "en" },
      },
      { idempotencyKey: "create-song-2026-04-08-001" },
    );

    const { project } = await client.projects.wait(created);

    // 2. Start and wait for an export
    const exportResult = await client.exports.create(
      project.id,
      { resolution: "1080p", quality: "high" },
      { idempotencyKey: `export-${project.id}-v1` },
    );

    const finalized = await client.exports.wait(exportResult);

    // 3. Download the file
    await client.exports.download(finalized, {
      output: "./karaoke.mp4",
    });
  }

  createAndExport().catch((error) => {
    if (error instanceof YoukaRequestError && error.retryable) {
      // Retry with the same idempotency keys
    }
    if (error instanceof YoukaTaskError) {
      console.error("Task failed:", error.code, error.task.error);
    }
    throw error;
  });
  ```
</CodeGroup>

## Polling-Empfehlungen

Die meisten Schreibvorgänge geben im SDK Operation-Handles zurück. Bevorzuge `client.projects.wait(...)` und `client.exports.wait(...)` und gehe nur dann auf `client.tasks.*` herunter, wenn du ausdrücklich Low-Level-Task-Zugriff brauchst.

| Job-Typ                              | Empfohlenes Anfangsintervall | Max. Wartezeit |
| ------------------------------------ | ---------------------------- | -------------- |
| Project create (stems + lyrics sync) | 3 s                          | 15 min         |
| Stem separation only                 | 3 s                          | 10 min         |
| Lyrics sync only                     | 2 s                          | 5 min          |
| Export render                        | 3 s                          | 30 min         |

In der CLI übernimmt `--wait` das Polling für dich. Im SDK verwenden die Wait-Helper standardmäßig ein Intervall von 2 s und akzeptieren `pollIntervalMs`.

<Tip>
  429-Antworten beachten. Bei Rate-Limits mindestens um den `Retry-After`-Header (oder 30 s, falls nicht vorhanden) zurückoffen.
</Tip>

## Idempotency-Keys

Jede Create- und Update-Operation unterstützt einen Idempotency-Key. Regeln:

* Verwende pro logischer Mutation einen **stabilen, eindeutigen, deterministischen** Key. Gut: `create-song-${sourceHash}`. Schlecht: eine neue UUID pro Retry.
* Verwende bei Retries **denselben** Key erneut. Der Server erkennt das Replay und gibt das ursprüngliche Ergebnis zurück.
* Keys sind pro Account scoped und laufen nach 24 Stunden ab.
* Wenn der Server `IDEMPOTENT_REPLAY_IN_PROGRESS` (HTTP 202) zurückgibt, läuft die ursprüngliche Anfrage noch. Warten und mit demselben Key erneut versuchen.

Beispielmuster:

```ts theme={null}
const key = `create-${sha256(sourceBytes)}`;

try {
  return await client.projects.create(body, { idempotencyKey: key });
} catch (error) {
  if (error instanceof YoukaRequestError && error.retryable) {
    // Safe to retry with the same key
    return await client.projects.create(body, { idempotencyKey: key });
  }
  throw error;
}
```

Siehe [API idempotency](/de/api/idempotency) für den vollständigen Vertrag.

## Fehlerbehebung

Verzweige nach `error.code` und `error.retryable`. Die häufigsten Fälle:

| Code                                  | Ursache                                                  | Aktion                                                      |
| ------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
| `INVALID_REQUEST`                     | Request-Body hat die Schema-Validierung nicht bestanden. | Payload korrigieren. Kein Retry.                            |
| `UNAUTHORIZED`                        | Fehlender oder ungültiger API-Key.                       | An den Aufrufer weitergeben. Kein Retry.                    |
| `NOT_FOUND`                           | Ressource existiert nicht oder du hast keinen Zugriff.   | Kein Retry.                                                 |
| `CONFLICT` (409)                      | Versionskonflikt oder Idempotency-Kollision.             | Mit demselben Idempotency-Key erneut versuchen.             |
| `TOO_MANY_REQUESTS` (429)             | Rate-Limit.                                              | Um `Retry-After` oder 30 s zurückoffen.                     |
| `INTERNAL_SERVER_ERROR` (500)         | Transienter Serverfehler.                                | Bis zu 3-mal mit Backoff retryen.                           |
| `IDEMPOTENT_REPLAY_IN_PROGRESS` (202) | Vorherige Anfrage läuft noch.                            | Warten und mit demselben Key erneut versuchen.              |
| `TASK_FAILED`                         | Die asynchrone Aufgabe endete mit einem Fehler.          | `error.task.error` an den Aufrufer weitergeben. Kein Retry. |
| `TASK_TIMED_OUT`                      | Die asynchrone Aufgabe hat ihr Zeitbudget überschritten. | Einmalig erneut versuchen ist sicher.                       |

## Mutierbare Felder ermitteln

Bevor du Presets mutierst, rufe das Preset-Schema ab, damit das Modell die gültigen Felder und Werttypen kennt:

<CodeGroup>
  ```bash CLI theme={null}
  # Preset body schema
  youka preset schema --json
  ```

  ```ts SDK theme={null}
  import { KaraokePresetSchema } from "@youka/de/sdk";

  const presetSchema = KaraokePresetSchema.toJSONSchema();
  ```
</CodeGroup>

Für Projekteinstellungen ist es besser, zuerst die aktuellen Projekteinstellungen zu lesen und dann einen minimalen Update-Body über `youka project settings <id> --body ...` zu senden.

Einmal pro Agent-Session abrufen und das Ergebnis cachen.

## Parallele Agenten

Wenn mehrere Agenten gleichzeitig gegen denselben Account laufen:

* Scope Idempotency-Keys sowohl auf die Agent-Identität als auch auf die logische Mutation: `agent-${agentId}-create-${sourceHash}`. Das verhindert, dass der Retry eines Agenten mit einer neuen Anfrage eines anderen kollidiert.
* Reads unbeschränkt lassen — `GET`-Requests sind günstig und haben keine Nebenwirkungen.
* Verwende pro Projekt eine einzelne Queue für `POST /projects/{projectId}/exports`, wenn du eine geordnete Export-Historie brauchst. Andernfalls können Exports in falscher Reihenfolge ankommen.

## Wie geht’s weiter

* [CLI global options](/de/cli/global-options) — alle Flags, die Agenten zur Verfügung stehen
* [SDK errors](/de/sdk/errors) — vollständige Referenz der Error-Klassen
* [API async jobs](/de/api/async-jobs) — der Polling-Vertrag
* [API idempotency](/de/api/idempotency) — der Idempotency-Vertrag