# Asistenti > Výpis asistentů dostupných uživateli API klíče a jejich použití v chatu. Asistent je nakonfigurovaný AI agent: model s vlastními instrukcemi, nástroji, znalostní bází a pamětí. Asistenti se vytvářejí a upravují v aplikaci AYETO; API je vypisuje, abyste si mohli jednoho vybrat a mluvit s ním přes [chat](chat.md). ## Rozsah Endpointy asistentů vyžadují rozsah `ayeto.assistant` (při vytváření klíče zobrazený jako **AYETO asistenti**), nebo klíč se všemi rozsahy (`*`). Viz [rozsahy](authentication.md#rozsahy). ## Výpis asistentů | | | |---|---| | Endpoint | `POST /api/v3/assistant/find` | | Rozsah | `ayeto.assistant` | | Limit požadavků | [default](conventions.md#limity-pozadavku) | Vrací asistenty, které uživatel API klíče může používat: - asistenty, které uživatel vytvořil, při osobním používání i v organizacích; - asistenty vlastněné skupinou, do které uživatel patří (například administrátory organizace); - asistenty sdílené s uživatelem, přímo e-mailem nebo prostřednictvím skupiny. Asistenti organizace, které uživatel nevlastní a nejsou s ním sdílení, se nevracejí, stejně jako šablony asistentů z galerie (šablona se stane asistentem, jakmile ji uživatel v aplikaci přidá). Výsledek obsahuje i asistenty, které aplikace vytváří pro svá vlastní studia: asistenta za každým Booster panelem a asistenta builderu každého workflow. Aplikace je ve svých seznamech asistentů skrývá. Chcete-li je vynechat, přidejte filtry `["booster_panel_id", "==", null]` a `["workflow_id", "==", null]` (viz [příklad](#priklad)). ### Požadavek Tělo je objekt dotazu s obvyklými poli pro [filtry, řazení a stránkování](conventions.md#filtry). Pro všechno pošlete `{}`; samotné tělo je povinné. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `filters` | pole | Ne | Podmínky filtru, viz [filtry](conventions.md#filtry) a příklady níže. Více podmínek se kombinuje pomocí AND. | | `sort_key` | řetězec | Ne | Pole, podle kterého se řadí, například `name`, `created.timestamp`, `updated.timestamp` nebo `accessed.timestamp` (naposledy použito). Výchozí: `created.timestamp`, sestupně. | | `sort_order` | celé číslo | Ne | `0` vzestupně, `1` sestupně. Výchozí `0`, když je nastaveno `sort_key`. | | `limit_from` | celé číslo | Ne | Index prvního výsledku (od nuly). Bez něj se vrátí všichni odpovídající asistenti. | | `limit_to` | celé číslo | Ne | Index za posledním výsledkem (výlučně), ne velikost stránky. | Užitečné filtry: | Cíl | Filtr | |---|---| | Jen osobní asistenti | `["organization_id", "==", null]` | | Asistenti jedné organizace | `["organization_id", "==", "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"]` | | Bez asistentů Booster panelů a builderů workflow | `["booster_panel_id", "==", null]`, `["workflow_id", "==", null]` | | Název obsahuje slovo (bez ohledu na velikost písmen) | `["name", "regex", "support"]` | | Asistenti vytvoření uživatelem (ne sdílení s ním) | `["created.user_id", "==", "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"]` | ### Odpověď `200 OK` s polem [asistentů](#asistent). ### Chyby | Stav | `detail` | Příčina | |---|---|---| | `401` | `API key is invalid` | Klíči chybí rozsah `ayeto.assistant` (a nejde o klíč se všemi rozsahy), nebo klíč není platný. | | `403` | `permission denied` | Účet uživatele nemá povoleno číst asistenty. | | `422` | chyba validace | Chybí tělo, nebo je neplatný filtr či `sort_key`. | Chyby autentizace, limitů požadavků a serveru jsou popsány v [konvencích](conventions.md#chyby). ### Příklad Vlastní asistenti uživatele (osobní, bez asistentů studií), od naposledy použitých: ```bash curl -X POST "https://ayeto.ai/api/v3/assistant/find" \ -H "uni-api-key: $AYETO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filters": [ ["organization_id", "==", null], ["booster_panel_id", "==", null], ["workflow_id", "==", null] ], "sort_key": "accessed.timestamp", "sort_order": 1, "limit_from": 0, "limit_to": 50 }' ``` ```json [ { "id": "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90", "name": "Customer support", "description": "Answers questions about orders, delivery and returns.", "avatar_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "organization_id": null, "created": {"timestamp": 1756819200000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"}, "updated": {"timestamp": 1759222800000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"}, "accessed": {"timestamp": 1759395606000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"} }, { "id": "7d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a", "name": "Contract reviewer", "description": "", "avatar_id": null, "organization_id": null, "created": {"timestamp": 1754035200000, "user_id": "6c5b4a39-2817-4f6e-9d5c-4b3a29180f7e"}, "updated": {"timestamp": 0, "user_id": null}, "accessed": {"timestamp": 0, "user_id": null} } ] ``` ## Avatar asistenta | | | |---|---| | Endpoint | `POST /api/v3/assistant/avatar/get` | | Rozsah | `ayeto.assistant` | | Limit požadavků | [default](conventions.md#limity-pozadavku) | Vrací odkaz na obrázek avatara asistenta, například abyste ho mohli zobrazit vedle odpovědí asistenta ve své aplikaci. ### Požadavek | Pole | Typ | Povinné | Popis | |---|---|---|---| | `assistant_id` | UUID | ano | Id asistenta, kterého uživatel vlastní nebo který je s ním sdílený. | ### Odpověď `200 OK` s úplnou URL obrázku avatara jako řetězcem JSON, nebo s prázdným řetězcem (`""`), když asistent avatara nemá. Odkaz funguje bez API klíče, takže ho můžete použít přímo jako zdroj obrázku; `avatar_id` ve [Výpisu asistentů](#vypis-asistentu) vám předem řekne, zda avatar existuje. ```json "https://ayeto.ai/api/v1/public/file/read?id=9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d&secret=4f1c9e2b7a6d4c3e" ``` ### Chyby | Stav | `detail` | Příčina | |---|---|---| | `401` | `API key is invalid` | Klíči chybí rozsah `ayeto.assistant` (a nejde o klíč se všemi rozsahy), nebo klíč není platný. | | `403` | `permission denied` | Účet uživatele nemá povoleno číst asistenty. | | `403` | `not shared with user` | Asistent není ve vlastnictví uživatele ani s ním není sdílený. | | `404` | `Assistant not found` | Asistent s tímto id neexistuje. | | `422` | chyba validace | `assistant_id` chybí nebo není UUID. | ### Příklad ```bash curl -X POST "https://ayeto.ai/api/v3/assistant/avatar/get" \ -H "uni-api-key: $AYETO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"assistant_id": "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90"}' ``` ## Asistent Objekt, který vrací [Výpis asistentů](#vypis-asistentu). Instrukce, model, nástroje a znalostní báze asistenta API nezpřístupňuje. | Pole | Typ | Povinné | Popis | |---|---|---|---| | `id` | UUID | Ano | Id asistenta. Předejte ho jako `assistant_id` do [chatu](chat.md). | | `name` | řetězec | Ano | Zobrazovaný název. | | `description` | řetězec | Ano | Krátký popis; může to být prázdný řetězec. | | `avatar_id` | UUID nebo null | Ne | Id souboru s obrázkem avatara; `null`, když asistent avatara nemá. Odkaz na něj získáte pomocí [Avatar asistenta](#avatar-asistenta). | | `organization_id` | UUID nebo null | Ne | Organizace, do které asistent patří; `null` u osobního asistenta. | | `created`, `updated`, `accessed` | objekt | Ano | Metadata `{timestamp, user_id}`, viz [společná pole](conventions.md#spolecna-pole). `accessed` je okamžik, kdy byl asistent naposledy použit v chatu; `0`, pokud od začátku zaznamenávání použit nebyl. | ## Chat s asistentem Chcete-li mluvit s asistentem, pošlete do [chatu](chat.md) jeho `id` jako `assistant_id` místo `model`. Použije se vlastní model, instrukce, nástroje a znalosti asistenta a nová konverzace se s ním propojí: objeví se s tímto `assistant_id` ve [výpisu konverzací](conversations.md#vypis-konverzaci). - Pro chat s asistentem stačí, když je sdílený jen pro čtení. - Asistent, který patří organizaci, běží v této organizaci (pokud nepošlete jiné `organization_id`), takže uživatel musí být členem nebo administrátorem této organizace. Asistent sdílený s uživatelem z organizace, do které nepatří, se ve výpisu objeví, ale chat s ním se odmítne s `403`. - Chat vyžaduje na klíči rozsah `ayeto.chat`.