Anthropic Agents SDK под капотом
Цели урока
После прохождения этого урока вы сможете:
- 1Понять, как NanoClaw использует Anthropic Agents SDK
- 2Изучить механизм определения инструментов (tool definitions)
- 3Разобраться в потоковой передаче сообщений (streaming)
- 4Научиться расширять NanoClaw собственными инструментами
Anthropic Agents SDK — основа NanoClaw
NanoClaw построен на Anthropic Agents SDK — официальном фреймворке для создания AI-агентов на базе Claude. SDK берёт на себя всю сложность взаимодействия с API: управление разговором, tool use, streaming, обработку ошибок. NanoClaw добавляет к этому контейнерную изоляцию и WhatsApp-интерфейс.
Архитектура NanoClaw (500 строк)
Вся кодовая база NanoClaw состоит из нескольких логических блоков. Рассмотрим, как ~500 строк TypeScript организованы:
| Блок | Строк (примерно) | Назначение |
|---|---|---|
| Agent Runtime | ~120 | Запуск агента в контейнере, управление жизненным циклом |
| Tool Definitions | ~100 | Определения инструментов (file, web, system) |
| WhatsApp Bridge | ~80 | Приём и отправка сообщений WhatsApp |
| Container Manager | ~80 | Создание/уничтожение контейнеров (Docker/Apple) |
| Swarm Orchestrator | ~70 | Координация агентов в swarm |
| Config & Types | ~50 | Типы TypeScript и загрузка конфигурации |
Как определяются инструменты
Anthropic Agents SDK использует typed tool definitions — типизированные определения инструментов, которые Claude может вызывать. NanoClaw определяет каждый инструмент с именем, описанием и JSON Schema параметров.
import { Tool } from '@anthropic-ai/agents';
const listFilesTool: Tool = {
name: 'list_files',
description: 'Показать список файлов в указанной директории',
input_schema: {
type: 'object',
properties: {
path: {
type: 'string',
description: 'Путь к директории (внутри контейнера)'
},
recursive: {
type: 'boolean',
description: 'Рекурсивный обход поддиректорий',
default: false
}
},
required: ['path']
},
async execute({ path, recursive }) {
// Выполняется ВНУТРИ контейнера
const files = await listDirectory(path, recursive);
return JSON.stringify(files);
}
};Streaming: потоковая передача ответов
NanoClaw использует streaming API для отправки ответов по мере их генерации. Это критически важно для WhatsApp: пользователь видит, что агент «печатает», а не ждёт полного ответа.
import { Agent } from '@anthropic-ai/agents';
const agent = new Agent({
model: 'claude-sonnet-4-5-20250514',
tools: [listFilesTool, readFileTool, writeFileTool],
system: config.system_prompt
});
// Потоковая обработка ответа
for await (const chunk of agent.stream(userMessage)) {
if (chunk.type === 'text') {
await whatsapp.sendTyping(chatId);
buffer += chunk.content;
}
if (chunk.type === 'tool_use') {
const result = await executeTool(chunk.tool, chunk.input);
agent.submitToolResult(chunk.id, result);
}
}Добавление собственных инструментов
Благодаря простоте кодовой базы, добавить новый инструмент в NanoClaw — тривиальная задача. Нужно определить Tool-объект и добавить его в массив инструментов агента.
// Пример: добавление инструмента "калькулятор"
const calculatorTool: Tool = {
name: 'calculator',
description: 'Вычислить математическое выражение',
input_schema: {
type: 'object',
properties: {
expression: {
type: 'string',
description: 'Математическое выражение (например: 2 + 2 * 3)'
}
},
required: ['expression']
},
async execute({ expression }) {
// Безопасное вычисление (без eval!)
const result = safeEvaluate(expression);
return String(result);
}
};При создании собственных инструментов никогда не используйте eval() или Function() для выполнения пользовательского ввода. Это создаёт уязвимость для code injection. Используйте безопасные парсеры и валидаторы.
Весь код NanoClaw — 500 строк. Вы можете прочитать его целиком за 8 минут, понять каждую строку и модифицировать с полной уверенностью в последствиях. Это принципиальное отличие от фреймворков с десятками тысяч строк.
Вопросы для размышления
- •Какие собственные инструменты вы бы добавили в NanoClaw?
- •Почему важно, чтобы инструменты выполнялись внутри контейнера, а не на хост-системе?
- •Как streaming улучшает пользовательский опыт в WhatsApp?
