Tekoälyagentit · Oppitunti

Komentoriviagentin käyttöliittymän rakentaminen

argparse, click ja Typer agentin CLI-argumenttien käsittelyyn

Oppitunti 1/413 vaihetta

Komentoriviagentin käyttöliittymän rakentaminen on ilmainen Tekoälyagentit-oppitunti CoddyKitissä. Tämä on oppitunti 1/4. Voit lukea koko oppitunnin alta ilmaiseksi ja harjoitella sen jälkeen käytännössä selaimessa sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla. Oppitunti kuuluu Tekoälyagentit-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Tekoälyagentit-kurssilla on yhteensä 4 oppituntia.

Miksi agentille kannattaa rakentaa CLI

Komentorivikäyttöliittymä (CLI) tekee agentista päätelaitteella käytettävän, putkissa skriptattavan ja helposti testattavan ilman verkkokäyttöliittymää. Monet tuotantoagentit otetaan käyttöön CLI-työkaluina.

Pythonissa on kolme erinomaista kirjastoa CLI-käyttöliittymien rakentamiseen: argparse (vakiokirjasto), Typer ja Click.

argparse: vakiokirjaston vaihtoehto

argparse sisältyy Pythoniin — erillistä asennusta ei tarvita. Määrittäkää käyttöliittymä ArgumentParser()-kutsulla, ilmoittakaa parametrit add_argument()-kutsulla ja käsitelkää ne parse_args()-kutsulla.

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

argparse-CLI:n suorittaminen ja automaattisesti luotu ohje

argparse luo argumenttimäärittelyistänne automaattisesti --help-ohjeviestin. Suorittakaa python agent_cli.py --help nähdäksenne sen. Puuttuvista pakollisista argumenteista näytetään automaattisesti hyödylliset virheilmoitukset.

# 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: moderni CLI tyyppivihjeillä

Typer rakentaa CLI:t Pythonin tyyppivihjeistä — koodia tarvitaan vähemmän kuin argparsea käytettäessä. Asentakaa se komennolla pip install typer. Funktioiden parametreista tulee automaattisesti CLI-argumentteja.

# 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: koristelijoihin perustuva CLI-kehys

Click käyttää koristelijoita CLI-komentojen ja -valitsimien määrittämiseen. Asentakaa se komennolla pip install click. Se tarjoaa monipuolisia ominaisuuksia, kuten komentoryhmiä, kehotteita ja edistymispalkkeja.

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

Alikomentojen lisääminen

Agentin kasvaessa toiminnallisuus kannattaa järjestää alikomennoiksi, kuten agent ask, agent search ja agent history. Sekä Click että Typer tukevat alikomentoryhmiä suoraan.

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

Lukeminen stdin:stä putkitetulle syötteelle

stdin:stä lukevaa CLI-agenttia voidaan käyttää Unix-putkissa. Käyttäkää putkitetun sisällön vastaanottamiseen sys.stdin-objektia tai Clickin stdin-argumenttityyppiä.

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

Pitkien tehtävien edistymisen näyttäminen

Agentin tehtävien suorittaminen voi kestää useita sekunteja. Näyttäkää latausanimaatio tai edistymisviesti, jotta käyttäjät tietävät agentin työskentelevän. Typerin sisäänrakennettu edistymisen tuki perustuu rich-kirjastoon.

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

Tulosteen muotoilu: JSON vai pelkkä teksti

Antakaa käyttäjien valita ihmiselle helposti luettava ja koneellisesti käsiteltävä tulostemuoto. --json-valitsin on hyödyllinen, kun agentin tuloste ohjataan putkella muihin työkaluihin.

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

Virheenkäsittely CLI-agenteissa

Poistukaa nollasta poikkeavalla koodilla virhetilanteissa, jotta kutsuvat skriptit voivat havaita epäonnistumiset. Kirjoittakaa virheilmoitukset standardivirtaan käyttämällä typer.echo(..., err=True)- tai click.echo(..., err=True)-kutsua.

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

Agentin muuttaminen asennettavaksi CLI-työkaluksi

Määrittäkää pyproject.toml-tiedostoon entry point, jotta agentti on käytettävissä järjestelmäkomentona. Komennon pip install -e . jälkeen käyttäjät voivat suorittaa komennon myagent ask 'question' suoraan mistä tahansa hakemistosta.

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

Tietojen tarkistus: CLI-agenttien käyttöliittymät

Testatkaa, kuinka hyvin ymmärrätte agenttien CLI-käyttöliittymien rakentamisen.

Vastaa interaktiivisessa oppitunnissa

Kertaus: CLI-agenttien käyttöliittymien rakentaminen

Osaatte nyt rakentaa agenteillenne ammattimaisia CLI-käyttöliittymiä:

Käyttäkää argparse-kirjastoa riippuvuudettomiin CLI-sovelluksiin (standardikirjasto)
Käyttäkää typer-kirjastoa selkeisiin tyyppivihjeisiin perustuviin CLI-sovelluksiin
Käyttäkää click-kirjastoa monipuolisiin koristelijoihin perustuviin CLI-sovelluksiin
Järjestäkää suuret agentit alikomennoilla
Tukekaa stdin-syötettä putki-integraatiota varten
Käyttäkää --json-valitsimia koneellisesti käsiteltävään tulosteeseen
Poistukaa virhetilanteissa nollasta poikkeavilla koodeilla, jotta shell-skriptit toimivat oikein

Aloita maksutta

Opi Tekoälyagentit tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 60
Oppitunnit: 239

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”Komentoriviagentin käyttöliittymän rakentaminen” ilmainen?

Kyllä – oppitunnin ”Komentoriviagentin käyttöliittymän rakentaminen” koko tekstin voi lukea täällä verkossa ilmaiseksi. Jos haluat harjoitella interaktiivisesti sisäänrakennetulla koodieditorilla ja ympäri vuorokauden käytettävissä olevan tekoälytuutorin avulla sekä avata koko Tekoälyagentit-kurssin, päivitä CoddyKit PROhon. Tekoälyagentit-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Komentoriviagentin käyttöliittymän rakentaminen”?

argparse, click ja Typer agentin CLI-argumenttien käsittelyyn Harjoittelet Tekoälyagentit-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Tekoälyagentit-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Tekoälyagentit-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 1/4.

Kuinka kauan ”Komentoriviagentin käyttöliittymän rakentaminen”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Tekoälyagentit-oppitunnilla?

Kyllä. Jokainen Tekoälyagentit-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

Komentoriviagentin käyttöliittymän rakentaminen
Interaktiiviset REPL-tyyliset agentit
Argumenttien jäsentäminen ja ohjeteksti
Tulosteen suoratoisto CLI-agenteissa

← Takaisin: Tekoälyagentit