UI-TARS Desktop : guide pratique des agents GUI pour computer use

UI-TARS Desktop est une application desktop pour controler un ordinateur ou un navigateur avec du langage naturel. Elle fait partie du stack TARS de ByteDance et s’appuie sur des modeles vision-langage UI-TARS / Seed capables de lire des captures d’ecran, raisonner sur l’interface, puis produire des actions souris/clavier.

Je l’ecris comme mon propre guide utilisateur et guide d’apprentissage. Je ne veux pas seulement retenir “un agent IA peut utiliser mon ordinateur”. Je veux comprendre le modele mental :

• Que se passe-t-il quand j’ecris une instruction ?
• Quelle difference entre local operator, remote operator et browser operator ?
• Pourquoi la configuration du modele est-elle critique ?
• Pourquoi les permissions, screenshots, navigateurs et single-monitor comptent ?
• Comment le SDK generalise ce pattern pour construire ses propres agents GUI ?
• Ou faut-il etre prudent avant de laisser un agent agir sur un vrai desktop ?

Sources officielles : GitHub UI-TARS-desktop, README, Quick Start, Settings guide, SDK guide et note deployment.

Ce qu’est UI-TARS Desktop

UI-TARS Desktop est une application native pour automatiser une interface graphique via un modele vision-langage. L’agent ne se limite pas a appeler des APIs structurees. Il observe l’ecran, identifie les elements visuellement, puis produit des actions : click, type, scroll, drag, hotkey ou finished.

Ce n’est donc pas un simple script Playwright.

Automatisation classique :

Trouver un element par selector -> click -> verifier le DOM.

Computer use avec UI-TARS :

Capture ecran -> demander au VLM quoi faire -> parser l'action -> executer souris/clavier -> recapturer.

Cette approche devient utile quand l’interface n’offre pas d’API stable : reglages systeme, applications desktop, pages web dynamiques, modals, remote computers, workflows mixtes.

Le repo se situe dans un stack plus large :

• Agent TARS : agent multimodal general avec CLI/Web UI, browser control, integration MCP, event stream et outils.
• UI-TARS Desktop : application native focalisee sur les operations GUI pour ordinateur local, remote computer et browser operator.

Le README decrit UI-TARS Desktop comme un agent GUI natif pour ordinateur local, pilote par UI-TARS et les modeles Seed-1.5-VL/1.6. Les fonctions principales : controle en langage naturel, reconnaissance visuelle par screenshot, controle precis souris/clavier, support Windows/macOS/browser, feedback temps reel et traitement local/prive.

La boucle centrale

Tout le systeme peut se comprendre comme une boucle.

1. Vous donnez une instruction.
2. L’operator capture l’ecran.
3. Le modele recoit l’instruction, les actions autorisees et les screenshots recents.
4. Le modele predit l’action suivante.
5. L’operator execute cette action.
6. La boucle continue jusqu’a completion, limite ou arret manuel.

Ce modele explique tout le reste : permissions, screenshots, action spaces, max loop, wait time, reports et securite.

Local, remote et browser operator

Le quick-start precise que Browser Operator demande Chrome, Edge ou Firefox. Il indique aussi une limite importante : UI-TARS Desktop est actuellement concu pour une configuration single-monitor. Le multi-monitor peut faire echouer certaines taches.

C’est logique : un agent GUI depend de coordonnees de screenshot. Plusieurs ecrans ajoutent des problemes de placement, scaling et mapping.

Videos officielles a regarder d’abord

Avant de configurer l’application, je regarderais les demos officielles dans le README :

• Showcase UI-TARS Desktop : videos local et remote operator
• Cas d’usage Agent TARS / UI-TARS de la communaute

Les deux exemples UI-TARS Desktop du README sont importants :

• Computer-use task : demander a l’agent d’ouvrir les reglages VS Code, d’activer AutoSave et de regler le delai a 500 ms.
• Browser-use task : demander a l’agent de verifier la derniere issue ouverte du projet UI-TARS Desktop sur GitHub.

Quand vous regardez ces videos, observez surtout la boucle :

1. Ou va le curseur ?
2. Combien de screenshots sont necessaires ?
3. Est-ce que l’agent recupere quand l’UI change ?
4. Est-ce que local operator et remote operator se comportent differemment ?
5. A quel moment faudrait-il une confirmation humaine ?

La video n’est pas seulement une demo. C’est une facon de comprendre comment un agent GUI agit pas a pas.

Installation et permissions

Le chemin simple est la page releases. Sur macOS :

brew install --cask ui-tars

Puis il faut autoriser :

• Accessibility : controle souris/clavier.
• Screen Recording : observation de l’ecran.

Sans ces permissions, il ne peut pas agir comme agent GUI.

Sur Windows, les details changent, mais l’idee securite reste la meme : un agent capable de voir et cliquer a de vrais effets.

Configuration modele

Les providers documentes incluent :

• Hugging Face for UI-TARS-1.0
• Hugging Face for UI-TARS-1.5
• VolcEngine Ark for Doubao-1.5-UI-TARS
• VolcEngine Ark for Doubao-1.5-thinking-vision-pro

Exemple Hugging Face :

Language: en
VLM Provider: Hugging Face for UI-TARS-1.5
VLM Base URL: https://your-endpoint/v1/
VLM API KEY: your_api_key
VLM Model Name: your_model_name

Exemple Doubao :

Language: cn
VLM Provider: VolcEngine Ark for Doubao-1.5-UI-TARS
VLM Base URL: https://ark.cn-beijing.volces.com/api/v3
VLM API KEY: YOUR_API_KEY
VLM Model Name: doubao-1.5-ui-tars-250328

