API Agentů

Agenti jsou přizpůsobitelní AI asistenti, kteří mohou provádět úkoly, analyzovat data a automatizovat pracovní postupy. Použijte Agents API k programovému vytváření a správě agentů pro vaši organizaci.

Základní URL: https://us.teamday.ai/api/v1/agents

Ověřování: Osobní přístupový token vyžadován

Přehled endpointů

Metoda	Endpoint	Popis	Status
GET	`/agents`	Vypsat všechny agenty	✅ Funguje
POST	`/agents`	Vytvořit nového agenta	✅ Funguje
GET	`/agents/[id]`	Získat detaily agenta	✅ Funguje
PATCH	`/agents/[id]`	Aktualizovat agenta	✅ Funguje
DELETE	`/agents/[id]`	Smazat agenta	✅ Funguje
POST	`/agents/[id]/execute`	Spustit agenta	🔴 Nefunguje (500 chyba)

Výsledky testů: 5/6 endpointů funkčních (83%)

Objekt Agent

Vlastnosti

{
  id: string              // ID agenta (formát: agent_xxx)
  name: string            // Zobrazovaný název
  role: string            // Role/účel agenta
  systemPrompt: string    // Systémové instrukce
  visibility: string      // "private" | "organization" | "public"
  organizationId: string  // Organizace vlastníka
  userId: string          // ID uživatele tvůrce
  createdAt: string       // ISO 8601 časová značka
  updatedAt: string       // ISO 8601 časová značka
  deletedAt?: string      // Časová značka měkkého smazání (pokud je smazáno)
}

Příklad objektu

{
  "id": "agent_abc123",
  "name": "Výzkumný asistent",
  "role": "Výzkum a analýza dat",
  "systemPrompt": "Jste užitečný výzkumný asistent se zaměřením na analýzu dat a sumarizaci.",
  "visibility": "private",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T10:30:00Z"
}

Vypsat agenty

Načtěte všechny agenty vaší organizace.

Požadavek

GET /api/v1/agents

Záhlaví:

Authorization: Bearer td_xxxxx...

Parametry dotazu: Žádné

Odpověď

Úspěch (200 OK):

[
  {
    "id": "agent_abc123",
    "name": "Výzkumný asistent",
    "role": "Výzkum a analýza",
    "systemPrompt": "Jste užitečný výzkumný asistent.",
    "visibility": "private",
    "organizationId": "org_xyz789",
    "userId": "user_456",
    "createdAt": "2025-12-09T10:30:00Z",
    "updatedAt": "2025-12-09T10:30:00Z"
  },
  {
    "id": "agent_def456",
    "name": "Kontrolor kódu",
    "role": "Kontrola kódu a návrhy",
    "systemPrompt": "Jste odborný kontrolor kódu.",
    "visibility": "organization",
    "organizationId": "org_xyz789",
    "userId": "user_789",
    "createdAt": "2025-12-08T15:20:00Z",
    "updatedAt": "2025-12-09T09:15:00Z"
  }
]

Prázdný výsledek:

[]

Chyba (401 Neautorizováno):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Neplatný nebo vypršelý token"
}

Příklad

curl https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Vytvořit agenta

Vytvořte nového AI agenta pro vaši organizaci.

Požadavek

POST /api/v1/agents

Záhlaví:

Authorization: Bearer td_xxxxx...
Content-Type: application/json

Tělo:

{
  "name": "Výzkumný asistent",
  "role": "Výzkum a analýza dat",
  "systemPrompt": "Jste užitečný výzkumný asistent se zaměřením na analýzu dat a sumarizaci.",
  "visibility": "private"
}

Povinná pole:

name (string) - Zobrazovaný název agenta
systemPrompt (string) - Systémové instrukce pro agenta

Volitelná pole:

role (string) - Popis role agenta (výchozí: prázdný řetězec)
visibility (string) - Úroveň přístupu: "private", "organization" nebo "public" (výchozí: "private")

Odpověď

Úspěch (201 Vytvořeno):

{
  "id": "agent_abc123",
  "name": "Výzkumný asistent",
  "role": "Výzkum a analýza dat",
  "systemPrompt": "Jste užitečný výzkumný asistent se zaměřením na analýzu dat a sumarizaci.",
  "visibility": "private",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T10:30:00Z"
}

Chyba (400 Chybný požadavek):

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Chybí povinné pole: name"
}

