AI Agents · Урок

Разбор аргументов и справочный текст

Обязательные и необязательные аргументы, проверка типов и автоматически создаваемая справка.

Урок 3 из 413 шагов

«Разбор аргументов и справочный текст» — бесплатный урок AI Agents на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.

Хороший дизайн CLI начинается с хороших аргументов

Хорошо спроектированный интерфейс аргументов агента CLI позволяет пользователям понять, как пользоваться инструментом, изучив только --help. У каждого аргумента должны быть понятные имя, тип, значение по умолчанию и описание.

Неудачные имена аргументов и отсутствие документации делают инструменты неудобными и усложняют их сопровождение.

Обязательные и необязательные аргументы

Обязательные аргументы необходимо указать — если их нет, CLI завершает работу с ошибкой. У необязательных аргументов есть значение default=, и их можно не указывать. Выбор между этими вариантами определяет удобство работы с инструментом.

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)

Проверка типов

Параметр type= автоматически преобразует строковый ввод и проверяет его. Используйте встроенные типы, например int, float и bool, или собственную функцию для более сложной проверки.

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=[...] ограничивает аргумент фиксированным набором разрешённых значений. argparse автоматически проверяет их и перечисляет варианты в тексте справки.

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'

Логические флаги с store_true

Логические флаги — это переключатели по наличию или отсутствию, которым не передаётся значение. Используйте action='store_true', чтобы при наличии флага устанавливать значение True, а при отсутствии — False.

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: управление отображением текста справки

По умолчанию argparse показывает в тексте справки имя аргумента в верхнем регистре: --query QUERY. Используйте metavar=, чтобы отображать более информативную замену, например QUESTION или 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')

Несколько значений с помощью nargs

Используйте nargs='+', чтобы принимать одно или несколько значений, или nargs='*' — для нуля или нескольких значений. Это удобно для передачи агенту списков URL, тегов или путей к файлам.

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

Подкоманды с помощью add_subparsers()

Подкоманды, например git commit и git push, позволяют каждой команде иметь собственный набор аргументов. Используйте add_subparsers(), чтобы определить их в 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'

Создание хорошего текста справки

Хороший текст справки отвечает на три вопроса: что делает этот аргумент, какие значения допустимы и каково значение по умолчанию? Пишите текст справки с точки зрения пользователя, а не разработчика.

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

Группы Argument для сложных CLI

Если CLI содержит много аргументов, сгруппируйте их по темам с помощью add_argument_group(). Так вывод --help станет гораздо понятнее.

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

Резервные значения из переменных окружения

Позвольте аргументам использовать переменные окружения, если они не указаны явно. Благодаря этому пользователи смогут задать значения по умолчанию в профиле оболочки и не вводить их каждый раз.

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

Проверка знаний: разбор аргументов

Проверьте, насколько хорошо Вы понимаете методы разбора аргументов CLI.

Ответь в интерактивном уроке

Итоги: разбор аргументов и текст справки

Теперь Вы знаете, как создавать полноценный и удобный интерфейс аргументов CLI:

Используйте required=True для обязательных аргументов и default= для необязательных
Проверяйте типы ввода с помощью type= и собственных функций-валидаторов
Ограничивайте значения с помощью choices=[...]
Используйте action='store_true' для логических флагов
Повышайте удобство чтения справки с помощью metavar= и понятных строк help=
Принимайте несколько значений с помощью nargs='+'
Используйте подкоманды и группы аргументов для сложных CLI
Используйте переменные окружения как резервный источник общих настроек

Можно начать бесплатно

Изучай AI Agents с ИИ-репетитором — бесплатно

Пиши и запускай код прямо в браузере, получай мгновенную помощь от ИИ-репетитора 24/7 и продолжи учиться на сайте или в приложении.

Курсы: 60
Уроки: 239

Начать учиться бесплатно Посмотреть полный курс

Часто задаваемые вопросы

Урок «Разбор аргументов и справочный текст» бесплатный?

Да — полный текст урока «Разбор аргументов и справочный текст» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.

Чему я научусь в уроке «Разбор аргументов и справочный текст»?

Обязательные и необязательные аргументы, проверка типов и автоматически создаваемая справка. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать AI Agents?

Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Разбор аргументов и справочный текст»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке AI Agents?

Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

Создание интерфейсов агентов командной строки
Интерактивные агенты в стиле REPL
Разбор аргументов и справочный текст
Потоковый вывод в агентах CLI

← Назад к AI Agents