AI Agents · Leçon

Analyser les arguments et rédiger l’aide

Arguments obligatoires ou facultatifs, validation des types et aide générée automatiquement.

Analyser les arguments et rédiger l’aide est une leçon AI Agents gratuite sur CoddyKit. Ceci est la leçon 3 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage AI Agents, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours AI Agents comprend 4 leçons au total.

Une bonne conception de CLI commence par de bons arguments

Une interface d’arguments bien conçue pour un agent CLI permet aux utilisateurs de comprendre comment utiliser l’outil à partir de --help uniquement. Chaque argument doit avoir un nom clair, un type, une valeur par défaut et une description.

Des arguments mal nommés ou non documentés rendent les outils frustrants à utiliser et difficiles à maintenir.

Arguments obligatoires ou facultatifs

Les arguments obligatoires doivent être fournis : la CLI se termine avec une erreur s’ils sont absents. Les arguments facultatifs possèdent une valeur default= et peuvent être omis. Le choix entre les deux influence l’expérience utilisateur de votre outil.

import argparse

parser = argparse.ArgumentParser(description='AI Agent CLI')

# Required: no default, must be provided
parser.add_argument(
    '--query', '-q',
    type=str,
    required=True,
    help='Question to send to the agent'
)

# Optional: has a default, can be omitted
parser.add_argument(
    '--model', '-m',
    type=str,
    default='gpt-4o-mini',
    help='Model name (default: gpt-4o-mini)'
)

parser.add_argument(
    '--max-tokens',
    type=int,
    default=1000,
    help='Maximum tokens in response (default: 1000)'
)

args = parser.parse_args(['--query', 'test'])
print(args.query, args.model, args.max_tokens)

Validation des types

Le paramètre type= convertit automatiquement l’entrée textuelle et la valide. Utilisez des types intégrés comme int, float et bool, ou une fonction personnalisée pour les validations plus complexes.

import argparse

def positive_int(value: str) -> int:
    n = int(value)
    if n <= 0:
        raise argparse.ArgumentTypeError(f'{value} must be a positive integer')
    return n

parser = argparse.ArgumentParser()
parser.add_argument('--temperature', type=float, help='LLM temperature 0.0-2.0')
parser.add_argument('--max-results', type=positive_int, default=5,
                    help='Number of results to return (must be > 0)')
parser.add_argument('--timeout', type=float, default=30.0,
                    help='Request timeout in seconds')

# These would be rejected with helpful error messages:
# --temperature abc     -> invalid float value
# --max-results -1      -> must be positive integer
args = parser.parse_args(['--temperature', '0.7', '--max-results', '3'])
print(args.temperature, args.max_results)

Choix : restreindre les valeurs valides

Le paramètre choices=[...] limite l’argument à un ensemble fixe de valeurs autorisées. argparse effectue automatiquement cette validation et répertorie les options dans le texte d’aide.

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--format',
    choices=['json', 'text', 'markdown'],
    default='text',
    help='Output format: json, text, or markdown'
)

parser.add_argument(
    '--model',
    choices=['gpt-4o', 'gpt-4o-mini', 'claude-3-5-sonnet', 'gemini-1.5-flash'],
    default='gpt-4o-mini',
    help='Model to use'
)

# Error if invalid value given:
# python agent.py --format xml
# agent.py: error: argument --format: invalid choice: 'xml'
# (choose from 'json', 'text', 'markdown')
args = parser.parse_args(['--format', 'json'])
print(args.format)  # 'json'

Indicateurs booléens avec store_true

Les indicateurs booléens permettent d’activer ou de désactiver une option par leur présence ou leur absence : aucune valeur n’est fournie. Utilisez action='store_true' pour définir un indicateur à True lorsqu’il est présent et à False lorsqu’il est absent.

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--verbose', '-v',
    action='store_true',
    help='Enable verbose output showing agent reasoning steps'
)