Chyba (401 Neautorizováno):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Neplatný nebo vypršelý token"
}

Příklad

curl -X POST https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Výzkumný asistent",
    "role": "Výzkum a analýza dat",
    "systemPrompt": "Jste užitečný výzkumný asistent se zaměřením na analýzu dat a sumarizaci.",
    "visibility": "private"
  }'

Získat agenta

Načtěte detaily konkrétního agenta podle ID.

Požadavek

GET /api/v1/agents/[id]

Záhlaví:

Authorization: Bearer td_xxxxx...

Parametry cesty:

id (string) - ID agenta (formát: agent_xxx)

Odpověď

Úspěch (200 OK):

{
  "id": "agent_abc123",
  "name": "Výzkumný asistent",
  "role": "Výzkum a analýza dat",
  "systemPrompt": "Jste užitečný výzkumný asistent se zaměřením na analýzu dat a sumarizaci.",
  "visibility": "private",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T10:30:00Z"
}

Chyba (404 Nenalezeno):

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Agent nenalezen"
}

Chyba (401 Neautorizováno):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Neplatný nebo vypršelý token"
}

Příklad

curl https://us.teamday.ai/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Aktualizovat agenta

Aktualizujte vlastnosti existujícího agenta.

Požadavek

PATCH /api/v1/agents/[id]

Záhlaví:

Authorization: Bearer td_xxxxx...
Content-Type: application/json

Parametry cesty:

id (string) - ID agenta (formát: agent_xxx)

Tělo (všechna pole jsou volitelná):

{
  "name": "Aktualizovaný výzkumný asistent",
  "role": "Pokročilý výzkum a analýza",
  "systemPrompt": "Jste odborný výzkumný asistent s hlubokými znalostmi analýzy dat.",
  "visibility": "organization"
}

Aktualizovatelná pole:

name (string) - Zobrazovaný název agenta
role (string) - Popis role agenta
systemPrompt (string) - Systémové instrukce
visibility (string) - Úroveň přístupu: "private", "organization" nebo "public"

Poznámka: Zahrňte pouze pole, která chcete aktualizovat. Vynechaná pole zůstávají nezměněna.

Odpověď

Úspěch (200 OK):

{
  "id": "agent_abc123",
  "name": "Aktualizovaný výzkumný asistent",
  "role": "Pokročilý výzkum a analýza",
  "systemPrompt": "Jste odborný výzkumný asistent s hlubokými znalostmi analýzy dat.",
  "visibility": "organization",
  "organizationId": "org_xyz789",
  "userId": "user_456",
  "createdAt": "2025-12-09T10:30:00Z",
  "updatedAt": "2025-12-09T14:45:00Z"
}

Chyba (404 Nenalezeno):

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Agent nenalezen"
}

Chyba (400 Chybný požadavek):

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Neplatná hodnota visibility. Musí být: private, organization nebo public"
}

Příklad

curl -X PATCH https://us.teamday.ai/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aktualizovaný výzkumný asistent",
    "visibility": "organization"
  }'

Smazat agenta

Měkké smazání agenta. Agent je označen jako smazaný, ale není trvale odstraněn z databáze.

Požadavek

DELETE /api/v1/agents/[id]

Záhlaví:

Authorization: Bearer td_xxxxx...

Parametry cesty:

id (string) - ID agenta (formát: agent_xxx)

Odpověď

Úspěch (200 OK):

{
  "success": true,
  "message": "Agent úspěšně smazán"
}

Chyba (404 Nenalezeno):

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Agent nenalezen"
}

Chyba (401 Neautorizováno):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Neplatný nebo vypršelý token"
}

Příklad

curl -X DELETE https://us.teamday.ai/api/v1/agents/agent_abc123 \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Poznámky

Chování měkkého smazání:

Agent je označen pomocí deletedAt časové značky
Agent se již nezobrazuje v seznamech
Agent nemůže být načten ani aktualizován
Historie spuštění je zachována
Nemůže být obnovena přes API (kontaktujte podporu pro obnovení)

Alternativa k smazání:

Zvažte aktualizaci visibility na "private" pro skrytí organizace
Aktualizujte name na předponu “[Archived]“

Spustit agenta (Aktuálně není k dispozici)

Status: 🔴 NEFUNGUJE - 500 Interní chyba serveru

Spusťte agenta se zprávou a obdržíte odpověď.

Požadavek

