Opérations exécutées par le fournisseur
Appeler des opérations d’agents et des outils enregistrés sans importer leur implémentation.
Démarrer une opération
L’hôte autorise l’appelant puis soumet la déclaration générée et les arguments
originaux. StartOperation utilise une session existante de l’hôte ;
StartOneShotOperation ne crée aucune session. Le worker fournisseur valide son
exportation et prépare la configuration immuable sélectionnée. Le consommateur n’a
besoin ni de la définition privée de l’agent ni de WithAgentExecutors.
handle, err := rt.StartOneShotOperation(
ctx, runID, operation, arguments, labels, nil,
)
if err != nil {
return err
}
output, err := handle.Wait(ctx)
if err != nil {
return err
}
Utilisez StartToolOperation ou StartOneShotToolOperation avec la sélection Registry
exacte conservée et son RegisteredInvocation. Configurez la même source Registry et le
client généré. Les agents natifs utilisent le workflow et la file déclarés. Les services
utilisent WithToolWorkflowQueue et un worker appelant RegisterToolWorkflow, sans
agent, planificateur, modèle ou conversation. Un enregistrement ou une étiquette ne
donne pas accès.
Pour démarrer et attendre une opération de manière idempotente après
l’interruption du processus de démarrage, utilisez EnsureOperationCompletion,
EnsureOneShotOperationCompletion, EnsureToolOperationCompletion ou
EnsureOneShotToolOperationCompletion. Passez runtime.WithTextOnly(true) si
l’opération doit renvoyer directement le texte de l’assistant sans appeler d’outils.
Utilisez runtime.WithRootExecutionTarget(target) lorsque le travail initial doit
nommer une version exacte de worker. Le moteur concret temporal.Engine possède
la méthode de recherche temporalEngine.CurrentWorkflowTarget(ctx, queue). Les
nouveaux workflows de réponse et de nettoyage ordinaire omettent la cible explicite :
Temporal choisit la version courante lors de l’affectation, puis le comportement de
versionnement configuré du worker régit l’exécution. La reprise préserve les
paramètres publiés exacts, y compris les anciennes cibles explicites.
Lorsqu’un worker de fournisseur doit servir un contrat d’opération à travers des
modifications de révision compatibles, enregistrez le contrat propre à la révision avec
rt.RegisterAgentOperationProvider avant de sceller le runtime.
Choisir explicitement l’historique
Enregistrez AgentToolResolver sur le worker fournisseur avant de sceller le runtime ou
de soumettre du travail. Sa signature est func(context.Context, genregistry.ExecutionInvocation, string, *runtime.ToolCall) (*runtime.AgentToolConfiguration, error). Il reçoit l’invocation originale, la
référence immuable et l’appel validé. Il renvoie History obligatoire, étiquettes,
politique et, éventuellement, métadonnées et références de prompts.
configuration := &runtime.AgentToolConfiguration{
History: runtime.LiteralAgentHistory(messages),
Labels: labels,
Policy: policy,
}
Pour un tour ultérieur, utilisez runtime.NextTurnAgentHistory(completedRunID, systemMessages, freshMessages). La source doit être une exécution réussie du même agent
et de la même session. Les nouveaux messages ne contiennent pas de messages système.
WithoutPriorReasoning() exclut le raisonnement fourni et hérité ; cette exclusion
persiste aux tours suivants. Une opération sans session ne reprend pas l’historique
d’une autre session. Une répétition exacte réutilise la préparation acceptée.
Résultats, saisie et annulation
Le moteur prend en charge le travail accepté avant la préparation. Répéter la requête exacte retrouve l’exécution originale ; modifier une requête acceptée crée un conflit. Un échec ou une annulation avant le premier enregistrement du runtime conserve un résultat terminal dans le moteur. Observez le travail accepté avant de conclure que l’absence d’un enregistrement signifie qu’aucun travail n’a démarré.
Les entrées, sorties, enregistrements et instantanés communs exigent Subject généré :
l’identifiant réel de l’agent, ou la source Registry et le nom qualifié de l’outil de
service. Un service n’a ni agent fictif ni session cachée. Les clients et historiques
propres aux agents exigent toujours une identité d’agent.
planner.PlanInput.ParentTool et planner.PlanResumeInput.ParentTool portent le
contrat de résultat sélectionné pour la délégation et les opérations directes. Le
planificateur renvoie planner.FinalToolResult conforme au contrat ; du texte seul est
refusé. Utilisez FinalToolResult pour le résultat typé et Final pour le texte.
Consultez les événements paginés seulement pour l’historique de diagnostic.
Lorsqu’une entrée est requise, la continuation rétablit l’opération d’origine, préserve les
métadonnées de l’appelant acceptées (Metadata) et admet un successeur. Pour les outils de service,
l’hôte enregistre durablement le prédécesseur, l’ID de l’exécution successeur et la réponse typée ;
son worker appelle StartToolContinuation et EnsureToolContinuationCompletion (en passant tout mémo
de workflow memo map[string]any comme argument final). L’annulation du parent suit les relations
enfants acceptées et préserve le nettoyage inachevé. L’achèvement ne doit pas dépendre d’un nouvel
essai du client.
Les workflows d’observation des annulations utilisent AutoUpgrade pour les
exécutions actives et suspendues. Ils observent le nettoyage sans modifier
l’exécution affectée au travail métier. La reprise conserve la cible explicite et
l’empreinte de requête d’un observateur déjà accepté.
Contrats d’entrée générés
Dans Use d’un toolset compilé, BindInput("read", "scope") retire un champ
fournisseur obligatoire de premier niveau de l’entrée du modèle pour ce consommateur.
Installez le helper typé généré pour chaque activité de planification afin de fournir la
valeur de l’application. Le fournisseur reçoit toujours l’entrée complète. Les champs
facultatifs, injectés, inconnus, répétés et les chemins imbriqués sont refusés ; les
contrats Registry distants nécessitent une déclaration compilée.
Les codecs acceptent Any ou Bytes explicitement représentés par json.RawMessage,
conservant JSON et nombres exacts. Une map déclarée avec Meta("struct:tag:json", ",embed") accepte des membres supplémentaires selon le contrat de ses valeurs. Les clés
dupliquées, collisions et valeurs invalides sont refusées. Les objets ordinaires restent
fermés et les octets ordinaires utilisent base64.
Mise à niveau et retour arrière
Cette mise à niveau coordonne le code, les formats échangés et les données conservées.
Régénérez et reconstruisez fournisseurs et consommateurs ; remplacez Messages par
History obligatoire et enregistrez le resolver chez le fournisseur. Un historique
explicitement vide est runtime.LiteralAgentHistory(nil) ; un AgentHistory sans
sélection est refusé. Les cibles natives exigent Executor, Configuration, Workflow
et Queue. SeedDeclaration ne duplique plus Origin ; RunSeed.Origin est extrait
directement du paramètre BeginRunPreparationOperation. Validez chaque groupe de
déclarations conservé, y compris les entrées retirées, avant l’activation.
Les suspensions utilisent goa-ai.run-suspension.v14 et les résultats principaux
json/goa-ai-run-output-v3. Les anciens formats sont refusés. Adaptez Stores, moteurs,
enregistrements, consommateurs et transports à Subject obligatoire. Inventoriez
démarrages, préparations, sélections, checkpoints, historiques parents contenant des
résultats enfants, exports et copies de résultats. Terminez le travail avec ses anciens
workers ou effectuez une conversion contrôlée par le propriétaire avec vérification du
replay. Ne partagez pas une file entre anciennes et nouvelles préparations tant que du
travail ancien subsiste.
Coordonnez lecteurs et écrivains déployés séparément. Un retour arrière exige données, déclarations, requêtes et workers compatibles ; rétablir seulement un binaire après de nouvelles écritures est dangereux. Le framework ne déduit pas les exécuteurs manquants et n’offre pas de compatibilité permanente.
Contrats détaillés du framework :