0Pricing
AI Agents · Lezione

Creazione di interfacce a riga di comando per agenti

argparse, click e Typer per la gestione degli argomenti CLI degli agenti

Creazione di interfacce a riga di comando per agenti è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 1 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.

Perché creare una CLI per il proprio agente

Un'interfaccia a riga di comando (CLI) rende l'agente accessibile da un terminale, utilizzabile negli script delle pipeline e facile da testare senza un'interfaccia web. Molti agenti in produzione vengono distribuiti come strumenti CLI.

Python offre tre eccellenti librerie per creare CLI: argparse (libreria standard), Typer e Click.

argparse: l'opzione della libreria standard

argparse è integrato in Python: non è necessaria alcuna installazione. Utilizzi ArgumentParser() per definire l'interfaccia, add_argument() per dichiarare i parametri e parse_args() per elaborarli.

import argparse

def main(argv=None):
    parser = argparse.ArgumentParser(
        description='AI Agent CLI — ask questions and get answers'
    )
    parser.add_argument('--query', type=str, required=True, help='The question to ask the agent')
    parser.add_argument('--model', type=str, default='gpt-4o-mini', help='OpenAI model to use (default: gpt-4o-mini)')
    args = parser.parse_args(argv)

    print(f'Querying agent with: {args.query}')
    print(f'Using model: {args.model}')

if __name__ == '__main__':
    main(['--query', 'What is the weather today?'])

Eseguire una CLI con argparse e la guida generata automaticamente

argparse genera automaticamente un messaggio --help a partire dalle definizioni degli argomenti. Esegua python agent_cli.py --help per visualizzarlo. Gli argomenti obbligatori mancanti generano automaticamente messaggi di errore utili.

# How users invoke the CLI:
# python agent_cli.py --query 'What is the weather in Paris?'
# python agent_cli.py --query 'Summarize this' --model gpt-4o
# python agent_cli.py --help

# Auto-generated help output:
# usage: agent_cli.py [-h] --query QUERY [--model MODEL]
#
# AI Agent CLI -- ask questions and get answers
#
# options:
#   -h, --help     show this help message and exit
#   --query QUERY  The question to ask the agent
#   --model MODEL  OpenAI model to use (default: gpt-4o-mini)

print('argparse generates help text automatically from your definitions')

Typer: CLI moderna con annotazioni di tipo

Typer crea CLI a partire dalle annotazioni di tipo di Python, con meno codice ripetitivo rispetto ad argparse. Installi con pip install typer. I parametri delle funzioni diventano automaticamente argomenti CLI.

# pip install typer
import typer

app = typer.Typer(help='AI Agent CLI')

@app.command()
def ask(
    query: str = typer.Option(..., '--query', '-q', help='Question for the agent'),
    model: str = typer.Option('gpt-4o-mini', '--model', '-m', help='Model to use'),
    verbose: bool = typer.Option(False, '--verbose', '-v', help='Show reasoning steps')
):
    typer.echo(f'Query: {query}')
    typer.echo(f'Model: {model}')
    if verbose:
        typer.echo('Verbose mode enabled')
    # result = run_agent(query, model=model, verbose=verbose)

if __name__ == '__main__':
    app()

Click: framework CLI basato sui decoratori

Click usa i decoratori per definire comandi e opzioni CLI. Installi con pip install click. Offre funzionalità avanzate come gruppi di comandi, prompt e barre di avanzamento.

# pip install click
import click

@click.command()
@click.option('--query', '-q', required=True, help='Question for the agent')
@click.option('--model', '-m', default='gpt-4o-mini', help='LLM model to use')
@click.option('--output', '-o', type=click.Path(), help='Save output to file')
def ask(query: str, model: str, output: str):
    click.echo(f'Sending: {query}')
    # result = run_agent(query, model=model)
    # click.echo(result['answer'])

    if output:
        with open(output, 'w') as f:
            f.write('result["answer"]')
        click.echo(f'Saved to {output}')

if __name__ == '__main__':
    ask()

Aggiunta dei sottocomandi

Man mano che l'agente cresce, organizzi le funzionalità in sottocomandi come agent ask, agent search e agent history. Sia Click sia Typer supportano nativamente i gruppi di sottocomandi.

import typer

app = typer.Typer(help='AI Research Agent')

@app.command()
def ask(query: str = typer.Argument(..., help='Question to ask')):
    'Ask the agent a question'
    typer.echo(f'Asking: {query}')

@app.command()
def search(topic: str = typer.Argument(..., help='Topic to research')):
    'Search and summarize a topic'
    typer.echo(f'Researching: {topic}')

@app.command()
def history(limit: int = typer.Option(10, help='Number of past queries to show')):
    'Show recent query history'
    typer.echo(f'Showing last {limit} queries')

if __name__ == '__main__':
    app()

# Usage: python agent.py ask 'What is AI?'
#        python agent.py search 'Python async'
#        python agent.py history --limit 5

Lettura da stdin per l'input tramite pipe

Un agente CLI che legge da stdin può essere utilizzato nelle pipeline Unix. Usi sys.stdin o il tipo di argomento stdin di Click per accettare contenuti tramite pipe.

import sys
import click