POST /api/v1/agents/[id]/execute

Záhlaví:

Authorization: Bearer td_xxxxx...
Content-Type: application/json

Parametry cesty:

id (string) - ID agenta (formát: agent_xxx)

Tělo:

{
  "message": "Analyzujte tato data a poskytněte poznatky",
  "stream": false
}

Pole:

message (string, povinné) - Zpráva uživatele pro agenta
stream (boolean, volitelné) - Povolte streamování odpovědi (výchozí: false)

Známý problém

Současné chování:

curl -X POST https://us.teamday.ai/api/v1/agents/agent_abc123/execute \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "hello",
    "stream": false
  }'

Odpověď:

{
  "error": true,
  "statusCode": 500,
  "statusMessage": "Internal Server Error",
  "message": "Spuštění chatu selhalo"
}

Hlavní příčina: Interní endpoint /api/claude-code/chat vrací 500 chyb.

Dočasné řešení: Použijte webové rozhraní na us.teamday.ai pro spuštění agenta, dokud to nebude vyřešeno.

Sledování: Toto je známý kritický problém a je aktivně vyšetřován.

Očekávané chování (Po opravě)

Odpověď bez streamování:

{
  "executionId": "exec_xyz789",
  "agentId": "agent_abc123",
  "response": "Na základě mé analýzy dat...",
  "status": "completed",
  "createdAt": "2025-12-09T15:30:00Z",
  "completedAt": "2025-12-09T15:30:45Z"
}

Odpověď se streamováním:

data: {"type":"token","content":"Na"}
data: {"type":"token","content":" základě"}
data: {"type":"token","content":" mé"}
...
data: {"type":"done","executionId":"exec_xyz789"}

Úrovně viditelnosti

Agenti podporují tři úrovně viditelnosti, které řídí, kdo je může vidět a používat:

Soukromé

Úroveň: "private"

Přístup:

Viditelné pouze tvůrci
Pouze tvůrce může provést
Není viditelné v seznamu agentů organizace

Případy použití:

Osobní asistenti
Experimentální agenti
Citlivé pracovní postupy

Organizace

Úroveň: "organization"

Přístup:

Viditelné všem členům organizace
Všichni členové mohou provádět
Zobrazuje se v sdílených agentech organizace

Případy použití:

Týmová spolupráce
Sdílené znalostní báze
Nástrojů pro celou firmu

Veřejné (Budoucnost)

Úroveň: "public"

Přístup:

Viditelné všem (budoucí funkce)
Kdokoli může provádět (budoucí funkce)
Uvedeno na veřejném tržišti agentů (budoucí funkce)

Případy použití:

Agenti sdílení komunity
Open-source nástroje
Veřejné demo

Status: Zatím není implementováno. V současné době se zachází stejně jako organization.

Nejlepší praktiky

Návrh agenta

Systémové prompty:

Buďte specifičtí ohledně role agenta a schopností
Zahrňte příklady požadovaného chování
Nastavte jasné hranice toho, co by agent měl/neměl dělat
Zůstaňte pod 2000 znaky pro optimální výkon

Příklad:

{
  "systemPrompt": "Jste asistent pro kontrolu kódu zaměřený na Python. Zaměřte se na:\n1. Kvalitu a čitelnost kódu\n2. Optimalizace výkonu\n3. Bezpečnostní zranitelnosti\n4. Osvědčené postupy\n\nPoskytujte konstruktivní zpětnou vazbu s konkrétními příklady."
}

Konvence pojmenování

Názvy agentů:

Použijte popisné, akčně orientované názvy
Zahrňte specialitu nebo doménu agenta
Zůstaňte pod 50 znaky

Dobré příklady:

“Kontrolor kódu Python”
“Asistent zákaznické podpory”
“Agent analýzy dat”

Vyhněte se:

Generickým názvům jako “Agent 1”, “Můj agent”
Velmi dlouhým názvům, které se v UI zkrátí

Bezpečnost

Viditelnost:

Výchozí "private" pro nové agenty
Používejte "organization" pouze pro agenty ověřené týmem
Zkontrolujte systémové prompty před zpřístupněním v celé organizaci

Citlivá data:

