Article original : How to Build a Real-time AI Gym Coach with Vision Agents
La vision par ordinateur transforme la façon dont les gens s'entraînent, des séances à domicile aux miroirs de sport intelligents.
Imaginez entrer dans votre salle de sport personnelle, allumer votre caméra et disposer d'un coach IA qui observe vos mouvements, compte vos répétitions et corrige votre posture en temps réel.
C'est exactement ce que nous allons construire dans ce tutoriel : un compagnon de sport et coach de fitness en temps réel.
Nous intégrerons l'inférence vidéo à faible latence de Vision Agents pour détecter les schémas de mouvement, compter les répétitions et donner un retour vocal instantané comme « Redressez votre dos ! » ou « Gardez une posture gainée ! », tout comme le ferait un entraîneur humain.
Voici une vidéo de démonstration du compagnon de sport IA lors d'une séance d'entraînement :
Ce que nous allons aborder :
Prérequis
Python 3.13 ou supérieur
Des clés API pour :
Gemini (pour le LLM multimodal en temps réel)
Stream (pour l'infrastructure vidéo/audio)
Alternativement : OpenAI (si vous utilisez OpenAI Realtime à la place)
Un éditeur de code comme VS Code ou Windsurf
Configuration du projet
Créez un nouveau répertoire sur votre ordinateur appelé gym_buddy. Vous pouvez également le faire directement dans votre terminal avec cette commande :
mkdir gym_buddy
Ouvrez ensuite le répertoire dans votre IDE (pour ce guide, j'utilise Windsurf IDE).
Si vous n'avez pas uv (un installateur et résolveur de paquets Python rapide) installé sur votre ordinateur, installez-le avec cette commande :
pip install uv
Note : Après avoir installé uv, vous pouvez également exécuter uv -init pour configurer le projet avec des fichiers d'exemple et un fichier .toml contenant les métadonnées.
Ensuite, nous allons créer le fichier pyproject.toml. Il s'agit d'un fichier de configuration pour les projets Python qui spécifie les exigences du système de construction et d'autres métadonnées du projet. C'est un fichier standard utilisé par les outils modernes de packaging Python.
Saisissez le code ci-dessous :
[project]
name = "gym-buddy"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"python-dotenv>=1.0",
"vision-agents",
"vision-agents-plugins-openai",
"vision-agents-plugins-getstream",
"vision-agents-plugins-ultralytics",
"vision-agents-plugins-gemini",
]
[tool.uv.sources]
"vision-agents" = {path = "../../agents-core", editable=true}
"vision-agents-plugins-deepgram" = {path = "../../plugins/deepgram", editable=true}
"vision-agents-plugins-ultralytics" = {path = "../../plugins/ultralytics", editable=true}
"vision-agents-plugins-openai" = {path = "../../plugins/openai", editable=true}
"vision-agents-plugins-getstream" = {path = "../../plugins/getstream", editable=true}
"vision-agents-plugins-gemini" = {path = "../../plugins/gemini", editable=true}
Vous pouvez également créer un fichier requirements.in avec uniquement les dépendances directes, comme ceci :
python-dotenv>=1.0
vision-agents
vision-agents-plugins-openai
vision-agents-plugins-getstream
vision-agents-plugins-ultralytics
vision-agents-plugins-gemini
Installez ensuite les dépendances à l'aide de uv et de l'une de ces commandes :
uv sync
Cela générera le fichier uv.lock du gestionnaire de paquets uv qui gère les dépendances et les builds du projet.
Si vous utilisez Windows, vous pourriez rencontrer une erreur d'installation des dépendances, particulièrement avec NumPy. Cela est probablement dû à l'absence d'outils de compilation sur votre système.
Pourquoi NumPy est requis
NumPy est une bibliothèque Python pour le calcul numérique. Dans ce projet, elle est utilisée par les composants de vision par ordinateur et d'IA (tels que la détection basée sur YOLO et Vision Agents) pour manipuler les données d'image, les boîtes de délimitation (bounding boxes), les coordonnées et autres sorties numériques produites lors de l'analyse vidéo en temps réel.
De nombreuses bibliothèques utilisées ici en dépendent pour les opérations rapides sur les tableaux et les calculs mathématiques. C'est pourquoi NumPy est installé lors de la configuration et pourquoi les problèmes liés à son installation peuvent affecter l'ensemble du pipeline.
Pour résoudre ce problème, installez les Visual Studio Build Tools (requis pour compiler les paquets Python avec des extensions C). Lors de l'installation, assurez-vous de sélectionner « Développement Desktop en C++ ». Cela installe tous les outils de compilation nécessaires.
Visual Studio s'affiche comme ceci une fois l'installation terminée. Vous devrez peut-être redémarrer votre ordinateur pour que les mises à jour prennent effet.
Exécutez maintenant cette commande dans votre terminal :
python -m pip install -e .
La commande ci-dessus installe toutes les dépendances nécessaires au projet.
Comment obtenir vos clés API
Pour ce projet, nous devons obtenir des clés API de Stream et Gemini/OpenAI.
Pour obtenir votre clé API Stream, inscrivez-vous avec votre méthode préférée.
Ensuite, accédez à votre tableau de bord et cliquez sur « Create App » pour créer une nouvelle application pour le compagnon de sport IA.
Saisissez le nom de l'application, choisissez l'environnement (Development/Production), sélectionnez une région et cliquez sur « Create App ».
Après avoir créé l'application, cliquez sur l'onglet d'aperçu du tableau de bord dans la barre latérale gauche, puis accédez à l'onglet Video et cliquez sur « API Keys ». Copiez votre clé API et votre secret, et conservez-les en lieu sûr.
Pour obtenir votre clé API Gemini, visitez le site Google AI Studio, puis cliquez sur « Get started ».
Ensuite, allez sur votre tableau de bord et cliquez sur « Create API key ».
Saisissez un nom pour la clé, puis créez un nouveau projet pour la clé API.
Une fois la nouvelle clé API créée, copiez-la et conservez-la en lieu sûr.
Création du compagnon de sport IA
Maintenant que vous avez les clés API nécessaires, créez un fichier .env dans le répertoire racine du projet et ajoutez toutes les clés API comme ceci :
GEMINI_API_KEY=votre_cle_gemini
STREAM_API_KEY=votre_cle_stream
STREAM_API_SECRET=votre_secret_stream
Si vous utilisez OpenAI au lieu de Gemini, ajoutez également :
OPENAI_API_KEY=votre_cle_openai
Voici la structure du projet et de la base de code pour l'application de compagnon de sport que nous construisons :
Dans le répertoire racine, créez un fichier __init__.py vide. Ce fichier permet à Python de traiter le répertoire comme un paquet. Vous pouvez ajouter un commentaire dans le fichier pour vous en souvenir, comme ceci :
# Ce fichier permet à Python de traiter le répertoire comme un paquet.
Ensuite, créez un fichier gym_buddy.py. C'est le fichier principal de l'application, contenant la configuration de l'agent et la logique de connexion à l'appel pour le Gym Companion. Saisissez le code ci-dessous dans le fichier :
import logging
from dotenv import load_dotenv
from vision_agents.core import User, Agent, cli
from vision_agents.core.agents import AgentLauncher
from vision_agents.plugins import getstream, ultralytics, gemini
logger = logging.getLogger(__name__)
load_dotenv()
async def create_agent(**kwargs) -> Agent:
agent = Agent(
edge=getstream.Edge(), # use stream for edge video transport
agent_user=User(name="AI gym companion"),
instructions="Read @gym_buddy.md", # read the gym buddy markdown instructions
llm=gemini.Realtime(fps=3), # Share video with gemini
# llm=openai.Realtime(fps=3), use this to switch to openai
processors=[
ultralytics.YOLOPoseProcessor(model_path="yolo11n-pose.pt")
], # realtime pose detection with yolo
)
return agent
async def join_call(agent: Agent, call_type: str, call_id: str, **kwargs) -> None:
call = await agent.create_call(call_type, call_id)
# join the call and open a demo env
with await agent.join(call):
await agent.llm.simple_response(
text="Say hi. After the user does their exercise, offer helpful feedback."
)
await agent.finish() # run till the call ends
if __name__ == "__main__":
cli(AgentLauncher(create_agent=create_agent, join_call=join_call))
Ensuite, créez un fichier gym_buddy.md. Il s'agit d'un fichier d'instructions pour le guide de coaching de l'agent, qu'il suivra lors de l'analyse des entraînements et de la fourniture de retours en temps réel. Saisissez le code markdown ci-dessous :
You are a voice fitness coach. You will watch the user's workout and offer feedback.
The video clarifies the body position using Yolo's pose analysis, so you'll see their exact movement.
Speak with a high-energy, motivating tone. Be strict about form but encouraging. Do not give feedback if you are not sure or do not see an exercise.
# Gym Workout Coaching Guide
## 1. Introduction
A fitness coach's primary responsibility is to ensure safety and efficacy in every movement. While everybody is different, the fundamental mechanics of human movement—stability, alignment, and range of motion—remain constant. By monitoring key checkpoints like spinal alignment, joint tracking, and tempo, coaches can guide athletes toward stronger, injury-free workouts. The following guidelines break down the core compound movements into phases, with clear teaching points and coaching cues.
## 2. The Squat: Setup and Stance
The squat is the king of lower-body exercises, but it starts before the descent. The athlete should stand with feet shoulder-width apart or slightly wider, toes pointed slightly outward (5-30 degrees). The spine must be neutral, chest proud, and core braced. Coaches should watch for collapsing arches in the feet or a rounded upper back. A solid setup creates the tension needed for a powerful lift.
## 3. The Squat: Descent (Eccentric Phase)
The movement begins by breaking at the hips and knees simultaneously. The hips should travel back and down, as if sitting in a chair, while the knees track in line with the toes. Coaches must ensure the heels stay glued to the floor. Common errors include "knee valgus" (knees caving in) or the torso collapsing forward. The descent should be controlled and deliberate.
## 4. The Squat: Depth and Reversal
"Depth" is achieved when the hip crease drops below the top of the knee (parallel). While not everyone has the mobility for this, it is the standard for a full range of motion. At the bottom, the athlete should maintain tension—no bouncing or relaxing. The reversal (concentric phase) is driven by driving the feet into the floor and extending the hips and knees, exhaling forcefully.
## 5. The Push-up: The Plank Foundation
A perfect push-up is essentially a moving plank. The setup requires hands placed slightly wider than shoulder-width, directly under the shoulders. The body must form a straight line from head to heels. Coaches should watch for sagging hips (lumbar extension) or piking hips (flexion). Glutes and quads should be squeezed tight to lock the body into a rigid lever.
## 6. The Push-up: Mechanics
As the athlete lowers themselves, the elbows should track back at roughly a 45-degree angle to the torso, forming an arrow shape, not a "T". The chest should descend until it nearly touches the floor. The neck must remain neutral—no reaching with the chin. The push back up should be explosive, fully extending the arms without locking the elbows violently.
## 7. The Lunge: Step and Stability
The lunge challenges balance and unilateral strength. Whether forward or reverse, the step should be long enough to allow both knees to bend to approximately 90 degrees at the bottom. The feet should remain hip-width apart throughout the movement, like moving on train tracks, not a tightrope. Coaches should look for wobbling or the front heel lifting off the ground.
## 8. The Lunge: Alignment
In the bottom position, the front knee should be directly over the ankle, not shooting far past the toes (though some forward travel is acceptable). The torso should remain upright or have a very slight forward lean; collapsing over the front thigh is a fault. The back knee should hover just an inch off the ground. Drive through the front heel to return to the start.
## 9. Tempo and Control
Time under tension builds muscle and control. Coaches should encourage a specific tempo, such as 2-0-1 (2 seconds down, 0 pause, 1 second up). Rushing through reps often masks muscle imbalances and relies on momentum rather than strength. If an athlete speeds up, cue them to "slow down and own the movement."
## 10. Breathing Mechanics
Proper breathing stabilises the core. The general rule is to inhale during the eccentric phase (lowering) and exhale during the concentric phase (lifting/pushing). For heavy lifts, the Valsalva manoeuvre (bracing the core with a held breath) may be appropriate, but for general fitness, rhythmic breathing ensures oxygen delivery and blood pressure management.
## 11. Common Faults and Fixes
- **Squat - Butt Wink**: Posterior pelvic tilt at the bottom. Fix: Limit depth or improve hamstring/ankle mobility.
- **Push-up - Winging Scapula**: Shoulder blades popping up. Fix: Push the floor away at the top (protraction) and engage serratus anterior.
- **Lunge - Valgus Knee**: Front knee collapsing in. Fix: Cue "push the knee out" and engage the glute medius.
- **General - Ego Lifting**: Sacrificing form for reps or weight. Fix: Regress the exercise or slow the tempo
Comment fonctionne l'agent IA
Nous avons maintenant configuré le fichier d'instructions pour l'agent IA. Voyons comment le code interagit avec la création de l'agent et le fichier d'instructions Markdown ci-dessus. Dans gym_buddy.py, l'agent est créé et initialisé avec des composants spécifiques comme ceci :
def create_agent() -> Agent:
# Initialize video transport
video_transport = StreamVideoTransport()
# Set up AI components
gemini = GeminiRealtime()
pose_processor = YOLOPoseProcessor(model_path="yolo11n-pose.pt")
# Create agent with instructions
return Agent(
name="AI Gym Buddy",
instructions="gym_buddy.md", # Loads coaching instructions
video_transport=video_transport,
llm=gemini,
processors=[pose_processor]
)
Le fichier gym_buddy.md contient des instructions structurées qui guident le comportement de l'agent compagnon de sport.
## Coaching Style
- Be encouraging and positive
- Provide clear, actionable feedback
- Focus on one correction at a time
## Squat Form
- Keep chest up and back straight
- Knees should track over toes
- Lower until thighs are parallel to ground
- Push through heels to stand
## Safety Guidelines
- Stop user if a dangerous form is detected
- Suggest modifications for beginners
- Remind to keep core engaged
Ces instructions sont chargées avec le paramètre instructions="gym_buddy.md" dans le fichier gym_buddy.py. L'agent analyse ensuite ce fichier pour comprendre comment évaluer votre posture pendant la séance d'entraînement et fournir des retours.
# Processing video frames
async def process_frame(self, frame):
# Analyze pose using YOLO
poses = await self.pose_processor.process(frame)
# Generate feedback based on instructions
feedback = await self.llm.generate_feedback(
poses=poses,
instructions=self.instructions
)
return feedback
Lorsqu'il donne un retour, l'agent compare les poses détectées avec la posture idéale décrite dans le markdown. Ensuite, il génère un retour en langage naturel en utilisant le ton et le style spécifiés. Les consignes de sécurité dans gym_buddy.md sont vérifiées en priorité, puis les corrections de posture spécifiques sont mentionnées par l'agent.
Pour ajouter un nouvel exercice, vous pouvez mettre à jour le fichier gym_buddy.md avec une nouvelle section comme celle-ci :
## Push-up Form
- Keep body in a straight line
- Lower until chest nearly touches floor
- Push through palms to return up
- Keep core engaged
L'agent intégrera automatiquement ces instructions lors de sa prochaine exécution. Cela facilite la mise à jour et l'extension des capacités de l'agent en éditant simplement le fichier markdown.
Vous pouvez consulter le code complet du AI Gym Companion dans le dépôt GitHub.
Comment lancer l'application
Tout d'abord, créez un environnement virtuel en Python avec cette commande :
python -m venv venv
Cela crée le répertoire .venv.
Activez ensuite l'environnement virtuel Python comme ceci :
.\venv\Scripts\activate
Lancez maintenant l'agent IA avec cette commande :
uv run gym_buddy.py
Vous pouvez également démarrer l'application avec cette commande :
python gym_buddy.py
Le chargement commence ainsi :
L'agent IA va :
Créer un appel vidéo
Ouvrir une interface de démonstration dans votre navigateur
Rejoindre l'appel et commencer l'observation
Vous demander de faire un exercice de squat
Analyser vos mouvements et positions, puis fournir un retour
La sortie du terminal ci-dessus montre également que Gemini AI est connecté.
L'agent se charge ensuite dans votre navigateur comme ceci :
Une fenêtre modale s'affiche également pour présenter les Vision Agents. Vous pouvez ignorer l'introduction ou cliquer sur Next pour continuer.
Le Vision Agent utilise un edge global pour garantir une latence d'appel optimale. C'est essentiel pour que le compagnon de sport IA puisse fournir des retours en temps réel sur les exercices effectués par les utilisateurs.
Le compagnon de sport IA peut également envoyer des messages de chat sur les exercices via la boîte de dialogue affichée sur le côté droit de l'interface. Ceci est possible grâce au SDK/API de chat.
Lorsque vous effectuez un squat, le Vision Agent (propulsé par Gemini) analyse les images vidéo en temps réel. Il détecte la fin du mouvement et déclenche l'outil send_rep_count. Cela met instantanément à jour le compteur d'exercices sur votre écran et fournit une réponse textuelle et vocale encourageante !
Voici une vidéo de démonstration du compagnon de sport IA lors d'une séance d'entraînement :
Vous pouvez également copier le lien et le partager, ou scanner le code QR ci-dessous pour tester le Gym Companion sur votre téléphone mobile.
Si vous souhaitez le tester sur votre téléphone, installez l'application Stream Video calls pour les appareils iOS pour une meilleure expérience mobile.
Prochaines étapes
Dans ce tutoriel, vous avez appris à construire un compagnon de sport IA à l'aide de Vision Agents.
Le Real-Time Gym Companion illustre comment l'IA de vision permet une interactivité de type humain en fusionnant :
La perception vidéo (voir)
La compréhension par LLM (penser)
Le retour vocal (parler)
Cette technologie à faible latence vous permet de créer des applications de fitness en temps réel qui donnent des retours instantanés, tout comme le ferait un entraîneur personnel.
Vous pouvez découvrir d'autres cas d'utilisation de projets avec Vision Agents dans le dépôt GitHub.