Создание интерфейсов агентов командной строки
argparse, click и Typer для обработки аргументов CLI-агентов.
«Создание интерфейсов агентов командной строки» — бесплатный урок AI Agents на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения AI Agents, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс AI Agents содержит 4 уроков всего.
Зачем создавать CLI для агента
Интерфейс командной строки (CLI) делает агента доступным из терминала, позволяет использовать его в сценариях и конвейерах, а также упрощает тестирование без веб-интерфейса. Многие рабочие агенты развёртываются как инструменты CLI.
В Python есть три отличные библиотеки для создания CLI: argparse (стандартная библиотека), Typer и Click.
argparse: вариант со стандартной библиотекой
argparse встроен в Python — установка не требуется. Используйте ArgumentParser(), чтобы определить интерфейс, add_argument(), чтобы объявить параметры, и parse_args(), чтобы обработать их.
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?'])Запуск CLI на argparse и автоматически создаваемая справка
argparse автоматически создаёт сообщение --help на основе определений аргументов. Выполните python agent_cli.py --help, чтобы просмотреть его. При отсутствии обязательных аргументов автоматически выводятся полезные сообщения об ошибках.
# 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 с аннотациями типов
Typer создаёт приложения CLI на основе аннотаций типов Python — шаблонного кода меньше, чем при использовании argparse. Установите с помощью pip install typer. Параметры функций автоматически становятся аргументами 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: фреймворк CLI на основе декораторов
Click использует декораторы для определения команд и параметров CLI. Установите с помощью pip install click. Библиотека предоставляет такие возможности, как группы команд, приглашения и индикаторы выполнения.
# 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()Добавление подкоманд
По мере развития агента организуйте его функции в подкоманды, например agent ask, agent search и agent history. И Click, и Typer изначально поддерживают группы подкоманд.
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Чтение из стандартного ввода через конвейер
Агент CLI, который читает данные из стандартного ввода, можно использовать в конвейерах Unix. Используйте sys.stdin или тип аргумента stdin в Click, чтобы принимать данные, переданные через конвейер.
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()Индикаторы выполнения длительных задач
Задачи агента могут выполняться несколько секунд. Показывайте анимацию или сообщение о ходе выполнения, чтобы пользователи знали, что агент работает. В Typer есть встроенная поддержка отображения хода выполнения через библиотеку 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()Форматирование вывода: JSON и обычный текст
Позвольте пользователям выбирать между форматами вывода, удобными для чтения человеком и машинной обработки. Флаг --json пригодится для передачи вывода агента через конвейер другим инструментам.
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()Обработка ошибок в агентах CLI
При ошибках завершайте работу с ненулевым кодом, чтобы вызывающие скрипты могли обнаружить сбой. Используйте typer.echo(..., err=True) или click.echo(..., err=True), чтобы записывать сообщения об ошибках в 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()Превращение агента в устанавливаемый инструмент CLI
Используйте точку входа в pyproject.toml, чтобы агент был доступен как системная команда. После выполнения pip install -e . пользователи смогут запускать myagent ask 'question' напрямую из любого каталога.
# 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')Проверка знаний: интерфейсы агентов CLI
Проверьте, насколько хорошо Вы понимаете создание интерфейсов CLI для агентов.
Итоги: создание интерфейсов агентов CLI
Теперь Вы умеете создавать профессиональные интерфейсы CLI для своих агентов:
- Используйте
argparseдля CLI без внешних зависимостей (стандартная библиотека) - Используйте
typerдля лаконичных CLI на основе аннотаций типов - Используйте
clickдля многофункциональных CLI на основе декораторов - Организуйте большие агенты с помощью подкоманд
- Поддерживайте стандартный ввод для интеграции с конвейерами
- Используйте флаги
--jsonдля машиночитаемого вывода - Завершайте работу с ненулевыми кодами при ошибках для совместимости со скриптами оболочки
Часто задаваемые вопросы
Урок «Создание интерфейсов агентов командной строки» бесплатный?
Да — полный текст урока «Создание интерфейсов агентов командной строки» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс AI Agents, подпишись на CoddyKit PRO. Курс AI Agents содержит 4 уроков всего.
Чему я научусь в уроке «Создание интерфейсов агентов командной строки»?
argparse, click и Typer для обработки аргументов CLI-агентов. Ты практикуешь AI Agents с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.
Нужен ли мне опыт, чтобы начать AI Agents?
Предыдущий опыт не требуется. AI Agents на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.
Сколько времени занимает урок «Создание интерфейсов агентов командной строки»?
Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.
Можно ли писать и запускать код в этом уроке AI Agents?
Да. Каждый урок AI Agents включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.
Все уроки этого курса
- Создание интерфейсов агентов командной строки
- Интерактивные агенты в стиле REPL
- Разбор аргументов и справочный текст
- Потоковый вывод в агентах CLI