agents-sdk

Aperçu du skill agents-sdk

À quoi sert agents-sdk

Le skill agents-sdk vous aide à créer des agents Cloudflare Workers avec Agents SDK lorsque vous avez besoin d’une conversation avec état, d’une exécution durable, d’interactions WebSocket ou en temps réel, de tâches planifiées, d’une intégration MCP ou d’une automatisation pilotée par le navigateur. Le agents-sdk skill est particulièrement adapté si vous cherchez une vraie décision d’installation : ce SDK peut-il faire le travail, quelle configuration est nécessaire, et que faut-il lire en premier avant de coder.

Cas d’usage les plus adaptés

Utilisez agents-sdk lorsque vous créez un Worker de production qui doit conserver l’état de l’agent, exposer des méthodes appelables, offrir un accès client typé, gérer des workflows adossés à une queue, des tentatives automatiques, de l’observabilité ou des hooks React côté client. C’est un très bon choix pour agents-sdk for Multi-Agent Systems seulement si ces agents vivent dans le runtime Cloudflare et partagent les contraintes des Worker/Durable Object.

Ce qui le distingue

Ce skill n’est pas un prompt générique du type « créez un agent ». Il est lié aux détails d’implémentation de Cloudflare : Durable Objects, wrangler.jsonc, migrations, nodejs_compat et des patterns propres à l’API comme @callable(), runFiber et useAgent. Autrement dit, le principal risque d’adoption concerne la configuration, pas la conception du concept.

Comment utiliser le skill agents-sdk

Installer et vérifier le bon contexte

Lancez l’étape agents-sdk install avec le gestionnaire de skills, puis vérifiez que vous travaillez bien dans un repo Cloudflare Workers et non dans une application de chat autonome. Le schéma d’installation de base est :

npx skills add cloudflare/skills --skill agents-sdk

Après l’installation, commencez par SKILL.md, puis consultez en priorité references/configuration.md, references/client-sdk.md, references/callable.md et references/durable-execution.md. Ces fichiers répondent aux questions qui bloquent le plus souvent l’adoption : les bindings, les migrations, la connexion côté client et la manière dont l’état survit aux redémarrages.

Transformer un objectif flou en prompt utile

Le skill donne de meilleurs résultats quand votre prompt décrit la forme du runtime, pas seulement la fonctionnalité. Un bon input précise :

• le type d’agent : agent de chat, agent de workflow, agent vocal, agent navigateur ou serveur MCP
• s’il s’agit d’un projet greenfield ou d’un ajout à une application Workers existante
• la surface client : hook React, client JS simple, RPC, email ou WebSocket
• le besoin de persistance : état simple, exécution durable ou flux queue/retry

Exemple de demande agents-sdk usage plus solide :
« Ajoute un agent Cloudflare Worker qui stocke l’état par utilisateur, expose une méthode callable et diffuse les réponses de chat via un client React. Utilise les règles de configuration Agents SDK actuelles et montre les modifications nécessaires dans wrangler.jsonc. »

Lire le repo dans le bon ordre

Pour la plupart des installations, le parcours le plus rentable est le suivant :

1. SKILL.md pour les patterns pris en charge et les sources de récupération
2. references/configuration.md pour les bindings, les migrations et la configuration du développement local
3. references/callable.md et references/client-sdk.md pour les interactions client/serveur
4. references/state-scheduling.md, references/workflows.md ou references/durable-execution.md si votre application a besoin de persistance ou de traitements longs
5. references/observability.md et references/queue-retries.md si la fiabilité compte

Conseils pratiques qui améliorent vraiment le résultat

Donnez au skill votre wrangler.jsonc existant, le nom exact de la classe d’agent actuelle et le chemin précis où le nouveau code doit vivre. Mentionnez aussi si vous utilisez déjà React, Workers AI ou MCP. Indiquez enfin si vous voulez un exemple minimal fonctionnel ou un patch d’intégration, car les détails de configuration du SDK changent beaucoup entre ces deux objectifs.

FAQ du skill agents-sdk

agents-sdk est-il réservé aux nouveaux projets ?

Non. Le agents-sdk guide prend en charge aussi bien les nouvelles applications Workers que les projets existants, mais les repos déjà en place demandent un examen de configuration plus attentif. Si vous avez déjà des bindings, des migrations ou une chaîne de build personnalisée, donnez ces détails dès le départ pour que le skill puisse s’intégrer à la configuration actuelle.

Faut-il déjà connaître Cloudflare ?

Une familiarité de base avec Cloudflare aide, mais le skill reste utile si vous savez suivre des instructions de configuration et lire wrangler.jsonc. Les débutants s’en sortent généralement bien en partant d’un objectif étroit, par exemple un seul agent avec un seul chemin client, plutôt que d’essayer de construire dès le premier jour un système multi-agents complet.

Quand ne faut-il pas utiliser agents-sdk ?

N’utilisez pas agents-sdk si vous avez seulement besoin d’un wrapper d’API sans état, d’un unique appel LLM ou d’un chatbot agnostique vis-à-vis du fournisseur, sans dépendance au runtime Cloudflare. C’est aussi un mauvais choix si vous ne pouvez pas utiliser Durable Objects, les contraintes de Workers ou le flux de déploiement spécifique à Cloudflare.

En quoi est-ce différent d’un prompt normal ?

Un prompt normal peut décrire un agent sur le plan conceptuel, mais agents-sdk s’appuie sur la surface API réelle de Cloudflare et sur ses règles de déploiement. Cela réduit les approximations autour de @callable(), de l’état, des migrations et des hooks client, là où les conseils génériques échouent souvent.

Comment améliorer le skill agents-sdk

Donnez la forme exacte du déploiement

Le plus gros gain de qualité vient du fait de préciser si l’agent tourne dans un seul Worker, utilise plusieurs classes Durable Object, expose du RPC ou nécessite une intégration navigateur/MCP. Si vous voulez un meilleur agents-sdk usage, incluez les points d’entrée attendus, les sources d’événements et le modèle d’état au lieu de dire seulement « crée un agent ».

Partagez les détails de configuration et de contraintes

Le mode d’échec le plus courant, c’est le contexte Cloudflare incomplet. Fournissez votre wrangler.jsonc, les flags de compatibilité, les bindings Durable Object, l’état des migrations et toutes les exigences de développement local. Si le skill voit ces contraintes, il peut éviter des suggestions qui casseraient le déploiement.

Itérez à partir d’un premier morceau qui fonctionne

Demandez d’abord un seul chemin de bout en bout, étroit mais complet : installation, configuration, une classe d’agent, un appel client, une mise à jour d’état. Ensuite, étendez vers les queues, les workflows, le streaming ou l’observabilité seulement une fois ce premier chemin validé. C’est la manière la plus rapide de vérifier que le agents-sdk skill correspond bien à votre application et de détecter tôt un décalage dans les bindings ou les hypothèses de runtime.