AI Agents · レッスン

引数解析とヘルプテキスト

Q: 「引数解析とヘルプテキスト」で何を学びますか？

必須引数とオプション引数、型検証、自動生成されるヘルプを学びます。 ブラウザで直接実行するハンズオンコードでAI Agentsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

必須引数とオプション引数、型検証、自動生成されるヘルプを学びます。

「引数解析とヘルプテキスト」はCoddyKit上の無料AI Agentsレッスンです。これはレッスン3/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはAI Agents学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Agentsコースには全4レッスンが含まれています。

優れたCLI設計は優れた引数から始まる

適切に設計されたCLIエージェントの引数インターフェースなら、ユーザーは--helpだけを見てツールの使い方を理解できます。すべての引数に、明確な名前、型、デフォルト値、説明を設定します。

名前がわかりにくかったり、説明がなかったりする引数は、ツールを使いにくくし、保守も難しくします。

必須引数とオプション引数

必須引数は指定しなければならず、欠落している場合CLIはエラーで終了します。オプション引数にはdefault=の値があり、省略できます。どの引数を必須にするかという判断が、ツールのUXを形作ります。

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：有効な値を制限する

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='+'を使うと1つ以上の値を、nargs='*'を使うと0個以上の値を受け取れます。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のようなサブコマンドを使うと、各コマンドに独自の引数セットを持たせられます。argparseではadd_subparsers()を使って定義します。

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'

適切なヘルプテキストを書く

優れたヘルプテキストは、次の3つの疑問に答えます。この引数は何をするのか、有効な値は何か、デフォルト値は何か。実装者ではなくユーザーの視点でヘルプテキストを書きます。

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

複雑な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にはサブコマンドと引数グループを使用します
よく使う設定には環境変数へフォールバックします

よくある質問

「引数解析とヘルプテキスト」レッスンは無料ですか？

はい。「引数解析とヘルプテキスト」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、AI Agentsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Agentsコースには全4レッスンが含まれています。

「引数解析とヘルプテキスト」で何を学びますか？

必須引数とオプション引数、型検証、自動生成されるヘルプを学びます。ブラウザで直接実行するハンズオンコードでAI Agentsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

AI Agentsを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのAI Agentsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン3/4です。

「引数解析とヘルプテキスト」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このAI Agentsレッスンでコードを書いて実行できますか？

はい。すべてのAI Agentsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← AI Agentsに戻る