TL;DR
Kimi Hosted Agents exécute des tâches IA multi-étapes avec des sessions persistantes, l’exécution d’outils et des bacs à sable cloud. Ce guide vous emmène d’une clé API Kimi à une présentation de trois diapositives téléchargeable en utilisant Bash, curl et jq. Commencez par réaliser une tâche avec une requête autonome. Ajoutez ensuite un document téléversé, connectez des outils métiers et traitez les échecs qui comptent dans une application déployée.
Points clés
- Kimi Hosted Agents relie une définition d’agent, un environnement d’exécution et une session. Conservez leurs IDs tout au long du workflow.
- Commencez par un résultat réduit et vérifiable. Le premier exemple produit une présentation avec des données fictives et un calcul que vous pouvez vérifier.
- Utilisez le flux d’événements pour suivre l’exécution, puis inspectez le fichier livré. Un simple succès HTTP n’établit pas la réussite de la tâche.
- Étendez l’exemple fonctionnel avec des fichiers en entrée, des outils personnalisés ou des services MCP. Chaque intégration a ses propres exigences d’exécution et d’identifiants.
- Budgétez ensemble l’inférence, le runtime du bac à sable et l’usage des plugins, y compris les relances nécessaires pour obtenir un résultat acceptable.
Qu’est-ce que Kimi Hosted Agents ?
Moonshot AI a annoncé Kimi Hosted Agents le 5 novembre 2026, en le positionnant comme un service pour les entreprises et développeurs construisant des agents longue durée.
Le produit adopte une approche Harness as a Service. Un harness est le logiciel autour d’un modèle qui gère la progression du travail : maintien de l’état, invocation d’outils, gestion de l’exécution et reprise après interruption.
Considérez un workflow de recherche hebdomadaire. Générer du texte n’est qu’une étape. L’application peut aussi devoir récupérer des sources, traiter des fichiers, créer des graphiques, enregistrer une présentation et préserver suffisamment d’état pour reprendre après une déconnexion.
Hosted Agents fournit cette couche opérationnelle. Votre équipe définit toujours la tâche métier, choisit les intégrations et décide de ce qui constitue un résultat acceptable.
L’architecture officielle de Kimi présente l’application, les services de plateforme et le noyau d’exécution utilisés par l’exécution hébergée.
Capacités clés pour votre première intégration
- Les sessions persistantes conservent ensemble les entrées, les événements d’exécution et les sorties d’une tâche.
- Les bacs à sable cloud fournissent les outils nécessaires pour traiter des fichiers et créer des livrables.
- Les Skills et plugins encapsulent des capacités réutilisables ; des outils personnalisés et des services MCP connectent vos propres systèmes.
Votre premier jalon est une présentation que vous pouvez ouvrir et inspecter. Des spécifications runtime détaillées deviennent utiles lorsque vous ajoutez des dépendances ou migrez un workflow existant dans le bac à sable ; la référence du bac à sable documente l’environnement disponible.
Ce qu’il vous faut avant d’appeler l’API Kimi Hosted Agents
- Un compte Kimi avec accès à Hosted Agents et une clé API.
- Bash, curl et jq sur macOS, Linux ou Windows avec WSL.
- Deux terminaux : le Terminal A envoie les requêtes ; le Terminal B observe les événements d’exécution.
- Un lecteur de présentations pour ouvrir le PPTX généré.
Créez un compte Kimi et une clé API dans la zone de gestion d’API de la console. Utilisez un terminal Bash, appelé Terminal A, pour la configuration et les commandes de tâches. Gardez-le ouvert afin que les étapes suivantes puissent réutiliser ses variables. Installez curl et jq avant de continuer. Les exemples utilisent la version d’API beta 2026-09-01-beta.
command -v curl &&
command -v jq &&
read -rsp "Kimi API key: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
export KIMI_API_KEY &&
export KIMI_BASE="https://api.moonshot.cn/v1" &&
export KIMI_VERSION="2026-09-01-beta"
Comment exécuter votre première tâche Kimi Hosted Agents
Le workflow suit le démarrage rapide REST API de Kimi. Vous utiliserez l’assistant PPT officiel pour transformer un court brief métier fictif en présentation. Toutes les données d’entrée sont incluses dans la requête, donc le premier lancement ne nécessite ni téléversement de fichier ni connexion à des données privées.
Exécutez chaque bloc dans l’ordre et vérifiez sa sortie avant de continuer. Les commandes chaînées par && interrompent le bloc lorsqu’une requête ou une validation échoue. Corrigez l’erreur signalée avant de passer à l’étape suivante ; conservez les mêmes IDs d’environnement et de session lors de la relance d’une configuration existante.
Étape 1 : Sélectionner l’assistant PPT officiel
Récupérez les agents disponibles et inspectez leurs noms et définitions. Lorsque vous y êtes invité, collez l’ID de l’assistant PPT officiel configuré avec des skills PPT. La commande finale vérifie que votre sélection existe dans la liste renvoyée et imprime sa définition.
curl --fail-with-body -sS "$KIMI_BASE/agents" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o agents.json &&
jq -r '.items[] | [.id, .name] | @tsv' agents.json &&
read -rp "PPT assistant ID: " AGENT_ID &&
jq -e --arg id "$AGENT_ID" \
'.items[] | select(.id == $id)' agents.json &&
export AGENT_ID
La commande finale doit afficher la définition de l’agent sélectionné. Si l’assistant n’est pas disponible dans votre projet, utilisez la configuration officielle de l’agent PPT pour préparer un agent équivalent avant de continuer.
Étape 2 : Créer un environnement cloud
Un Environment est une configuration réutilisable de votre setup d’exécution, incluant les paquets installés, l’accès réseau et les commandes de démarrage. Le réutiliser donne aux sessions ultérieures le même setup ; chaque session cloud reçoit néanmoins son propre bac à sable et espace de travail. Consultez le guide des environnements pour les options de configuration.
Créez l’environnement une fois et conservez son ID. Les images cloud se construisent de manière asynchrone ; attendez que son statut de build soit ready avant de créer une session. Si l’API indique qu’il n’est pas prêt, attendez et réessayez avec le même ENVIRONMENT_ID. Créer un autre environnement ne termine pas la première construction.
curl --fail-with-body -sS "$KIMI_BASE/environments" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
-d '{"name":"First presentation environment","config":{"type":"cloud"}}' \
-o environment.json &&
ENVIRONMENT_ID="$(jq -er '.id | strings | select(length > 0)' environment.json)" &&
export ENVIRONMENT_ID &&
printf 'Environment: %s\n' "$ENVIRONMENT_ID"
Étape 3 : Créer une session
Une Session fige la version de l’Agent et une version disponible de l’Environnement au moment de sa création. La requête ci-dessous fournit leurs IDs ; la plateforme sélectionne et fige les versions. Vous pouvez aussi définir agent_version pour choisir une version exacte de l’Agent. Mettre à jour l’Agent ou l’Environnement plus tard n’actualise pas une session existante, et une session ne peut pas changer son environment_id. Créez une nouvelle session pour utiliser des configurations révisées. Ces règles sont documentées dans la création de session.
Conservez l’ID de session renvoyé pour le flux d’événements et les requêtes de tâche. Une nouvelle session commence en idle ; envoyer user.message démarre la tâche.
test -n "$AGENT_ID" &&
test -n "$ENVIRONMENT_ID" &&
jq -n --arg agent "$AGENT_ID" --arg env "$ENVIRONMENT_ID" \
'{agent_id:$agent,environment_id:$env,title:"First product update presentation"}' \
> session-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @session-request.json \
-o session.json &&
SESSION_ID="$(jq -er '.id | strings | select(length > 0)' session.json)" &&
export SESSION_ID &&
printf 'Session: %s\n' "$SESSION_ID"
Étape 4 : Suivre l’exécution dans un second terminal
Ouvrez le Terminal B. Saisissez la même clé API, puis collez l’ID de session imprimé dans le Terminal A. Le flux d’événements SSE affiche les mises à jour d’exécution pendant que le Terminal A soumet la tâche. Laissez ce terminal connecté jusqu’à ce que vous ayez inspecté le résultat.
read -rsp "Kimi API key: " KIMI_API_KEY &&
printf '\n' &&
test -n "$KIMI_API_KEY" &&
read -rp "Session ID from Terminal A: " SESSION_ID &&
test -n "$SESSION_ID" &&
curl --fail-with-body -sS -N \
"https://api.moonshot.cn/v1/sessions/$SESSION_ID/events/stream" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: 2026-09-01-beta" \
-H "Accept: text/event-stream"
Étape 5 : Envoyer une tâche autonome
Revenez au Terminal A et envoyez un événement user.message. L’exemple utilise des chiffres fictifs et demande un livrable spécifique. L’agent doit utiliser les faits fournis plutôt que de rechercher des données métier.
cat > task.json <<'JSON' &&
{
"events": [{
"type": "user.message",
"data": {"content": [{
"type": "text",
"text": "Create a three-slide PPTX for a fictional product called Northstar. Use only these supplied facts: the pilot has 120 users; 90 were active this week; the team plans to interview 10 users next week. Slide 1: pilot overview. Slide 2: weekly activity, including the active-user percentage. Slide 3: next steps. Label the business and data as fictional. Do not browse the web. Save the presentation and register the PPTX as a downloadable artifact using save_artifact."
}]}
}]
}
JSON
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @task.json
Étape 6 : Télécharger et inspecter la présentation
Surveillez les événements session.status dans le Terminal B. Lorsque la session revient à idle, inspectez sa raison d’arrêt : end_turn indique que le tour est terminé, tandis que requires_action signifie que votre client doit fournir un résultat d’outil ou gérer une confirmation. Vérifiez aussi les événements session.error. Une fois le tour terminé sans erreur non résolue, listez les artefacts et sélectionnez le PPTX généré.
curl --fail-with-body -sS "$KIMI_BASE/artifacts?session_id=$SESSION_ID" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o artifacts.json &&
jq . artifacts.json &&
read -rp "PPTX artifact ID: " ARTIFACT_ID &&
test -n "$ARTIFACT_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/artifacts/$ARTIFACT_ID/content" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-o northstar.pptx &&
printf 'Downloaded northstar.pptx\n'
Ouvrez northstar.pptx. Un résultat réussi contient trois diapositives, identifie les données comme fictives et calcule l’activité hebdomadaire comme 90 ÷ 120 = 75 %. Cela vous donne une vérification concrète à la fois de la livraison du fichier et de l’exactitude du contenu avant de connecter des données métiers réelles.
Comment téléverser et associer des fichiers à une session Kimi Hosted Agents ?
Après le premier essai concluant, placez un report.pdf d’exemple dans le répertoire de travail du Terminal A. L’API de fichiers sépare le téléversement d’un fichier de son association à une session. Exécutez ce bloc avec l’ID de session existant après la fin de la première tâche.
Utilisez purpose=file-extract pour extraire le texte du PDF. L’API de fichiers autorise jusqu’à 100 MiB par fichier et, par défaut, 10 GiB de stockage par organisation. Les fichiers téléversés ne peuvent pas être mis à jour sur place ; téléversez un fichier révisé et liez son nouvel ID. Supprimez les fichiers inutilisés lorsque vous devez libérer du stockage.
Avec kimi-api-version: 2026-09-01-beta, vérifiez extract_status dans la réponse d’upload. Cet exemple ne continue que lorsque sa valeur est ready. Si elle est error, inspectez le format et le contenu du PDF, puis téléversez un fichier corrigé. L’API peut associer une extraction échouée comme fichier brut, mais cela ne fournit pas le texte extrait attendu par ce tutoriel. Un statut manquant ou inattendu arrête également le bloc ; inspectez upload.json avant de continuer.
test -f report.pdf &&
test -n "$SESSION_ID" &&
curl --fail-with-body -sS "$KIMI_BASE/files" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-F "file=@report.pdf" \
-F "purpose=file-extract" \
-o upload.json &&
FILE_ID="$(jq -er '.id | strings | select(length > 0)' upload.json)" &&
{
EXTRACT_STATUS="$(jq -r '.extract_status // "missing"' upload.json)" &&
case "$EXTRACT_STATUS" in
ready) true ;;
error)
printf '%s\n' 'PDF extraction failed. Check the PDF and upload a corrected file.' >&2
false ;;
*)
printf 'Unexpected extract_status: %s. Inspect upload.json before continuing.\n' "$EXTRACT_STATUS" >&2
false ;;
esac
} &&
jq -n --arg file "$FILE_ID" \
'{type:"file",file_id:$file}' > resource-request.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/resources" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @resource-request.json
Associer le fichier n’envoie pas une nouvelle tâche. Gardez le Terminal B connecté et soumettez un suivi qui nomme le document et l’output souhaité.
jq -n --arg prompt \
"Use the attached report.pdf to create a new three-slide PPTX. Replace the earlier fictional brief. Summarize the report, its evidence, and its next steps. Do not invent missing figures or browse the web. Register the finished PPTX with save_artifact." \
'{events:[{type:"user.message",data:{content:[{type:"text",text:$prompt}]}}]}' \
> followup.json &&
curl --fail-with-body -sS "$KIMI_BASE/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $KIMI_API_KEY" \
-H "kimi-api-version: $KIMI_VERSION" \
-H "Content-Type: application/json" \
--data-binary @followup.json
Lorsque cette tâche se termine, répétez l’étape de listing des artefacts et sélectionnez le nouveau PPTX. Comparez ses affirmations avec le PDF, en particulier les nombres, dates et actions proposées.
Comment connecter des outils à Kimi Hosted Agents ?
Outils personnalisés exécutés par votre application
Pour une action métier comme la consultation du statut de livraison d’un projet, utilisez un outil personnalisé implémenté par votre application. Déclarer l’outil le rend disponible à l’agent ; votre code exécute toujours l’opération.
- Déclarez une entrée
customdans le tableautoolsde l’agent avec un nom, une description et uninput_schemade forme objet. - Gérez
agent.custom_tool_usedepuis le flux d’événements et validez les arguments fournis avant d’exécuter votre fonction. - Publiez un événement
user.custom_tool_resultdans la session, en utilisant leidJSON de l’événement appelant commedata.event_id.
Commencez par une consultation en lecture seule. Conservez l’autorisation et la protection contre les actions en double dans l’application lorsqu’une intégration peut modifier des enregistrements métiers.
Services MCP et workflows plus vastes
Pour un service MCP distant, déclarez sa connexion dans mcp_servers. Stockez les identifiants d’accès dans un coffre-fort et liez ce coffre lors de la création de la session. La plateforme découvre et appelle les outils du service ; la définition du serveur doit contenir les détails de connexion plutôt que des secrets.
Orchestration multi-agent optionnelle
La plateforme prend en charge la délégation coordinateur-vers-enfants. Un coordinateur peut attribuer des tâches bornées à des threads enfants et combiner leurs résultats.
Sa configuration de délégation accepte 1–20 entrées d’agent. C’est une limite de configuration, pas la preuve de 20 travailleurs simultanés ni d’une amélioration de vitesse ×20. Les threads enfants ne peuvent pas créer une autre couche de threads enfants.
Un design utile peut séparer la collecte des sources, l’analyse quantitative et la revue éditoriale. Une courte tâche de synthèse est généralement mieux gérée par un seul agent.
Comment déployer une intégration Kimi Hosted Agents ?
Placez les appels à l’API Kimi derrière le backend de votre application. Le navigateur peut soumettre une tâche et afficher la progression via vos propres endpoints, tandis que le backend conserve la clé API et associe chaque utilisateur aux sessions auxquelles il a droit. Stockez l’ID de session avec la demande métier afin qu’un rechargement de page puisse rouvrir la même tâche.
Exécution hébergée vs auto-hébergée
Utilisez un environnement cloud pour le workflow PPT de ce guide : il prend en charge save_artifact et le workflow de fichiers de session. Choisissez un environnement auto-hébergé lorsque l’exécution en bac à sable doit se faire sur un hôte géré par votre organisation. Kimi exécute toujours l’inférence du modèle, l’orchestration et la gestion de session ; les entrées d’outils et les résultats transitent par sa plateforme. Il s’agit d’un modèle d’exécution hybride.
- Les environnements auto-hébergés nécessitent une vérification entreprise. Vous exploitez l’hôte Worker, installez ses dépendances et gérez l’isolation et les identifiants. Le Worker a besoin d’un accès HTTPS sortant vers la plateforme.
- Le mode auto-hébergé ne dispose actuellement pas de
save_artifact, IPython et des outils de recherche d’images. Les fichiers téléversés, skills et mémoires ne sont pas montés sur le Worker, et ses fichiers de sortie n’apparaissent pas dans la liste des fichiers de session. Planifiez comment fournir les entrées et récupérer les sorties avant de migrer ce tutoriel vers ce mode.
Pour une première intégration, commencez dans le cloud. Envisagez l’auto-hébergement lorsque le contrôle de l’hôte d’exécution justifie le setup supplémentaire et les changements de livraison de fichiers.
Choisir qui opère l’exécution
Utilisez Hosted Agents lorsque vous souhaitez que la plateforme gère l’exécution des sessions. Si votre équipe doit construire et opérer sa propre boucle d’agent, la CometAPI fournit un accès unifié aux modèles pour cette pile personnalisée. Les exemples Hosted Agents de ce guide utilisent les endpoints et identifiants propres à Kimi.
Tarification de Kimi Hosted Agents et optimisation des coûts
Kimi Hosted Agents facture les tokens de modèle, le runtime du bac à sable cloud et les appels de plugins payants. Le tableau ci-dessous montre comment ces coûts affectent un workflow de présentation. Les prix sont en yuan chinois (CNY), vérifiés le 10 novembre 2026 selon la tarification Hosted Agents et la tarification de l’inférence de modèle. Un million de tokens équivaut à 1 MTok.
| Composant de coût | Unité de facturation | Taux et implications pour votre tâche |
|---|---|---|
| Inférence modèle | Par 1 MTok | Pour kimi-k3.1-pro : entrée de base ¥13, sortie ¥68, hits de cache ¥1,30, écritures de cache 5 minutes ¥13 et écritures de cache 1 heure ¥26. Appliquez le tarif pour chaque catégorie d’usage sur tous les appels. |
| Bac à sable cloud | Runtime ; facturé à la seconde | ¥0,072/heure pour un bac à sable avec 1 cœur CPU et 1 Go de mémoire. Dix minutes coûtent ¥0,012. |
| Plugins | Par appel facturable | Exemples : recherche web ¥0,03/appel ; recherche d’images ¥0,045/appel. Les autres plugins ont leurs propres tarifs. Multipliez le nombre d’appels de chaque plugin par son prix. |
| Coût total tâche | Par tâche complétée | Additionnez modèle, bac à sable et plugins. L’exemple de PPT ci-dessous totalise ¥0,544 sans appels payants, ou ¥0,724 avec trois recherches web et deux recherches d’images au même usage modèle et runtime. |
Le tarif du modèle est un exemple de budgétisation pour kimi-k3.1-pro, pas l’affirmation que chaque Agent PPT officiel utilise ce modèle. Vérifiez la définition du modèle de l’Agent sélectionné avant d’appliquer ces tarifs. Les tarifs d’autres modèles et des variantes haut débit diffèrent.
Comment compter les tokens d’entrée et de sortie
Un Agent peut appeler son modèle plusieurs fois lors de la création d’une présentation. Additionnez l’usage facturé de chaque appel, y compris les tours de suivi et révisions. L’entrée peut inclure la requête, le texte extrait du PDF, les résultats d’outils et le contexte de conversation ; l’usage en sortie ne se limite pas aux mots visibles sur les diapositives.
Pour la mise en cache K3, séparez entrée non mise en cache, écritures de cache et hits de cache. Ce sont des catégories d’entrée distinctes : ne facturez pas le total d’entrée complet au tarif de base puis ajoutez des frais de cache pour les mêmes tokens. Utilisez le tarif applicable pour les écritures 5 minutes ou 1 heure. Le guide de facturation du cache explique comment rapprocher ces catégories de l’usage rapporté.
Exemple chiffré : une présentation en trois diapositives
Supposons que votre Agent utilise kimi-k3.1-pro et qu’un run complet de trois diapositives consomme 20 000 tokens d’entrée, 4 000 tokens de sortie facturés et 10 minutes de runtime cloud facturable. Supposons aucun hit de cache, aucune écriture de cache 1 heure et aucun appel de plugin payant. Toute l’entrée est soit non mise en cache, soit écrite dans le cache 5 minutes par défaut, tous deux à ¥13/MTok. Ce sont des quantités estimées pour la planification, pas des mesures du tutoriel Northstar.
| Poste | Calcul | Coût estimé |
|---|---|---|
| Entrée modèle | 20,000 ÷ 1,000,000 × ¥13 | ¥0,260 |
| Sortie modèle | 4,000 ÷ 1,000,000 × ¥68 | ¥0,272 |
| Bac à sable | 10 ÷ 60 × ¥0,072 | ¥0,012 |
| Plugins payés | 0 appel facturable | ¥0,000 |
| Total | ¥0,260 + ¥0,272 + ¥0,012 | ¥0,544 (≈ ¥0,54) |
Le tutoriel avec faits fournis demande à l’Agent de ne pas naviguer sur le web. Si vous l’étendez plus tard à une présentation de recherche avec trois recherches web et deux recherches d’images, le coût plugin serait 3 × ¥0.03 + 2 × ¥0.045 = ¥0.180. En tenant les autres quantités constantes, on obtient ¥0.544 + ¥0.180 = ¥0.724. La recherche peut aussi augmenter les tokens de modèle et le runtime ; utilisez donc les quantités mesurées pour la facture finale.
Ce qui change lorsque vous utilisez plusieurs agents
La délégation peut ajouter des appels modèle, du contexte répété, des appels d’outils et du travail de révision. Le workflow multi-agent de Kimi place le coordinateur et les threads enfants dans une seule session. Le simple nombre de threads enfants n’est pas un multiplicateur des coûts de bac à sable. Additionnez l’usage modèle et plugin à travers les threads et utilisez le runtime facturable réel de la session. Une exécution plus longue ou des sessions cloud supplémentaires indépendantes peuvent augmenter le coût du bac à sable. La FAQ explique que le temps de bac à sable cesse de s’accumuler lorsque tous les threads se terminent et que la session devient idle.
Réduire le coût par présentation exploitable
Commencez avec un Agent et un livrable réduit. Fournissez les passages sources pertinents, contraignez le nombre de diapositives et activez les recherches payantes uniquement lorsque la tâche en a besoin. Reconnectez un flux d’événements interrompu au lieu de soumettre à nouveau la même tâche. Pour les workflows récurrents, inspectez les hits de cache et stabilisez le contexte réutilisable. Comparez le coût total de toutes les tentatives au nombre de présentations que vous acceptez réellement ; un premier jet bon marché nécessitant plusieurs relances peut coûter plus cher au final.
Dépannage des erreurs API courantes
- Échec d’authentification : vérifiez que la clé API est définie dans le terminal qui envoie la requête et qu’elle appartient au compte visé. Inspectez l’erreur HTTP avant de répéter l’appel.
- curl rejette une option, ou jq est absent : vérifiez les utilitaires installés. Ces exemples nécessitent une version de curl prenant en charge
--fail-with-bodyet un exécutable jq fonctionnel dans le même environnement Bash. - jq ne peut pas extraire un ID : ouvrez le JSON de réponse sauvegardé. Il peut contenir une erreur d’API au lieu d’un objet ressource réussi. Corrigez d’abord la requête plutôt que de passer un ID vide au prochain endpoint.
- Un workflow d’outil personnalisé n’avance plus : inspectez les événements d’outil en attente. Une raison d’arrêt
requires_actionsignifie que le client doit renvoyer un résultat d’outil ou gérer une confirmation avant que le thread concerné ne continue. - Les diapositives téléchargées contiennent des affirmations non étayées : comparez-les au brief fourni ou au rapport. Révisez la tâche avec l’écart spécifique et inspectez le prochain livrable avant de l’utiliser.
Enregistrez l’endpoint, le statut HTTP, l’ID de session et l’événement pertinent lors du diagnostic d’un échec. Ne placez pas de clés API dans les journaux de diagnostic.
Conclusion
Commencez par un workflow Kimi Hosted Agents complet : sélectionnez un agent, préparez son environnement, créez une session, soumettez une tâche et inspectez le fichier livré. Une fois ce chemin validé, ajoutez un document source puis les outils métiers dont votre application a besoin. Gardez la progression visible et jugez chaque exécution à l’aune de l’utilité de sa sortie, pas seulement de la réussite de la requête.
FAQ
Dois-je renvoyer une tâche Kimi Hosted Agents après une déconnexion ?
Non. Un flux d’événements déconnecté ne nécessite pas un nouvel envoi de tâche. Reconnectez-vous avec la valeur id: du dernier cadre SSE dans l’en-tête Last-Event-ID pour reprendre la lecture. Cette valeur est un curseur de flux, pas l’ID JSON de l’objet événement. Se reconnecter évite d’envoyer accidentellement le même travail deux fois.
Que faire si une sortie Kimi Hosted Agents est absente des artefacts ?
Un fichier du bac à sable peut exister sans être enregistré comme artefact. Vérifiez si l’agent a terminé la présentation et appelé save_artifact. Si l’enregistrement manque, utilisez les APIs de fichiers de session pour inspecter le répertoire de sortie : GET /v1/sessions/{session_id}/filesystem?prefix=output. Le listing couvre un répertoire à la fois ; mettez à jour prefix pour inspecter un sous-répertoire. Téléchargez le fichier choisi avec GET /v1/sessions/{session_id}/filesystem/raw?path=output/northstar.pptx, en remplaçant le chemin d’exemple par le chemin exact renvoyé par le listing. Encodez l’URL de la valeur de requête si le chemin contient des espaces ou d’autres caractères réservés. Incluez les mêmes en-têtes d’autorisation et de version d’API que dans le tutoriel.
La mise à jour d’une configuration Kimi Hosted Agents modifie-t-elle une session active ?
Non. Une session utilise la version de l’agent figée à la création. Mettre à jour l’agent crée une nouvelle version pour les sessions ultérieures tandis que les sessions existantes conservent leur configuration d’origine. Pour tester des instructions ou outils révisés, démarrez une nouvelle session et comparez sa sortie avec l’exécution précédente.