Nezahrnujte API klíče nebo přihlašovací údaje v systémových promptech
Místo toho použijte [správu tajemství TeamDay
Agenti dědí oprávnění uživatele - správně vymezete tokeny

Výkon

Aktualizace agenta:

Změny systemPrompt se projeví okamžitě při dalším spuštění
Není potřeba znovu vytvářet agenta pro aktualizaci chování
Zvažte verzování zahrnutím verze do názvu agenta (např. “Výzkumný asistent v2”)

Omezení sazby:

Ačkoli neexistují formální limity, vyhněte se vytváření 100+ agentů
Znovu použijte agenty s různými zprávami místo vytváření duplikátů
Odstraňte nepoužívané agenty, aby byla organizace čistá

Společné vzory

Agent s více účely

Vytvořte jednoho agenta, který zpracovává více souvisejících úkolů:

curl -X POST https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inženýrský asistent",
    "role": "Kontrola kódu, dokumentace a ladění",
    "systemPrompt": "Jste inženýrský asistent. V závislosti na úkolu:\n- Kontrola kódu: Zaměřte se na kvalitu, bezpečnost, výkon\n- Dokumentace: Napište jasnou, stručnou dokumentaci s příklady\n- Ladění: Analyzujte chyby a navrhněte opravy\n\nPřizpůsobte svou odpověď konkrétnímu požadavku uživatele.",
    "visibility": "organization"
  }'

Specializovaný agent

Vytvořte fokusované agenty pro konkrétní domény:

curl -X POST https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Optimátor SQL dotazů",
    "role": "Optimalizace a ladění SQL",
    "systemPrompt": "Jste odborný optimátor SQL. Analyzujte dotazy pro:\n- Použití indexů\n- Účinnost spojů\n- Optimalizaci plánu dotazů\n- Osvědčené postupy pro cílovou databázi (PostgreSQL, MySQL, atd.)\n\nPoskytujte konkrétní, praktická doporučení.",
    "visibility": "private"
  }'

Týmová spolupráce

Sdílejte agenty v celé organizaci:

# Vytvořit sdíleného agenta
curl -X POST https://us.teamday.ai/api/v1/agents \
  -H "Authorization: Bearer $TEAMDAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pomocník standup týmu",
    "role": "Organizace denního standup",
    "systemPrompt": "Pomozte týmům organizovat denní standupy. Formátujte aktualizace jasným a stručným způsobem:\n- Co bylo dosaženo včera\n- Plány na dnes\n- Jakékoli blokátory\n\nZůstaňte stručný a praktičný.",
    "visibility": "organization"
  }'

Zpracování chyb

Běžné chyby

400 Chybný požadavek:

Chybí povinná pole (name, systemPrompt)
Neplatná hodnota visibility
Poškozený JSON

401 Neautorizováno:

Chybí Authorization záhlaví
Neplatný nebo vypršelý token
Token nemá požadovaná oprávnění

404 Nenalezeno:

ID agenta neexistuje
Agent byl smazán
Chybná organizace (agent patří jiné organizaci)

500 Interní chyba serveru:

Problémy s připojením k databázi
Služba dočasně není dostupná
Kontaktujte podporu, pokud potrvá

Formát chybové odpovědi

Všechny chyby mají tuto strukturu:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Podrobný popis chyby"
}

Strategie opakování

Doporučený přístup:

async function createAgentWithRetry(agentData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('https://us.teamday.ai/api/v1/agents', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(agentData)
      })

      if (!response.ok) {
        const error = await response.json()

        // Neopakujte chyby klienta (4xx)
        if (response.status >= 400 && response.status < 500) {
          throw new Error(error.message)
        }

        // Opakujte chyby serveru (5xx)
        if (i === maxRetries - 1) throw new Error(error.message)

        // Exponenciální zpoždění
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000))
        continue
      }

      return await response.json()

    } catch (err) {
      if (i === maxRetries - 1) throw err
    }
  }
}

Související zdroje

Ověřování - Nastavení PAT tokenu a bezpečnost
API Spuštění - Sledování historie spuštění agenta
API Úloh - Správa agentských úkolů a pracovních postupů
Reference chyb - Kompletní dokumentace kódů chyb

Potřebujete pomoc?

Problémy s agenty?

Zkontrolujte reference chyb pro odstraňování problémů
Ověřte, že token má správná oprávnění
Nejprve testujte jednoduchého agenta

Otázky?

📧 E-mail: support at teamday.ai
💬 Discord: Připojit se ke komunitě
🐛 Hlásit chyby: GitHub Issues

Poslední aktualizace: 9. prosince 2025