AI Agents · Lezione

Parsing degli argomenti e testo di aiuto

Argomenti obbligatori e facoltativi, convalida dei tipi e aiuto generato automaticamente

Lezione 3 di 413 passaggi

Parsing degli argomenti e testo di aiuto è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

Una buona progettazione CLI parte da buoni argomenti

Un'interfaccia CLI ben progettata per gli argomenti dell'agente permette agli utenti di capire come usare lo strumento leggendo soltanto --help. Ogni argomento dovrebbe avere un nome, un tipo, un valore predefinito e una descrizione chiari.

Argomenti con nomi poco chiari o privi di documentazione rendono gli strumenti frustranti da usare e difficili da mantenere.

Argomenti obbligatori e facoltativi

Gli argomenti obbligatori devono essere forniti: la CLI termina con un errore se mancano. Gli argomenti facoltativi hanno un valore default= e possono essere omessi. La decisione su quali usare influenza l'esperienza utente dello strumento.

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)

Validazione dei tipi

Il parametro type= converte automaticamente l'input testuale e lo convalida. Usi tipi integrati come int, float e bool, oppure una funzione personalizzata per convalide più complesse.

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)

Choices: limitazione dei valori validi

Il parametro choices=[...] limita l'argomento a un insieme fisso di valori consentiti. argparse esegue automaticamente la convalida ed elenca le opzioni nel testo di aiuto.

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'

Flag booleani con store_true

I flag booleani sono interruttori di presenza o assenza: non viene fornito alcun valore. Usi action='store_true' per impostare un flag su True quando è presente e su False quando è assente.

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: controllo della visualizzazione del testo di aiuto

Per impostazione predefinita, argparse mostra il nome dell'argomento in maiuscolo nel testo di aiuto: --query QUERY. Usi metavar= per visualizzare un segnaposto più informativo, come QUESTION o 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')

Più valori con nargs

Usi nargs='+' per accettare uno o più valori oppure nargs='*' per accettarne zero o più. È utile per passare all'agente elenchi di URL, tag o percorsi di file.

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']

Sottocomandi con add_subparsers()

I sottocomandi, come git commit e git push, forniscono a ogni comando il proprio insieme di argomenti. Usi add_subparsers() per definirli in 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'

Scrittura di un buon testo di aiuto

Un buon testo di aiuto risponde a tre domande: a cosa serve questo argomento, quali valori sono validi e qual è il valore predefinito? Scriva il testo di aiuto dal punto di vista dell'utente, non da quello di chi implementa lo strumento.

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')

Gruppi di argomenti per CLI complesse

Quando una CLI ha molti argomenti, li raggruppi per argomento usando add_argument_group(). In questo modo l'output di --help è molto più facile da leggere.

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')

Valori di riserva dalle variabili d'ambiente

Permetta agli argomenti di utilizzare le variabili d'ambiente come valori di riserva quando non vengono forniti. In questo modo gli utenti possono impostare i valori predefiniti nel profilo della shell senza doverli digitare ogni volta.

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}')

Verifica delle conoscenze: analisi degli argomenti

Verifichi la Sua comprensione delle tecniche di analisi degli argomenti CLI.

Rispondi nella lezione interattiva

Riepilogo: analisi degli argomenti e testo di aiuto

Ora sa come creare un'interfaccia CLI completa e intuitiva per gli argomenti:

Usi required=True per gli argomenti obbligatori e default= per quelli facoltativi
Convalidi i tipi di input con type= e funzioni di convalida personalizzate
Limiti i valori con choices=[...]
Usi action='store_true' per i flag booleani
Migliori la leggibilità dell'aiuto con metavar= e stringhe help= chiare
Accetti più valori con nargs='+'
Usi sottocomandi e gruppi di argomenti per CLI complesse
Utilizzi le variabili d'ambiente come valori di riserva per le impostazioni comuni

Gratis per iniziare

Impara AI Agents con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 60
Lezioni: 239

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Parsing degli argomenti e testo di aiuto» è gratuita?

Sì — il testo completo di «Parsing degli argomenti e testo di aiuto» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Parsing degli argomenti e testo di aiuto»?

Argomenti obbligatori e facoltativi, convalida dei tipi e aiuto generato automaticamente Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Agents?

Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «Parsing degli argomenti e testo di aiuto»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Agents?

Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Creazione di interfacce a riga di comando per agenti
Agenti interattivi in stile REPL
Parsing degli argomenti e testo di aiuto
Output in streaming negli agenti CLI

← Torna a AI Agents