Référence SDK / API

La façon dont vous communiquez avec la passerelle Crew dépend de l'endroit où votre code s'exécute. Cette page fait correspondre chaque surface à l'API appropriée.

Il n'existe aucun paquet npm de client de passerelle TypeScript publié. Les noms de méthodes kirocrew-client ci-dessous décrivent la surface canonique de l'API Gateway — les mêmes points de terminaison que tout client (y compris fetch brut) utilise.

Les pages d'interface utilisateur du tableau de bord importent des hooks à portée de permission depuis @kirocrew/app-sdk, résolus à l'exécution via la carte d'importation de l'hôte :

import { useAppApi, useAppEvents } from '@kirocrew/app-sdk'

function MyPage() {
  const api = useAppApi()               // permission-scoped GET/POST/PUT/PATCH/DELETE
  useAppEvents('notification', (e) => console.log(e))
  // ...
}

useAppApi() retourne un client dont les méthodes (get, post, put, patch, del) appellent les points de terminaison de la Gateway listés ci-dessous, à portée de votre liste d'autorisations permissions.api. Les chemins hors portée lancent une erreur. L'hôte injecte l'authentification automatiquement.

Importez depuis @kirocrew/app-sdk/ui :

Card, CardTitle, Btn, SendBtn, Input, SearchInput, Badge, AimBadge, StatCard, Skeleton, ContentSkeleton, EmptyState, PageHeader, Toggle, InfoTip, SegmentedControl, MarkdownRenderer.

pip install kirocrew-client

Client asynchrone autonome utilisant aiohttp. Aucune dépendance au paquet principal Crew.

from kirocrew_client import CrewClient

async with CrewClient(app_name="my-app") as mc:
    ok = await mc.ping()
    slots = await mc.list_slots()
    task_id = await mc.dispatch_agent_async("my-agent", "Analyze ticket T-123")
    result = await mc.get_task_result(task_id)

CrewClient(
    base_url="",              # default: http://localhost:{KIROCREW_PORT or 5476}
    token="",                 # optional for localhost
    app_name="",              # enables app-scoped storage + auto-auth
    timeout=30,               # request timeout seconds
    max_retries=3,
    retry_base_delay=1.0,
    message_length_limit=40000,
    on_auth_expired=None,     # async callback returning new token
)

Lorsque app_name est défini et qu'aucune authentification explicite n'est fournie, le client lit automatiquement le secret de l'application depuis ~/.kiro/crew/apps/{name}/.app_secret et l'échange contre un jeton à courte durée de vie via POST /api/apps/{name}/token.

Les noms de méthodes ci-dessous utilisent snake_case pour Python; les noms TypeScript sont indiqués pour la lisibilité. Les mêmes points de terminaison sont accessibles via fetch() brut depuis Node ou un navigateur.

Toutes les méthodes d'abonnement retournent une fonction de désabonnement.

Types d'événements (liste partielle) : chat_chunk, chat_done, chat_message, chat_error, tool_call, notification, slots, slot_title, dashboard, log, refresh, approval, subagent_done, task_update, task_complete, proactive_notification, app_reload, error.

Contexte silencieux en arrière-plan — apparaît au prochain tour initié par l'utilisateur sans déclencher de réponse.

Options : { source?: string, ephemeral?: boolean, maxAge?: number }.

Pour les serveurs dorsaux d'application : vérifier qu'une requête a été signée par le proxy inverse de la passerelle.

La signature est HMAC-SHA256(timestamp:method:/api/path[?query]:sha256(body)) avec le secret de l'application comme clé. Les horodatages doivent se situer dans une plage de ±60 s par rapport à maintenant. Utilise une comparaison à temps constant.

Pour les opérations de cycle de vie des applications au-delà des enveloppes du client :

kirocrew-client fournit également deux aides pour l'automatisation de l'installation.

Valider et sérialiser app.json :

from kirocrew_client import AppManifest

m = AppManifest.from_dict({"name": "my-app", "version": "1.0.0", ...})
errors = m.validate()   # list[str] — empty if valid
data = m.to_dict()

Gérer l'installation de l'application via l'API REST de la Gateway :

from kirocrew_client import CrewClient, AppLifecycle

async with CrewClient() as mc:
    lifecycle = AppLifecycle(mc)
    await lifecycle.install("/path/to/my-app")
    await lifecycle.enable("my-app")
    await lifecycle.disable("my-app")
    await lifecycle.uninstall("my-app")
    apps = await lifecycle.list()

Gérer le processus de la passerelle Crew (démarrage, arrêt, vérification de l'état) :

from kirocrew_client import GatewayManager

gm = GatewayManager(port=5476)
await gm.start()
healthy = await gm.is_healthy()
await gm.stop()

Toutes les erreurs de kirocrew-client sont des instances CrewError avec code, message, status, body.

from kirocrew_client import CrewError

try:
    await mc.send_message("slot-1", "hello")
except CrewError as e:
    print(e.code, e.message, e.status)