0Pricing
AI Agents · Lekcja

Parsowanie argumentów i tekst pomocy

Argumenty wymagane i opcjonalne, walidacja typów oraz automatycznie generowana pomoc.

Parsowanie argumentów i tekst pomocy to bezpłatna lekcja AI Agents na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Agents, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Agents zawiera 4 lekcji w sumie.

Dobry projekt CLI zaczyna się od dobrych argumentów

Dobrze zaprojektowany interfejs argumentów agenta CLI pozwala użytkownikom zrozumieć sposób korzystania z narzędzia wyłącznie na podstawie --help. Każdy argument powinien mieć jasną nazwę, typ, wartość domyślną i opis.

Niejasno nazwane lub nieudokumentowane argumenty sprawiają, że korzystanie z narzędzi jest frustrujące, a ich utrzymanie — trudne.

Argumenty wymagane a opcjonalne

Argumenty wymagane muszą zostać podane — jeśli ich brakuje, CLI kończy działanie z błędem. Argumenty opcjonalne mają wartość default= i można je pominąć. Decyzja, które argumenty należą do poszczególnych kategorii, wpływa na wygodę korzystania z narzędzia.

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)

Walidacja typów

Parametr type= automatycznie konwertuje dane wejściowe w postaci tekstu i je waliduje. Należy używać wbudowanych typów, takich jak int, float i bool, lub własnej funkcji do bardziej złożonej walidacji.

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: ograniczanie do prawidłowych wartości

Parametr choices=[...] ogranicza argument do ustalonego zestawu dozwolonych wartości. argparse automatycznie je waliduje i wyświetla dostępne opcje w tekście pomocy.

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'

Flagi logiczne z użyciem store_true

Flagi logiczne działają na zasadzie obecności lub braku — nie podaje się dla nich wartości. Należy użyć action='store_true', aby ustawić flagę na True, gdy jest obecna, i na False, gdy jej nie ma.

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: sterowanie wyświetlaniem tekstu pomocy

Domyślnie argparse wyświetla nazwę argumentu wielkimi literami w tekście pomocy: --query QUERY. Użyj metavar=, aby wyświetlić bardziej informujący symbol zastępczy, taki jak QUESTION lub 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')

Wiele wartości z użyciem nargs

Użyj nargs='+', aby przyjmować co najmniej jedną wartość, lub nargs='*', aby przyjmować zero lub więcej wartości. Jest to przydatne podczas przekazywania agentowi list adresów URL, tagów lub ścieżek plików.

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

Podkomendy z użyciem add_subparsers()

Podkomendy, takie jak git commit i git push, dają każdemu poleceniu własny zestaw argumentów. Użyj add_subparsers(), aby zdefiniować je w 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'

Pisanie dobrego tekstu pomocy

Dobry tekst pomocy odpowiada na trzy pytania: do czego służy ten argument, jakie wartości są prawidłowe i jaka jest wartość domyślna? Tekst pomocy należy pisać z perspektywy użytkownika, a nie osoby implementującej rozwiązanie.

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

Grupy argumentów dla złożonych interfejsów CLI

Gdy CLI ma wiele argumentów, należy pogrupować je tematycznie za pomocą add_argument_group(). Dzięki temu dane wyjściowe --help są znacznie łatwiejsze do odczytania.

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

Wartości zapasowe ze zmiennych środowiskowych

Należy umożliwić użycie zmiennych środowiskowych jako wartości zapasowych argumentów, gdy nie zostaną one podane. Dzięki temu użytkownicy mogą ustawić wartości domyślne w profilu powłoki bez konieczności wpisywania ich za każdym razem.

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

Sprawdzenie wiedzy: parsowanie argumentów

Sprawdź swoją wiedzę na temat technik parsowania argumentów CLI.

Podsumowanie: parsowanie argumentów i tekst pomocy

Wiesz już, jak zbudować kompletny i przyjazny dla użytkownika interfejs argumentów CLI:

  • Używaj required=True dla argumentów wymaganych, a default= dla opcjonalnych
  • Waliduj typy danych wejściowych za pomocą type= i własnych funkcji walidujących
  • Ograniczaj wartości za pomocą choices=[...]
  • Używaj action='store_true' dla flag logicznych
  • Poprawiaj czytelność pomocy za pomocą metavar= i jasnych ciągów help=
  • Przyjmuj wiele wartości za pomocą nargs='+'
  • Używaj podkomend i grup argumentów w przypadku złożonych interfejsów CLI
  • Używaj zmiennych środowiskowych jako wartości zapasowych dla często używanych ustawień

Często zadawane pytania

Czy lekcja „Parsowanie argumentów i tekst pomocy” jest bezpłatna?

Tak — pełny tekst „Parsowanie argumentów i tekst pomocy” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Agents, przejdź na CoddyKit PRO. Kurs AI Agents zawiera 4 lekcji w sumie.

Co nauczysz się w „Parsowanie argumentów i tekst pomocy”?

Argumenty wymagane i opcjonalne, walidacja typów oraz automatycznie generowana pomoc. Ćwiczysz AI Agents z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć AI Agents?

Nie wymagamy żadnego doświadczenia. AI Agents w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Parsowanie argumentów i tekst pomocy”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji AI Agents?

Tak. Każda lekcja AI Agents zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

  1. Tworzenie interfejsów agentów wiersza poleceń
  2. Agenci interaktywni w stylu REPL
  3. Parsowanie argumentów i tekst pomocy
  4. Strumieniowanie wyników w agentach CLI
← Powrót do AI Agents