Le provider doit correspondre au modele pour que le parsing des actions fonctionne. Pour Hugging Face, l’URL doit se terminer par /v1/ selon le quick-start.

Parametres importants :

• Check Model Availability
• Use Responses API si supporte
• Language
• Max Loop [25, 200]
• Loop Wait Time [0, 3000]
• moteur de recherche du browser operator
• report storage et UTIO en option

Pour apprendre en securite, je regle surtout Max Loop et Loop Wait Time.

Premiere tache sure

Ne commencez pas par “achete un billet” ou “change mes parametres cloud”.

Commencez par :

Ouvre un navigateur et cherche le repo GitHub UI-TARS Desktop.

Puis :

Ouvre les settings VS Code et cherche autosave, sans rien modifier.

Puis seulement :

Active autosave avec un delai de 500 ms.

Choisissez un type de tache.

Le modele SDK

Le guide @ui-tars/sdk expose l’architecture :

• GUIAgent
• UITarsModel
• Operator

L’operator doit faire deux choses :

• screenshot() : capturer l’etat visuel.
• execute() : executer l’action predite.

Exemple TypeScript :

import { GUIAgent } from '@ui-tars/sdk';
import { NutJSOperator } from '@ui-tars/operator-nut-js';

const guiAgent = new GUIAgent({
  model: {
    baseURL: config.baseURL,
    apiKey: config.apiKey,
    model: config.model,
  },
  operator: new NutJSOperator(),
  onData: ({ data }) => console.log(data),
  onError: ({ data, error }) => console.error(error, data),
});

await guiAgent.run('send "hello world" to x.com');

NutJS supporte click, double click, right click, drag, hover, typing, hotkeys, scrolling et screenshot.

La separation importante :

GUIAgent
  -> le modele decide quoi faire
  -> l'operator sait observer et agir

Status, stop et limites

Les statuts SDK incluent :

• INIT
• RUNNING
• END
• MAX_LOOP

Le SDK supporte aussi AbortSignal. C’est crucial : un agent visuel peut se tromper a cause d’un popup, cookie banner, permission dialog, chargement lent ou mapping de coordonnees.

En mode apprentissage :

• max loop bas ;
• desktop visible ;
• abort facile ;
• pas de comptes sensibles ouverts ;
• pas de paiement/suppression ;
• un seul ecran ;
• fenetres bien placees.

Operateurs custom et action spaces

Un operator custom etend la classe Operator et implemente :

• screenshot()
• execute()

Il peut aussi definir les actions autorisees :

click(start_box="")
type(content="")
scroll(direction="")
finished()

C’est essentiel : le modele ne doit pas avoir une liberte infinie. Il doit agir dans un vocabulaire borne.

Dans execute(), l’operator recoit la prediction parse, les dimensions physiques, le DPR et les facteurs de scaling. C’est une des difficultes des agents GUI : transformer correctement les coordonnees du modele en actions physiques.

Planning + execution GUI

Les docs montrent aussi l’idee de combiner un modele de planning avec UI-TARS :

open chrome
open trip.com
click search
select Beijing in the from input
select Shanghai in the to input
click search

Pour les workflows longs, c’est preferable. Le plan rend l’execution inspectable, recuperable et plus facile a valider.

Je voudrais toujours :

• plan visible ;
• confirmation avant action irreversible ;
• screenshots logs ;
• rapport final ;
• limites de loops et timeout.

Reports, UTIO et observabilite

Les settings decrivent l’export de rapport HTML et un serveur optionnel de stockage. Les docs decrivent aussi UTIO, UI-TARS Insights and Observation, qui peut envoyer des evenements comme lancement app, instruction envoyee ou partage de rapport.

C’est utile pour une equipe, mais sensible : instructions et screenshots peuvent contenir des donnees privees. Pour apprendre, export local suffit. Pour production, traitez ces endpoints comme de l’infrastructure sensible.

Bons et mauvais cas d’usage

Bon candidat :

• workflows visuels sans API stable ;
• tests UI ou demos ;
• reglages desktop ;
• navigation browser complexe ;
• recherche computer-use ;
• construction d’operators custom.

Mauvais candidat :

• actions financieres/admin sans confirmation ;
• multi-monitor ;
• workflow ou une API stable est meilleure ;
• besoin de replay deterministe exact ;
• saisie de donnees sensibles sans isolation ;
• automation invisible en arriere-plan.

Si une API fiable existe, utilisez l’API. Si la tache est vraiment visuelle et humaine, un agent GUI devient pertinent.

Checklist troubleshooting

• Single monitor.
• Permissions Accessibility + Screen Recording.
• Chrome/Edge/Firefox pour Browser Operator.
• Provider VLM coherent avec le modele.
• URL Hugging Face avec /v1/.
• Check Model Availability.
• Max Loop bas au debut.
• Loop Wait Time plus haut pour pages lentes.
• Fenetres visibles et simples.
• Attention aux cookie banners, popups et modals.

Mon parcours d’apprentissage

1. Installer l’app desktop.
2. Donner les permissions.
3. Configurer un provider VLM supporte.
4. Check Model Availability.
5. Tache de recherche browser.
6. Tache locale sans mutation.
7. Petit changement local reversible.
8. Inspecter/exporter le rapport.
9. Tester Browser Operator.
10. Lire le SDK et mapper GUIAgent, model, operator.
11. Construire un operator custom seulement apres avoir compris l’app desktop.

La lecon principale : UI-TARS Desktop n’est pas un chatbot. C’est une boucle observation ecran -> prediction modele -> execution operator. Une fois cette boucle claire, les permissions, screenshots, action spaces, providers, loop limits, reports et garde-fous deviennent beaucoup plus faciles a comprendre.