parser.add_argument(
    '--no-cache',
    action='store_true',
    help='Disable response caching'
)

parser.add_argument(
    '--dry-run',
    action='store_true',
    help='Parse arguments but do not run the agent'
)

# Usage: python agent.py --query 'test' --verbose
args = parser.parse_args(['--verbose'])
print(f'verbose={args.verbose}')    # True
print(f'no_cache={args.no_cache}')  # False
print(f'dry_run={args.dry_run}')    # False

metavar : contrôler l’affichage du texte d’aide

Par défaut, argparse affiche le nom de l’argument en majuscules dans le texte d’aide : --query QUERY. Utilisez metavar= pour afficher un paramètre fictif plus explicite comme QUESTION ou URL.

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--query',
    type=str,
    metavar='QUESTION',  # shown in help as: --query QUESTION
    required=True,
    help='Natural language question for the agent'
)

parser.add_argument(
    '--url',
    type=str,
    metavar='URL',       # shown in help as: --url URL
    help='URL to scrape and summarize'
)

parser.add_argument(
    '--temperature',
    type=float,
    metavar='0.0-2.0',   # shown in help as: --temperature 0.0-2.0
    default=0.7
)

# Help output:
# --query QUESTION    Natural language question for the agent
# --url URL           URL to scrape and summarize
print('metavar makes help text more informative')

Plusieurs valeurs avec nargs

Utilisez nargs='+' pour accepter une ou plusieurs valeurs, ou nargs='*' pour zéro valeur ou davantage. Cela est utile pour transmettre à l’agent des listes d’URL, d’étiquettes ou de chemins de fichiers.

import argparse

parser = argparse.ArgumentParser()

parser.add_argument(
    '--urls',
    nargs='+',       # one or more URLs
    metavar='URL',
    help='URLs to analyze (space-separated)'
)

parser.add_argument(
    '--tags',
    nargs='*',       # zero or more tags
    default=[],
    help='Optional tags for filtering results'
)

# Usage: python agent.py --urls https://a.com https://b.com --tags ai research
args = parser.parse_args(
    ['--urls', 'https://a.com', 'https://b.com', '--tags', 'ai']
)
print(args.urls)  # ['https://a.com', 'https://b.com']
print(args.tags)  # ['ai']

Sous-commandes avec add_subparsers()

Les sous-commandes, comme git commit et git push, donnent à chaque commande son propre ensemble d’arguments. Utilisez add_subparsers() pour les définir avec argparse.

import argparse

parser = argparse.ArgumentParser(description='AI Agent CLI')
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# 'ask' subcommand
ask_parser = subparsers.add_parser('ask', help='Ask the agent a question')
ask_parser.add_argument('question', type=str, help='Question to ask')
ask_parser.add_argument('--model', default='gpt-4o-mini')

# 'search' subcommand
search_parser = subparsers.add_parser('search', help='Research a topic')
search_parser.add_argument('topic', type=str, help='Topic to research')
search_parser.add_argument('--depth', type=int, default=3, choices=[1, 2, 3])

args = parser.parse_args(['ask', 'What is Python?', '--model', 'gpt-4o'])
print(args.command)   # 'ask'
print(args.question)  # 'What is Python?'
print(args.model)     # 'gpt-4o'

Rédiger un texte d’aide efficace

Un bon texte d’aide répond à trois questions : que fait cet argument, quelles valeurs sont valides et quelle est la valeur par défaut ? Rédigez le texte d’aide du point de vue de l’utilisateur, et non de celui de la personne qui l’implémente.

import argparse

parser = argparse.ArgumentParser(
    description='AI Research Agent — answers questions using web search and LLMs.',
    epilog='Example: python agent.py --query "What is quantum computing?" --format json'
)

# Bad help text:
parser.add_argument('--t', type=float, help='t value')  # cryptic

# Good help text:
parser.add_argument(
    '--temperature',
    type=float,
    default=0.7,
    metavar='0.0-2.0',
    help='Sampling temperature for the LLM. Lower = more focused, higher = more creative. (default: 0.7)'
)

