Руководства

Потоковый ввод

Понимание двух режимов ввода для Claude Agent SDK и когда использовать каждый

Обзор

Claude Agent SDK поддерживает два различных режима ввода для взаимодействия с агентами:

Режим потокового ввода (По умолчанию и рекомендуется) - Постоянная интерактивная сессия
Ввод одного сообщения - Одноразовые запросы, которые используют состояние сессии и возобновление

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

Режим потокового ввода (Рекомендуется)

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

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

Как это работает

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
    participant App as Your Application
    participant Agent as Claude Agent
    participant Tools as Tools/Hooks
    participant FS as Environment/<br/>File System
    
    App->>Agent: Initialize with AsyncGenerator
    activate Agent
    
    App->>Agent: Yield Message 1
    Agent->>Tools: Execute tools
    Tools->>FS: Read files
    FS-->>Tools: File contents
    Tools->>FS: Write/Edit files
    FS-->>Tools: Success/Error
    Agent-->>App: Stream partial response
    Agent-->>App: Stream more content...
    Agent->>App: Complete Message 1
    
    App->>Agent: Yield Message 2 + Image
    Agent->>Tools: Process image & execute
    Tools->>FS: Access filesystem
    FS-->>Tools: Operation results
    Agent-->>App: Stream response 2
    
    App->>Agent: Queue Message 3
    App->>Agent: Interrupt/Cancel
    Agent->>App: Handle interruption
    
    Note over App,Agent: Session stays alive
    Note over Tools,FS: Persistent file system<br/>state maintained
    
    deactivate Agent

Преимущества

Загрузка изображений

Прикрепляйте изображения напрямую к сообщениям для визуального анализа и понимания

Сообщения в очереди

Отправляйте несколько сообщений, которые обрабатываются последовательно, с возможностью прерывания

Интеграция инструментов

Полный доступ ко всем инструментам и пользовательским MCP серверам во время сессии

Поддержка хуков

Используйте хуки жизненного цикла для настройки поведения в различных точках

Обратная связь в реальном времени

Видите ответы по мере их генерации, а не только финальные результаты

Постоянство контекста

Поддерживайте контекст разговора через несколько оборотов естественным образом

Пример реализации

import { query } from "@anthropic-ai/claude-agent-sdk";
import { readFileSync } from "fs";

async function* generateMessages() {
  // Первое сообщение
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Проанализируй эту кодовую базу на предмет проблем безопасности"
    }
  };
  
  // Ждем условий или пользовательского ввода
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Продолжение с изображением
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Просмотри эту диаграмму архитектуры"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// Обработка потоковых ответов
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 10,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Ввод одного сообщения

Ввод одного сообщения проще, но более ограничен.

Когда использовать ввод одного сообщения

Используйте ввод одного сообщения когда:

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

Ограничения

Режим ввода одного сообщения не поддерживает:

Прямые вложения изображений в сообщениях
Динамическую постановку сообщений в очередь
Прерывание в реальном времени
Интеграцию хуков
Естественные многооборотные разговоры

Пример реализации

import { query } from "@anthropic-ai/claude-agent-sdk";

// Простой одноразовый запрос
for await (const message of query({
  prompt: "Объясни поток аутентификации",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// Продолжение разговора с управлением сессией
for await (const message of query({
  prompt: "Теперь объясни процесс авторизации",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Руководства

Потоковый ввод

Понимание двух режимов ввода для Claude Agent SDK и когда использовать каждый

Обзор

Claude Agent SDK поддерживает два различных режима ввода для взаимодействия с агентами:

Режим потокового ввода (По умолчанию и рекомендуется) - Постоянная интерактивная сессия
Ввод одного сообщения - Одноразовые запросы, которые используют состояние сессии и возобновление

Режим потокового ввода (Рекомендуется)

Как это работает

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D", "primaryColor": "#F0F0EB", "primaryTextColor": "#191919", "primaryBorderColor": "#D9D8D5", "secondaryColor": "#F5E6D8", "tertiaryColor": "#CC785C", "noteBkgColor": "#FAF0E6", "noteBorderColor": "#91918D"}, "sequence": {"actorMargin": 50, "width": 150, "height": 65, "boxMargin": 10, "boxTextMargin": 5, "noteMargin": 10, "messageMargin": 35}}}%%
sequenceDiagram
    participant App as Your Application
    participant Agent as Claude Agent
    participant Tools as Tools/Hooks
    participant FS as Environment/<br/>File System
    
    App->>Agent: Initialize with AsyncGenerator
    activate Agent
    
    App->>Agent: Yield Message 1
    Agent->>Tools: Execute tools
    Tools->>FS: Read files
    FS-->>Tools: File contents
    Tools->>FS: Write/Edit files
    FS-->>Tools: Success/Error
    Agent-->>App: Stream partial response
    Agent-->>App: Stream more content...
    Agent->>App: Complete Message 1
    
    App->>Agent: Yield Message 2 + Image
    Agent->>Tools: Process image & execute
    Tools->>FS: Access filesystem
    FS-->>Tools: Operation results
    Agent-->>App: Stream response 2
    
    App->>Agent: Queue Message 3
    App->>Agent: Interrupt/Cancel
    Agent->>App: Handle interruption
    
    Note over App,Agent: Session stays alive
    Note over Tools,FS: Persistent file system<br/>state maintained
    
    deactivate Agent

Преимущества

Загрузка изображений

Прикрепляйте изображения напрямую к сообщениям для визуального анализа и понимания

Сообщения в очереди

Отправляйте несколько сообщений, которые обрабатываются последовательно, с возможностью прерывания

Интеграция инструментов

Полный доступ ко всем инструментам и пользовательским MCP серверам во время сессии

Поддержка хуков

Используйте хуки жизненного цикла для настройки поведения в различных точках

Обратная связь в реальном времени

Видите ответы по мере их генерации, а не только финальные результаты

Постоянство контекста

Поддерживайте контекст разговора через несколько оборотов естественным образом

Пример реализации

import { query } from "@anthropic-ai/claude-agent-sdk";
import { readFileSync } from "fs";

async function* generateMessages() {
  // Первое сообщение
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Проанализируй эту кодовую базу на предмет проблем безопасности"
    }
  };
  
  // Ждем условий или пользовательского ввода
  await new Promise(resolve => setTimeout(resolve, 2000));
  
  // Продолжение с изображением
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Просмотри эту диаграмму архитектуры"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("diagram.png", "base64")
          }
        }
      ]
    }
  };
}

// Обработка потоковых ответов
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 10,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Ввод одного сообщения

Ввод одного сообщения проще, но более ограничен.

Когда использовать ввод одного сообщения

Используйте ввод одного сообщения когда:

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

Ограничения

Режим ввода одного сообщения не поддерживает:

Прямые вложения изображений в сообщениях
Динамическую постановку сообщений в очередь
Прерывание в реальном времени
Интеграцию хуков
Естественные многооборотные разговоры

Пример реализации

import { query } from "@anthropic-ai/claude-agent-sdk";

// Простой одноразовый запрос
for await (const message of query({
  prompt: "Объясни поток аутентификации",
  options: {
    maxTurns: 1,
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

// Продолжение разговора с управлением сессией
for await (const message of query({
  prompt: "Теперь объясни процесс авторизации",
  options: {
    continue: true,
    maxTurns: 1
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}