> ## 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.
# AI एजेंट्स
> Youka CLI या API को कॉल करने वाले एजेंट्स के लिए ऑपरेटिंग नियम और वर्कफ़्लो पैटर्न
Youka को एजेंट्स द्वारा संचालित किए जाने के लिए डिज़ाइन किया गया है। हर CLI कमांड एक मशीन-पठनीय JSON एन्वेलप लौटाता है, हर write idempotency keys को सपोर्ट करता है, और public API वही surface और वही semantics एक्सपोज़ करता है। यह पेज उन ऑपरेटिंग नियमों को संकलित करता है जिनकी एक एजेंट लेखक को Youka को किसी वर्कफ़्लो में जोड़ने से पहले ज़रूरत होती है।
## शुरुआत करें
यदि आप पहली बार कोई एजेंट सेट अप कर रहे हैं, तो पहले Youka CLI इंस्टॉल करें, फिर Youka karaoke skill इंस्टॉल करें:
```bash theme={null}
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
```
इससे एजेंट को CLI द्वारा समर्थित एक तैयार-उपयोग Youka skill मिल जाता है। इंस्टॉल होने के बाद, नीचे दिए गए वर्कफ़्लो पैटर्न का उपयोग करके karaoke वीडियो बनाएं, स्टाइल कस्टमाइज़ करें, और MP4 फ़ाइलें सुरक्षित रूप से एक्सपोर्ट करें।
### अपने एजेंट को प्रॉम्प्ट करें
CLI और skill इंस्टॉल करने के बाद, आप अपने एजेंट को इस तरह सीधा कार्य दे सकते हैं:
```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.
```
## ऑपरेटिंग नियम
CLI पर हमेशा `--json` पास करें। API में हमेशा `Accept:
application/json` सेट करें। कभी भी human output को parse न करें।
हर write के साथ एक स्थिर idempotency key होनी चाहिए, ताकि timeout के बाद retries मूल परिणाम लौटाएं और काम डुप्लिकेट न हो।
stale mutation responses पर भरोसा न करें। किसी terminal task के बाद, final state पाने के लिए project या export को फिर से read करें।
2–3 सेकंड के interval से शुरू करें। लंबी jobs के लिए exponentially back off करें।
429 responses का सम्मान करें।
## Output contract
`--json` मोड में हर CLI कमांड stdout पर ठीक एक envelope लिखता है।
Success:
```json theme={null}
{
"schemaVersion": "1",
"ok": true,
"data": { "id": "prj_abc123", "title": "My Song" }
}
```
Failure:
```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 | अर्थ | Retry? |
| ---- | ---------------------------------------------- | ------------------------- |
| `0` | Success. | N/A |
| `1` | Runtime error (network, API, rendering). | `error.retryable` जाँचें। |
| `2` | Invalid input (bad flags, unreadable payload). | नहीं — input ठीक करें। |
## एंड-टू-एंड वर्कफ़्लो
कैनॉनिकल एजेंट वर्कफ़्लो है: एक प्रोजेक्ट बनाएं, प्रतीक्षा करें, एक्सपोर्ट करें, परिणाम डाउनलोड करें। यहाँ CLI और SDK दोनों implementations के साथ पूरा पैटर्न है।
```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/hi/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;
});
```
## Polling मार्गदर्शन
SDK में अधिकांश writes operation handles लौटाते हैं। `client.projects.wait(...)` और `client.exports.wait(...)` को प्राथमिकता दें, और `client.tasks.*` पर तभी जाएँ जब आपको स्पष्ट रूप से low-level task access की ज़रूरत हो।
| Job type | Recommended initial interval | Max wait |
| ------------------------------------ | ---------------------------- | -------- |
| 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 |
CLI पर, `--wait` आपके लिए polling संभालता है। SDK पर, wait helpers डिफ़ॉल्ट रूप से 2 s interval उपयोग करते हैं और `pollIntervalMs` स्वीकार करते हैं।
429 responses का सम्मान करें। rate limits पर, कम से कम `Retry-After`
header जितना (या अनुपस्थित होने पर 30 s) back off करें।
## Idempotency keys
हर create और update operation एक idempotency key सपोर्ट करता है। नियम:
* हर logical mutation के लिए **stable, unique, deterministic** key इस्तेमाल करें। अच्छा: `create-song-${sourceHash}`। खराब: हर retry पर नया UUID।
* retries के दौरान **उसी** key का पुन: उपयोग करें। सर्वर replay पहचानकर मूल परिणाम लौटाता है।
* keys per-account scoped होती हैं और 24 घंटे बाद expire हो जाती हैं।
* यदि सर्वर `IDEMPOTENT_REPLAY_IN_PROGRESS` (HTTP 202) लौटाए, तो original request अभी भी चल रही है। प्रतीक्षा करें और उसी key के साथ retry करें।
Example pattern:
```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;
}
```
पूरा contract देखने के लिए [API idempotency](/hi/api/idempotency) देखें।
## Error recovery
`error.code` और `error.retryable` के आधार पर branch करें। सामान्य केस:
| Code | कारण | Action |
| ------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
| `INVALID_REQUEST` | Request body schema validation में fail हुआ। | payload ठीक करें। retry नहीं। |
| `UNAUTHORIZED` | API key missing या invalid। | caller तक surface करें। retry नहीं। |
| `NOT_FOUND` | resource मौजूद नहीं है या आपके पास access नहीं है। | retry नहीं। |
| `CONFLICT` (409) | version conflict या idempotency collision। | उसी idempotency key के साथ retry करें। |
| `TOO_MANY_REQUESTS` (429) | rate limit। | `Retry-After` या 30 s के अनुसार back off करें। |
| `INTERNAL_SERVER_ERROR` (500) | transient server failure। | backoff के साथ 3 बार तक retry करें। |
| `IDEMPOTENT_REPLAY_IN_PROGRESS` (202) | prior request अभी भी चल रही है। | प्रतीक्षा करें और उसी key के साथ retry करें। |
| `TASK_FAILED` | async task failure में समाप्त हुई। | `error.task.error` को caller तक surface करें। retry नहीं। |
| `TASK_TIMED_OUT` | async task ने अपना budget पार कर लिया। | एक बार retry करना सुरक्षित है। |
## Mutable fields की खोज
presets को mutate करने से पहले, preset schema fetch करें ताकि मॉडल valid fields और value types जान सके:
```bash CLI theme={null}
# Preset body schema
youka preset schema --json
```
```ts SDK theme={null}
import { KaraokePresetSchema } from "@youka/hi/sdk";
const presetSchema = KaraokePresetSchema.toJSONSchema();
```
project settings के लिए, पहले current project settings पढ़ना बेहतर है, फिर `youka project settings --body ...` के जरिए minimal update body सबमिट करें।
प्रति agent session एक बार fetch करें और परिणाम cache करें।
## Parallel agents
जब एक ही account के खिलाफ कई agents concurrently चल रहे हों:
* idempotency keys को **agent identity** और logical mutation — दोनों के अनुसार scope करें: `agent-${agentId}-create-${sourceHash}`। इससे एक agent का retry किसी दूसरे agent की fresh request से collide नहीं करेगा।
* reads को unbounded रखें — `GET` requests सस्ते होते हैं और उनके कोई side effects नहीं होते।
* यदि आपको ordered export history चाहिए, तो प्रति project `POST /projects/{projectId}/exports` के लिए single queue इस्तेमाल करें। अन्यथा exports out of order आ सकते हैं।
## आगे क्या
* [CLI global options](/hi/cli/global-options) — agents के लिए उपलब्ध हर flag
* [SDK errors](/hi/sdk/errors) — error classes का पूरा reference
* [API async jobs](/hi/api/async-jobs) — polling contract
* [API idempotency](/hi/api/idempotency) — idempotency contract