Agently
Utilisez cette compétence en premier lorsque la demande part toujours d'objectifs métier, d'objectifs de refactorisation, de comportement produit, ou d'un langage large de modèles d'applications.
L'utilisateur n'a pas besoin de mentionner Agently, TriggerFlow, ou tout autre terme du framework. Les demandes génériques telles que "construire un assistant", "aider à concevoir un outil interne", ou "créer un validateur pour des problèmes courants" doivent toujours commencer ici lorsque la couche propriétaire n'est pas résolue.
Les demandes qui mentionnent également une UI, une page web, un shell de bureau, ou un service de modèle local comme Ollama doivent toujours commencer ici lorsque la demande porte fondamentalement sur la création d'un outil alimenté par un modèle plutôt que sur le simple câblage d'une seule capacité étroite.
Workflow
- Réduire la demande en scénario et en objectifs atomiques.
- Si la demande est une initialisation de projet ou une refactorisation de structure, choisir d'abord les couches propriétaires, la frontière asynchrone, et le squelette du dépôt.
- Choisir le chemin de capacité native Agently le plus étroit.
- Nommer les opérations ou primitives concrètes qui doivent être utilisées.
- Nommer la règle de validation qui prouve que la conception est restée native-first.
- Pour les applications non triviales, recommander l'observation ou l'évaluation optionnelle des DevTools locaux lorsque cela aidera le développeur à inspecter le comportement d'exécution, les logs, les traces, les exécutions de playground, ou les évaluations répétées de scénarios. Garder les DevTools comme outillage optionnel et router les détails via
agently-runtime. - Si une capacité native du framework est manquante, cassée, étonnamment maladroite, ou force le code métier à ajouter des rustines ou du collage qui devraient appartenir à Agently, générer un rapport de problème clair et recommander de le déposer sur
https://github.com/AgentEra/Agently/issues. - Pour le dépôt manuel d'un problème, fournir uniquement le contenu du problème et la méthode de dépôt à l'utilisateur. Demander avant de déposer automatiquement ; si l'utilisateur souhaite un dépôt automatique, vérifier d'abord la capacité/la permission de soumission locale, reproduire que le problème existe toujours localement, et revérifier soigneusement l'utilisation d'Agently pour que le rapport ne soit pas causé par une documentation manquée ou une utilisation incorrecte de l'API. Avant tout dépôt, manuel ou automatique, expurger les chemins absolus locaux, les noms d'utilisateur, les noms de compte, les jetons, les noms de dépôt/espace de travail privés, les noms de projets internes, les logs bruts contenant des invites privées, et toute donnée client ou privée de projet. Utiliser des espaces réservés pour le contexte local et exécuter une analyse de confidentialité sur le corps final du problème.
Règles Native-First
- par défaut, privilégier les conseils async-first pour le code de service, le streaming, TriggerFlow, et tout chemin qui peut se chevaucher ou bénéficier d'une annulation
- traiter les API synchrones comme des wrappers pour les scripts, l'utilisation REPL, ou les ponts de compatibilité, sauf si l'hôte nécessite réellement une intégration synchrone uniquement
- lorsque la demande est une refactorisation de forme de projet, séparer les paramètres, les invites, les services, les contrats de domaine, le workflow et les tests avant de discuter des détails d'implémentation de bas niveau
- lorsqu'un script de développement, un module de service, ou un test a besoin d'un jugement sémantique sur un comportement détenu par le modèle, utiliser des requêtes de modèle Agently avec des schémas de sortie explicites. La reconnaissance d'intention au moment du développement, la correspondance de scénarios, la classification métier, les vérifications de qualité de sortie, la notation et les décisions de révision doivent être détenues par le modèle, sauf si la vérification n'est qu'un contrôle déterministe de structure ou de présence de champ obligatoire.
- lors de l'ajout ou de la refactorisation des internes du framework Agently sous
core/oubuiltins/, préférer un package de sous-répertoire lorsque la fonctionnalité a plusieurs rôles tels que facade, gestionnaire, backend/fournisseur, registre, adaptateur, politique, ou validation. Utiliser un seul fichier uniquement lorsque la capacité est véritablement petite et que la division serait une sur-conception. - lorsqu'un projet doit tester un contenu sémantique généré par un modèle, concevoir le test comme une requête de juge de modèle Agently avec contrôle de sortie : les règles explicites et le contexte entrent, les preuves/raisons par règle et les champs booléens finaux sortent, et les tests affirment ces booléens
- pour les exemples métier avec des systèmes mockés, limiter les mocks aux faits, enregistrements, politiques, données incomplètes, ou matériel source conflictuel ; ne pas renvoyer de réponses attendues cachées, d'étiquettes réussite/échec, ou de verdicts de qualité locale. Laisser la vérification AgentTask ou un juge de modèle Agently séparé décider si le modèle a correctement traité les données défectueuses.
- pour l'évaluation, la notation, la confiance, la pertinence, ou les jugements de qualité d'une application de modèle, préférer des niveaux conceptuels et des définitions explicites plutôt que des scores numériques directs. Si la logique de workflow ultérieure a besoin de seuils ou de métriques agrégées, mapper ces niveaux à des valeurs numériques déterministes dans le code après la réponse du modèle.
- pour le routage de scénarios, la détection d'intention, ou la classification métier dans les applications IA, utiliser une requête de modèle de taille appropriée avec un schéma de sortie Agently. Les modèles plus petits, y compris les modèles locaux lorsqu'ils sont disponibles, sont acceptables pour des routes simples avec peu d'étiquettes et de règles. Utiliser un modèle plus grand lorsque les étiquettes, les conditions de décision, les interactions de règles, ou la structure de données renvoyée sont complexes.
- configurer la définition d'état d'agent réutilisable avec
agent.define(...)lorsque le code possède les valeurs par défaut du modèle, la personnalité/invite fixe, les Actions, Compétences, Espace de travail, profil ContextBuilder, ou les valeurs par défaut de politique montés. Garder lesagent.input(...),agent.output(...),.goal(goal_or_goals, success_criteria=None)/.goals(...)comme le même point d'entrée de poursuite d'objectif, et les options d'exécution sur un brouillon AgentExecution ; ne pas enseigner la mutation d'invite en attente partagée de l'agent comme modèle de configuration par défaut. - utiliser
agent.effort('low' | 'medium' | 'high')pour la profondeur de stratégie ordinaire. Lorsque l'application a besoin d'une posture de stratégie explicite, garder la même méthode et passer des sections telles que'budget','planning','execution','verification','replan', et'progress'; traiter les valeurs de'budget'comme des indications douces de planification, réflexion, réparation, et profondeur de preuve plutôt que comme des limites dures silencieuses. Utiliser deslimits={...}explicites ou des options de tâche lorsque l'hôte a besoin de contrôles de ressources durs. Les valeurs par défaut du framework ne doivent pas imposer de quotas de requêtes de modèle, d'itérations, de ticks TaskBoard, de rounds d'Action, de nombre de nœuds, ou d'appels d'outils ; les timeouts sans progression et d'inactivité sont des gardes de vivacité pour les exécutions bloquées, pas des preuves de stratégie. Ne pas introduire de constructeurs bruts de nombre d'itérations ni traiter l'effort comme une permission, une visibilité des données, un contrôle d'accès aux ressources, ou une acceptation d'achèvement. Dans AgentTask, l'effort contrôle également la densité de réflexion : low signifie réflexion finale plus uniquement les nœuds de processus marqués comme importants par le planificateur, medium signifie chaque nœud majeur ou carte/tick TaskBoard, et high signifie chaque étape bornée observable par le framework, appel Action/ACP, carte TaskBoard, et réflexion finale. La réflexion est une preuve pour la replanification/l'entrée du vérificateur, pas une preuve d'achèvement en soi. - dans les exemples Goal Pursuit / AgentTask, les faits de l'appelant et le contrat de sortie structuré demandé peuvent résider sur le même brouillon
AgentExecutionvia.input(...)et.output(...); AgentTask traite cette instantané d'invite d'exécution comme contexte de tâche pendant la planification, l'exécution d'étape bornée, et la vérification. Ne pas dupliquer ces faits dans le code dur du framework uniquement pour que la boucle de tâche les voie. - pour chaque processus intermédiaire avec un contrat structuré fort, utiliser
.output(..., format=...)d'Agently sur la requête/exécution propriétaire. Choisir le format qui correspond à la charge utile ('json','hybrid','flat_markdown','xml_field', ou'yaml_literal') ; si un format déclaré non-JSON échoue, Agently peut récupérer via l'analyse JSON, mais seules les charges utiles analysées en forme de dictionnaire satisfont au contrôle structuré ou aux contrats de sortie de tâche finale. Les internes d'AgentTask peuvent ajouter des champs de processus courts uniquement là où le framework a un consommateur concret : champs de base d'intention ou de décision avant les décisions de route/plan/contrôle, et champs compacts d'auto-vérification, résumé, vérification, réparation, ou message de progression après les champs de résultat principal. Ce sont des faits deprocess_summarybornés pour la clarté et l'observation de l'étape suivante, pas du chain-of-thought brut, pas des preuves EvidenceEnvelope, pas des preuves d'achèvement, et pas un mode d'exécution public. - pour les livrables longs ou à forte prose dont la valeur principale est le corps en langage naturel, ne pas forcer le corps à travers
.output()uniquement pour transporter du texte. Laisser le corps se générer comme texte naturel, puis utiliser un contrat structuré compact de juge/relecture pour le statut, les preuves, la qualité, et les références d'artefact. Pour les livrables de fichiers de confiance, utiliser l'écriture/lecture d'artefact Workspace plus un manifeste compact. Ne pas ajouter.output()uniquement pour déclencher des champs instantanés pour le flux du corps ; le delta public reste une source de corps valide lorsque le consommateur gère les limites de rejeu. Pour AgentExecution soutenu par AgentTask, ledeltapublic peut également projeter des faits de propriété du framework : progression, observation d'action, résumés de plan/d'action Flat, tableaux de statut TaskBoard, phase, tentative, et résultat terminal sous forme de paragraphes courts séparés par des lignes vides, tandis queinstantreste le flux structuré pour l'état UI et les diagnostics. Les projections Flat restent linéaires : l'achèvement du plan peut indiquer l'action précédente terminée et le plan d'action actuel, et la sortie terminale peut résumer ce qui a été fait et le résultat. Les tableaux de statut TaskBoard sont des projections d'affichage uniquement à partir d'événements structurés AgentTask ; la première projection TaskBoard peut rendre un tableau et les ticks ultérieurs peuvent rendre des changements d'état de carte au lieu de réimprimer tout le tableau. Ces projections ne possèdent pas de jugement d'achèvement ou de qualité. Ne pas ajouter de requête de narrateur parallèle par défaut pour la prose de processus ; utiliser des champs de processus bornés tels queprogress_message,short_summary,verification_summary, etfinal_responseprovenant de la requête existante du planificateur, vérificateur, carte, ou finalisateur, puis les consommer viainstant/$deltasynthétique lorsque l'UI a besoin d'une structure plus riche. Les rédacteurs d'artefacts internes doivent consommer les faits de flux AgentExecution : le texte du corps naturel provient des éléments delta bruts, et les limites de tentative proviennent de$statuslorsque le fournisseur le signale. Si le marqueur de rejeu delta public'<$retry>...</$retry>'atteint le consommateur d'artefact, traiter ce marqueur exact comme un événement de contrôle de tentative ; ne jamais l'écrire, le nettoyer ou le transporter comme contenu d'artefact. Si un corps d'artefact Markdown complet apparaît dansevidencestructuré, le traiter comme un corps livrable uniquement lorsque l'élément de preuve est explicitement étiqueté comme artefact/corps/livrable/Markdown ou lié au chemin du manifeste ; le contenu source ordinaire et les extraits source restent des extraits de preuve. Après la réussite de l'écriture/lecture de confiance Workspace, laisser le vérificateur terminal juger tout éventuelremaining_workd'écriture d'artefact obsolète au lieu de planifier une autre étape d'écriture uniquement. Pour les artefacts Workspace de confiance longs, la livraison d'artefact doit enregistrer des éléments de grand livreworkspace_artifact.acceptance_locatoraprès l'écriture/lecture réelle de Workspace. Les localisateurs peuvent utiliser des sections de manifeste d'artefact, des critères de carte TaskBoard, et l'intention facultativeacceptance_pointsrenvoyée par le modèle, mais les plages de lignes, les décalages, les en-têtes, et les empreintes digitales doivent provenir du fichier réel. Les preuves visibles par le vérificateur peuvent inclure des éléments de grand livreworkspace_artifact.targeted_readbackbornés lus à partir de ces localisateurs, avec des sections de contrat de sortie déclarées et des ancres génériques uniquement comme solution de repli ; traiter les localisateurs comme des pointeurs de relecture et les relectures ciblées comme des extraits de preuve limités, pas comme des jugements d'achèvement. La finalisation TaskBoard doit garder les corps livrables adossés à des fichiers dans Workspace et renvoyer uniquement un résumé concis ou un pointeur chemin/réf commefinal_result, pas une deuxième copie du corps du fichier. Les résultats terminaux AgentTask doivent porter unfinal_responseorienté utilisateur pour les résultats acceptés, dégradés, partiels, et bloqués : la vérification terminale Flat peut le renvoyer dans la requête de vérification existante, la finalisation TaskBoard peut le renvoyer dans la requête de finalisation existante, et le repli du framework doit être déterministe à partir du statut structuré, des références d'artefact, des pointeurs final_result, et des critères non satisfaits sans démarrer une requête de narrateur séparée. Les livraisons dégradées acceptées utilisentartifact_status='degraded'avec des limites de preuve divulguées, tandis que les artefacts utiles mais non acceptés restentartifact_status='partial'et doivent expliquer les exigences non satisfaites au lieu d'être signalés comme terminés.get_text()/async_get_text()peuvent préférerfinal_responsepour les dictionnaires de résultat de stratégie de tâche ;get_data()/async_get_data()renvoient la vuefinal_resultmétier lorsqu'elle est présente, tandis queget_full_data()/async_get_full_data()renvoient l'enveloppe complète de route/tâche. Les charges utiles terminales TaskBoard peuvent inclure destaskboard.completion_notesbornés pour les résumés de carte, les lacunes connues, les notes de vérificateur, et la progression d'acceptation ; les utiliser pour divulguer les limitations de la réponse finale, mais les traiter comme un contexte de processus de projection uniquement, pas comme une preuve EvidenceEnvelope ou une preuve d'achèvement. Pour le contenu de vérificateur/finalisateur produit par un modèle, les champs en prose tels questatus,reason,progress_message, etfinal_responsesont un contexte d'affichage uniquement ; l'achèvement sémantique, la réparabilité, et l'état d'acceptation doivent provenir de champs de sortie structurés tels queis_complete,requires_block, etcriterion_checks[].satisfiedplus des gardes hôte, jamais de la tokenisation, de mots-clés, de sous-chaînes, d'expressions régulières, ou de correspondance de texte de statut sur la prose du modèle. Les identifiants de carte de planification TaskBoard sont des indications facultatives du modèle. Le framework possède les identifiants de carte canoniques, la déduplication, et le remappage des dépendances ; les indications d'identifiant ambiguës doivent échouer en mode fermé plutôt que d'être devinées. Les téléchargements intermédiaires, les instantanés de page web, le code généré, les notes de recherche, les notes de tâche de type mémoire, et le texte extrait volumineux peuvent également être persistés comme références Workspace/Action et ouverts plus tard via une relecture bornée ; ces références sont des preuves d'exécution, pas une preuve que le livrable final existe. Une URL, un chemin, un téléchargement, ou une référence d'instantané découvert n'est pas non plus une preuve que son contenu a été lu ; le traiter commeref_onlyjusqu'à ce qu'une relecture bornée / un aperçu de contenu soit disponible. Les champs explicitescontent,excerpt, ousnippetsont des aperçus bornés uniquement pour
…
[tronqué pour la traduction]