Начало работы с Claude Agent SDK

Введение

Надоело соединять скрипты, инструменты и запросы к моделям на живую нитку? Claude Agent SDK позволяет превратить рабочий процесс Claude Code в формате «планирование → создание → запуск» в полноценных программируемых агентов. С его помощью можно автоматизировать задачи, подключать инструменты и разрабатывать приложения с командной строкой без кучи вспомогательного кода. Если вы привыкли работать с Claude в терминале, этот набор инструментов развития предлагает тот же подход, но с четкой структурой, управлением состоянием и возможностями расширения.

В этом руководстве вы настроите Claude Agent SDK и создадите простое приложение для командной строки с несколькими инструментами, которое последовательно выполняет шаги: планирование → действие → проверка. По ходу дела вы узнаете, как регистрировать инструменты, управлять контекстом и организовывать циклы агентов для локальных задач, таких как отладка, генерация кода и развертывание.

Что такое Claude Agent SDK?

Claude Sonnet 4.5 от Anthropic представляет собой важный шаг вперед в возможностях модели, с передовой системой для кодирования, которая лидирует в отраслевых тестах по рассуждениям, математике и обработке длинного контекста. В обновлении появились расширение для Chrome, инструмент памяти и функции генерации документов. Ключевой элемент — Claude Agent SDK, который основан на Claude Code.

Claude Agent SDK помогает разработчикам создавать, расширять и настраивать приложения на базе Claude. Он интегрируется с локальной средой, дает модели доступ к вашим инструментам и позволяет координировать сложные процессы, включая программирование, исследования, ведение заметок и автоматизацию.

Настройка Claude Agent SDK

Перед началом разработки убедитесь, что установлены Claude Code CLI и Claude Agent SDK.

1. Требования

• Python: версия 3.10 или новее.
• Node.js: версия 18 или выше для CLI.
• Ключ API Claude или учетная запись Anthropic.

2. Установка Claude Code CLI

Для установки Claude Code CLI на Windows выполните следующую команду в PowerShell:

irm https://claude.ai/install.ps1 | iex

Затем добавьте этот путь в системные переменные среды:

C:\Users\<user>\.local\bin

Перезапустите PowerShell и проверьте:

claude --version

Для других платформ используйте менеджер пакетов npm:

npm i -g @anthropic-ai/claude-code

После установки введите claude в терминале, чтобы войти в систему.

3. Установка Claude Agent SDK (Python)

Установите Python SDK для Claude Agent с помощью pip.

pip install claude-agent-sdk

Если возникает ошибка CLINotFoundError, проверьте, что Claude CLI установлен правильно и добавлен в PATH.

Создание приложения с несколькими инструментами на базе Claude Agent SDK

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

Приложение объединяет Claude Sonnet 4.5, инструменты WebSearch, WebFetch и локальное хранение в единую систему с несколькими агентами.

Создайте файл Python trend_smith.py и добавьте в него следующий код:

1. Импорты и базовые настройки

Здесь загружаются библиотеки Python, типы из Claude Agent SDK, небольшое меню помощи, название модели и стиль текста серого цвета для строк статуса.

import asyncio import os import re import sys import time from datetime import datetime from pathlib import Path from claude_agent_sdk import ( AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient, ResultMessage, TextBlock, ToolResultBlock, ToolUseBlock, ) HELP = """Commands: /trend <topic> Quick multi-source scan (auto-saves markdown) /scan <query> Short one-page scan /help /exit Help / Quit """ MODEL = os.getenv("CLAUDE_MODEL", "sonnet") # e.g. "sonnet-4.5" GRAY = "\033[90m" RESET = "\033[0m"

2. Системный промт и место для отчетов

Это задает правила для ответов (быстрые, краткие, с последовательными разделами) и выбирает папку reports/ рядом со скриптом для сохранения кратких обзоров.