print('Good help text explains what, how, and default value')

Groupes d’arguments pour les CLI complexes

Lorsqu’une CLI possède de nombreux arguments, regroupez-les par thème avec add_argument_group(). La sortie de --help devient ainsi beaucoup plus facile à lire.

import argparse

parser = argparse.ArgumentParser(description='AI Agent CLI')

# Group 1: required inputs
required_group = parser.add_argument_group('Required')
required_group.add_argument('--query', required=True, help='Question to ask')

# Group 2: LLM settings
llm_group = parser.add_argument_group('LLM Settings')
llm_group.add_argument('--model', default='gpt-4o-mini', help='Model name')
llm_group.add_argument('--temperature', type=float, default=0.7)
llm_group.add_argument('--max-tokens', type=int, default=1000)

# Group 3: output settings
output_group = parser.add_argument_group('Output')
output_group.add_argument('--format', choices=['text', 'json'], default='text')
output_group.add_argument('--verbose', action='store_true')

print('Argument groups organize --help output by category')

Valeurs de repli provenant de variables d’environnement

Permettez aux arguments d’utiliser des variables d’environnement comme valeurs de repli lorsqu’ils ne sont pas fournis. Les utilisateurs peuvent ainsi définir des valeurs par défaut dans le profil de leur interpréteur de commandes sans devoir les saisir à chaque fois.

import argparse
import os

os.environ['OPENAI_API_KEY'] = 'sk-proj-demo-key'

parser = argparse.ArgumentParser()

parser.add_argument(
    '--api-key',
    type=str,
    default=os.environ.get('OPENAI_API_KEY'),
    help='OpenAI API key (default: $OPENAI_API_KEY env var)'
)

parser.add_argument(
    '--model',
    type=str,
    default=os.environ.get('AGENT_MODEL', 'gpt-4o-mini'),
    help='Model to use (default: $AGENT_MODEL or gpt-4o-mini)'
)

args = parser.parse_args([])

if not args.api_key:
    parser.error('--api-key is required (or set OPENAI_API_KEY environment variable)')

print(f'Model: {args.model}')

Vérification des connaissances : analyse des arguments

Vérifiez votre compréhension des techniques d’analyse des arguments d’une CLI.

Récapitulatif : analyse des arguments et texte d’aide

Vous savez maintenant créer une interface complète et conviviale pour les arguments d’une CLI :

Utiliser required=True pour les arguments obligatoires et default= pour les arguments facultatifs
Valider les types d’entrée avec type= et des fonctions de validation personnalisées
Restreindre les valeurs avec choices=[...]
Utiliser action='store_true' pour les indicateurs booléens
Améliorer la lisibilité de l’aide avec metavar= et des chaînes help= claires
Accepter plusieurs valeurs avec nargs='+'
Utiliser des sous-commandes et des groupes d’arguments pour les CLI complexes
Utiliser des variables d’environnement comme valeurs de repli pour les paramètres courants

Questions Fréquemment Posées

La leçon « Analyser les arguments et rédiger l’aide » est-elle gratuite ?

Oui — le texte complet de « Analyser les arguments et rédiger l’aide » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours AI Agents, passe à CoddyKit PRO. Le cours AI Agents comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Analyser les arguments et rédiger l’aide » ?

Arguments obligatoires ou facultatifs, validation des types et aide générée automatiquement. Tu pratiques AI Agents avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer AI Agents ?

Aucune expérience préalable n'est requise. AI Agents sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 3 sur 4.

Combien de temps prend la leçon « Analyser les arguments et rédiger l’aide » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon AI Agents ?

Oui. Chaque leçon AI Agents inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

Créer des interfaces d’agents en ligne de commande
Agents interactifs de type REPL
Analyser les arguments et rédiger l’aide
Diffuser la sortie des agents CLI

← Retour à AI Agents