0Pricing
AI Agents · Lección

Creación de interfaces de agentes de línea de comandos

argparse, click y Typer para gestionar los argumentos CLI de los agentes.

Creación de interfaces de agentes de línea de comandos es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.

¿Por qué crear una CLI para su agente?

Una interfaz de línea de comandos (CLI) permite acceder a su agente desde un terminal, usarlo en scripts dentro de flujos automatizados y probarlo fácilmente sin una interfaz web. Muchos agentes de producción se implementan como herramientas CLI.

Python cuenta con tres excelentes bibliotecas para crear CLI: argparse (biblioteca estándar), Typer y Click.

argparse: la opción de la biblioteca estándar

argparse está integrado en Python, por lo que no requiere instalación. Use ArgumentParser() para definir su interfaz, add_argument() para declarar los parámetros y parse_args() para procesarlos.

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

Ejecución de una CLI con argparse y ayuda generada automáticamente

argparse genera automáticamente un mensaje de ayuda --help a partir de las definiciones de sus argumentos. Ejecute python agent_cli.py --help para verlo. Los argumentos obligatorios que falten generan automáticamente mensajes de error útiles.

# 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 anotaciones de tipo

Typer crea interfaces de línea de comandos (CLI) a partir de las anotaciones de tipo de Python, con menos código repetitivo que argparse. Instálelo con pip install typer. Los parámetros de las funciones se convierten automáticamente en argumentos de la 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 de CLI basado en decoradores

Click utiliza decoradores para definir comandos y opciones de la CLI. Instálelo con pip install click. Ofrece funciones avanzadas, como grupos de comandos, mensajes interactivos y barras de progreso.

# 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()

Cómo añadir subcomandos

A medida que su agente crece, organice la funcionalidad en subcomandos como agent ask, agent search y agent history. Tanto Click como Typer admiten grupos de subcomandos de forma nativa.

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

Lectura de stdin para entradas canalizadas

Un agente de CLI que lee de stdin puede utilizarse en canalizaciones de Unix. Use sys.stdin o el tipo de argumento stdin de Click para aceptar contenido canalizado.

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

Indicadores de progreso para tareas largas

Las tareas del agente pueden tardar varios segundos. Muestre un indicador giratorio o un mensaje de progreso para que los usuarios sepan que el agente está trabajando. Typer ofrece compatibilidad integrada con el progreso mediante la biblioteca 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()

Formato de salida: JSON frente a texto sin formato

Permita que los usuarios elijan entre formatos de salida legibles para personas y para máquinas. Un indicador --json resulta útil para canalizar la salida del agente hacia otras herramientas.

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

Gestión de errores en agentes de CLI

Termine con un código distinto de cero cuando se produzcan errores para que los scripts que realizan la llamada puedan detectar los fallos. Use typer.echo(..., err=True) o click.echo(..., err=True) para escribir los mensajes de error en 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()

Cómo convertir su agente en una herramienta de CLI instalable

Use un punto de entrada de pyproject.toml para que su agente esté disponible como comando del sistema. Después de ejecutar pip install -e ., los usuarios podrán ejecutar myagent ask 'question' directamente desde cualquier directorio.

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

Comprobación de conocimientos: interfaces de agentes de CLI

Compruebe sus conocimientos sobre la creación de interfaces de CLI para agentes.

Recapitulación: creación de interfaces de agentes de CLI

Ahora puede crear interfaces de CLI profesionales para sus agentes:

  • Use argparse para CLI sin dependencias (biblioteca estándar)
  • Use typer para CLI limpias basadas en anotaciones de tipo
  • Use click para CLI completas basadas en decoradores
  • Organice los agentes grandes con subcomandos
  • Admita stdin para integrarse con canalizaciones
  • Use indicadores --json para obtener una salida legible por máquinas
  • Termine con códigos distintos de cero cuando se produzcan errores, para mantener la compatibilidad con scripts de shell

Preguntas frecuentes

¿La lección «Creación de interfaces de agentes de línea de comandos» es gratis?

Sí — el texto completo de «Creación de interfaces de agentes de línea de comandos» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.

¿Qué aprenderé en «Creación de interfaces de agentes de línea de comandos»?

argparse, click y Typer para gestionar los argumentos CLI de los agentes. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Agents?

No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Creación de interfaces de agentes de línea de comandos»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Agents?

Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Creación de interfaces de agentes de línea de comandos
  2. Agentes interactivos al estilo REPL
  3. Análisis de argumentos y texto de ayuda
  4. Salida en streaming en agentes CLI
← Volver a AI Agents