SYS = """You are TrendSmith, a fast, concise trend researcher. - Finish quickly (~20 s). - For /trend: ≤1 WebSearch + ≤2 WebFetch from distinct domains. - For /scan: ≤1 WebFetch only. Return for /trend: TL;DR (1 line) 3-5 Signals (short bullets) Key Players, Risks, 30/90-day Watchlist Sources (markdown: **Title** -- URL) Return for /scan: 5 bullets + TL;DR + Sources. After finishing /trend, the client will auto-save your full brief. """ BASE = Path(__file__).parent REPORTS = BASE / "reports"

3. Безопасное сохранение файлов

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

def _ts(): return datetime.now().strftime("%Y%m%d_%H%M") def _sanitize(s: str): return re.sub(r"[^\\w\-.]+", "_", s).strip("_") or "untitled" def _ensure_dir(p: Path): try: p.mkdir(parents=True, exist_ok=True) except Exception: pass def _safe_write(path: Path, text: str) -> Path: """Write text to path; if directory/permission fails, fall back to ~/TrendSmith/reports.""" try: _ensure_dir(path.parent) path.write_text(text, encoding="utf-8") return path except Exception: home_reports = Path.home() / "TrendSmith" / "reports" _ensure_dir(home_reports) fb = home_reports / path.name fb.write_text(text, encoding="utf-8") return fb def save_report(topic: str, text: str) -> Path: filename = f"{_sanitize(topic)}_{_ts()}.md" target = REPORTS / filename return _safe_write(target, text.strip() + "\n")

4. Отслеживание каждого запуска

Это хранит данные для одного запроса: потоковый текст, модель, количество инструментов, использование токенов, затраты и время, а затем сбрасывает все перед следующим запросом.

class State: def __init__(self): self.brief = "" self.model_raw = None self.usage = {} self.cost = None self.last_cmd = None self.last_topic = None self.tools = {} self.t0 = 0.0 self.t1 = 0.0 def reset(self): self.brief = "" self.model_raw = None self.usage = {} self.cost = None self.tools = {} self.t0 = time.perf_counter() self.t1 = 0.0 def friendly_model(name: str | None) -> str: if not name: return MODEL n = (name or "").lower() if "sonnet-4-5" in n or "sonnet_4_5" in n: return "Claude 4.5 Sonnet" if "sonnet" in n: return "Claude Sonnet" if "haiku" in n: return "Claude Haiku" if "opus" in n: return "Claude Opus" return name or "Unknown"

5. Краткий обзор запуска

Это выводит аккуратный серый блок с информацией о модели, токенах, использовании инструментов и продолжительности, не смешивая с потоком контента.

def usage_footer(st: State, opts_model: str): st.t1 = st.t1 or time.perf_counter() dur = st.t1 - st.t0 usage = st.usage or {} it = usage.get("input_tokens") ot = usage.get("output_tokens") total = usage.get("total_tokens") if total is None and (it is not None or ot is not None): total = (it or 0) + (ot or 0) tools_used = ", ".join(f"{k}×{v}" for k, v in st.tools.items()) or "--" model_label = friendly_model(st.model_raw or opts_model) box = [ "┌─ Run Summary ─────────────────────────────────────────────", f"│ Model: {model_label}", f"│ Tokens: {total if total is not None else ''?''" + (f" (in={it if it is not None else ''?''} | out={ot if ot is not None else ''?''}" if (it is not None or ot is not None) else ""), f"│ Tools: {tools_used}", f"│ Duration: {dur:.1f}s", "└───────────────────────────────────────────────────────────", ] print(GRAY + "\n".join(box) + RESET, file=sys.stderr)

6. Основной цикл (все в одном)

Это запускает приложение, читает команду, запрашивает у ИИ ответ, транслирует его в поток, сохраняет отчеты для /trend и выводит обзор.