@click.command()
@click.argument('input', default='-', type=click.File('r'))
@click.option('--task', default='summarize', help='Task: summarize, translate, or analyze')
def process(input, task: str):
    text = input.read().strip()
    if not text:
        click.echo('Error: no input provided', err=True)
        raise SystemExit(1)

    click.echo(f'Task: {task}')
    click.echo(f'Input length: {len(text)} chars')
    # result = agent.run(task=task, content=text)
    # click.echo(result)

# Usage:
# echo 'Hello world' | python agent_cli.py --task translate
# cat article.txt | python agent_cli.py --task summarize
if __name__ == '__main__':
    process()

Indicatori di avanzamento per attività lunghe

Le attività dell'agente possono richiedere diversi secondi. Mostri uno spinner o un messaggio di avanzamento, così gli utenti sanno che l'agente è in funzione. Typer offre un supporto integrato per l'avanzamento tramite la libreria rich.

import typer
from time import sleep

app = typer.Typer()

@app.command()
def research(topic: str = typer.Argument(...)):
    typer.echo(f'Researching: {topic}')

    with typer.progressbar(range(5), label='Gathering sources') as progress:
        for i in progress:
            sleep(0.5)  # simulate work

    typer.echo('Done!')
    typer.echo('Result: [mocked research result]')

# Or with a spinner from rich:
# from rich.console import Console
# console = Console()
# with console.status('Thinking...'):
#     result = agent.run(topic)
# console.print(result)

if __name__ == '__main__':
    app()

Formattazione dell'output: JSON o testo normale

Permetta agli utenti di scegliere tra formati di output leggibili dalle persone e dalle macchine. Un flag --json è utile per passare l'output dell'agente ad altri strumenti tramite pipe.

import json
import typer

app = typer.Typer()

@app.command()
def ask(
    query: str = typer.Argument(...),
    as_json: bool = typer.Option(False, '--json', help='Output as JSON')
):
    result = {
        'query': query,
        'answer': 'Paris is the capital of France.',
        'confidence': 0.98,
        'sources': ['https://wikipedia.org/France']
    }

    if as_json:
        typer.echo(json.dumps(result, indent=2))
    else:
        typer.echo(f'Answer: {result["answer"]}')
        typer.echo(f'Sources: {', '.join(result["sources"])}')

if __name__ == '__main__':
    app()

Gestione degli errori negli agenti CLI

In caso di errore, termini con un codice diverso da zero, così gli script chiamanti possono rilevare i problemi. Usi typer.echo(..., err=True) o click.echo(..., err=True) per scrivere i messaggi di errore su stderr.

import sys
import typer

app = typer.Typer()

@app.command()
def ask(query: str = typer.Argument(...)):
    try:
        # result = agent.run(query)
        result = {'status': 'ok', 'answer': 'Result here'}

        if result['status'] != 'ok':
            typer.echo(f'Agent error: {result.get("error")}', err=True)
            raise typer.Exit(code=1)

        typer.echo(result['answer'])

    except Exception as e:
        typer.echo(f'Unexpected error: {e}', err=True)
        raise typer.Exit(code=2)

# Exit codes: 0 = success, 1 = agent error, 2 = unexpected error
# These allow shell scripts to handle failures:
# python agent.py 'query' || echo 'Agent failed'
if __name__ == '__main__':
    app()

Trasformare l'agente in uno strumento CLI installabile

Usi un punto di ingresso in pyproject.toml per rendere l'agente disponibile come comando di sistema. Dopo pip install -e ., gli utenti possono eseguire myagent ask 'question' direttamente da qualsiasi directory.

# pyproject.toml
# [project]
# name = 'myagent'
# version = '0.1.0'
# dependencies = ['typer', 'openai', 'httpx']
#
# [project.scripts]
# myagent = 'myagent.cli:app'

# After pip install -e .:
# myagent ask 'What is AI?'
# myagent search 'Python tutorials'
# myagent --help

# This is how production CLI agents like 'gh', 'poetry', and 'ruff' work
print('Entry points turn your Python module into a system CLI command')

Verifica delle conoscenze: interfacce CLI per agenti

Verifichi la Sua comprensione della creazione di interfacce CLI per gli agenti.

Riepilogo: creazione di interfacce CLI per agenti

Ora può creare interfacce CLI professionali per i Suoi agenti:

  • Usi argparse per CLI senza dipendenze (libreria standard)
  • Usi typer per CLI chiare e basate sulle annotazioni di tipo
  • Usi click per CLI ricche di funzionalità e basate sui decoratori
  • Organizzi gli agenti di grandi dimensioni con i sottocomandi
  • Supporti stdin per l'integrazione nelle pipeline
  • Usi i flag --json per un output leggibile dalle macchine
  • Termini con codici diversi da zero in caso di errore, per garantire la compatibilità con gli script shell

Domande Frequenti

La lezione «Creazione di interfacce a riga di comando per agenti» è gratuita?

Sì — il testo completo di «Creazione di interfacce a riga di comando per agenti» è 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 «Creazione di interfacce a riga di comando per agenti»?

argparse, click e Typer per la gestione degli argomenti CLI degli agenti 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 1 di 4.

Quanto tempo richiede la lezione «Creazione di interfacce a riga di comando per agenti»?

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

  1. Creazione di interfacce a riga di comando per agenti
  2. Agenti interattivi in stile REPL
  3. Parsing degli argomenti e testo di aiuto
  4. Output in streaming negli agenti CLI
← Torna a AI Agents