async def main(): """Setup → REPL → parse → query/stream → auto-save → summary.""" st = State() _ensure_dir(REPORTS) opts = ClaudeAgentOptions( model=MODEL, system_prompt=SYS, allowed_tools=["WebFetch", "WebSearch"], ) print("📈 TrendSmith \n\n" + HELP) async with ClaudeSDKClient(options=opts) as client: while True: # Read input try: user = input("\nYou: ").strip() except (EOFError, KeyboardInterrupt): print("\nBye!") break if not user: continue low = user.lower() # Basic commands if low in {"/exit", "exit", "quit"}: print("Bye!") break if low in {"/help", "help"}: print(HELP) continue # Parse into a prompt if low.startswith("/trend "): topic = user.split(" ", 1)[1].strip().strip('"') if not topic: print(''e.g. /trend "AI chip startups"'') continue st.last_cmd, st.last_topic = "trend", topic prompt = f"Run a fast trend scan for '{topic}' following the output spec." elif low.startswith("/scan "): q = user.split(" ", 1)[1].strip() if not q: print(''e.g. /scan "AI hardware news"'') continue st.last_cmd, st.last_topic = "scan", q prompt = f"Quick scan for '{q}' in under 10s (≤1 WebFetch). Return 5 bullets + TL;DR + sources." else: st.last_cmd, st.last_topic = "free", None prompt = user # Execute request and stream results st.reset() print(f"{GRAY}▶ Working...{RESET}") try: await client.query(prompt) except Exception as e: print(f"{GRAY}❌ Query error: {e}{RESET}") continue try: async for m in client.receive_response(): if isinstance(m, AssistantMessage): st.model_raw = st.model_raw or m.model for b in m.content: if isinstance(b, TextBlock): st.brief += b.text or "" print(b.text or "", end="") elif isinstance(b, ToolUseBlock): name = b.name or "Tool" st.tools[name] = st.tools.get(name, 0) + 1 print(f"{GRAY}\n🛠 Tool: {name}{RESET}") elif isinstance(b, ToolResultBlock): pass # quiet tool payloads elif isinstance(m, ResultMessage): st.usage = m.usage or {} st.cost = m.total_cost_usd except Exception as e: print(f"{GRAY}\n⚠ Stream error: {e}{RESET}") # Auto-save trend briefs and show the summary if st.last_cmd == "trend" and st.brief.strip(): try: saved_path = save_report(st.last_topic or "trend", st.brief) print(f"\n{GRAY}✅ Auto-saved → {saved_path}{RESET}") except Exception as e: print(f"{GRAY}⚠ Save error: {e}{RESET}") st.t1 = time.perf_counter() usage_footer(st, opts.model) if __name__ == "__main__": asyncio.run(main())

Тестирование приложения TrendSmith

Теперь запустите файл Python, чтобы протестировать приложение. Вот краткий обзор использования CLI:

• /trend "<topic>" → краткий обзор из нескольких источников, автоматически сохраняется в reports/<topic>_<ts>.md.
• /scan "<query>" → быстрый обзор на одной странице (≤1 WebFetch), только вывод.
• /help → показывает команды.
• /exit → выход.

python .\trend_smith.py

В примере использована опция /trend для поиска стартапов в области чипов для ИИ.

/trend "AI chip startups"

В результате приложение применило разные инструменты поиска и веб-скрапинга, чтобы собрать данные с различных сайтов.

В итоге оно выдало полный ответ, автоматически сохранило отчет в файле markdown и сгенерировало обзор использования. Стоимость составила 0,136 доллара.

Вот предварительный просмотр сохраненного отчета в формате Markdown по теме стартапов в области чипов для ИИ.

Теперь протестируйте опцию сканирования и сгенерируйте обзор темы с помощью веб-поиска.

/scan Code CLI tools

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

Заключение

Приложение работает стабильно, и использование Claude Agent SDK оказалось приятным процессом. Если вы уже применяете Claude Code, стоит попробовать этот SDK, чтобы превратить повседневные задачи в терминале в надежные и повторяемые CLI с элементами агентов.

Применяйте его для:

• Автоматизации типичных задач разработки (отладка, тестирование, развертывание).
• Скриптинга простых аналитик или рутинных операций.
• Упаковки процессов в переиспользуемые и распространяемые инструменты.

SDK подходит специалистам, которым нужна стабильность, воспроизводимость и минимум вспомогательного кода. Кроме того, Claude Code может помочь в создании самого агентного приложения с использованием SDK.