From 1f48d1633afd646aaf8c2138e71a281a24580215 Mon Sep 17 00:00:00 2001 From: hon2y_b22 Date: Thu, 2 Apr 2026 10:01:40 +0900 Subject: [PATCH] feat: enhance streaming-cast documentation and resources - Added details for the `streaming-cast` skill, including its purpose and use cases for LangGraph v2 streaming. - Updated README and CONTRIBUTING files to reflect the new streaming phase and its components. - Included examples for stream modes, StreamWriter, and integration with SSE/WebSocket. - Improved clarity on the development flow involving streaming capabilities. --- CONTRIBUTING.md | 1 + CONTRIBUTING_KR.md | 1 + README.md | 16 +++++++++++++++- README_KR.md | 16 +++++++++++++++- .../.claude/skills/streaming-cast/SKILL.md | 2 +- .../TEMPLATE_README.md | 8 ++++++++ 6 files changed, 41 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1baa16..89d60b1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -116,6 +116,7 @@ The Act Operator project consists of several components. - `architecting-act`: Architecture design, subgraph composition strategies & CLAUDE.md generation - `developing-cast`: LangGraph cast implementation patterns (create_agent, nodes, memory, middleware) - `developing-deepagent`: DeepAgent harness patterns (create_deep_agent, subagents, backends, sandbox) +- `streaming-cast`: LangGraph v2 streaming patterns (stream modes, StreamWriter, subgraph/agent streaming, SSE/WebSocket integration) - `testing-cast`: Testing strategies ### 4️⃣ Documentation (Separate Repository) diff --git a/CONTRIBUTING_KR.md b/CONTRIBUTING_KR.md index 1423a1b..b246625 100644 --- a/CONTRIBUTING_KR.md +++ b/CONTRIBUTING_KR.md @@ -116,6 +116,7 @@ Act Operator 프로젝트는 여러 컴포넌트로 구성되어 있습니다. - `architecting-act`: 아키텍처 설계, 서브그래프 구성 전략 및 CLAUDE.md 생성 - `developing-cast`: LangGraph Cast 구현 패턴 (create_agent, 노드, 메모리, 미들웨어) - `developing-deepagent`: DeepAgent 하네스 패턴 (create_deep_agent, 서브에이전트, 백엔드, 샌드박스) +- `streaming-cast`: LangGraph v2 스트리밍 패턴 (스트림 모드, StreamWriter, 서브그래프/에이전트 스트리밍, SSE/WebSocket 통합) - `testing-cast`: 테스팅 전략 ### 4️⃣ 문서 (별도 레포) diff --git a/README.md b/README.md index 97130e0..ac848b2 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,8 @@ Skills encode that knowledge as **living files that agents read directly**. Inst │ └── resources/ # 50+ patterns: core, agents, tools, memory, middleware ├── developing-deepagent/ # DeepAgent harness │ └── resources/ # create_deep_agent, subagents, backends, sandbox, HITL +├── streaming-cast/ # Streaming phase harness +│ └── resources/ # Stream modes, subgraph streaming, SSE/WebSocket integration └── testing-cast/ # Testing phase harness └── resources/ # Mocking strategies, fixtures, coverage guides ``` @@ -140,6 +142,7 @@ Skills encode that knowledge as **living files that agents read directly**. Inst - `architecting-act` — Design graph architectures and node composition strategies. Uses an interactive question sequence to understand requirements before producing a CLAUDE.md that becomes the persistent spec for the implementation phase. Supports 4 modes: initial design, add cast, extract sub-cast, redesign cast. - `developing-cast` — Implement LangGraph casts (state, nodes, agents with `create_agent`, tools, memory, middlewares, graph assembly). Reads CLAUDE.md as its source of truth. - `developing-deepagent` — Implement DeepAgent harnesses (`create_deep_agent`, subagents, backends, sandbox execution, HITL). Used when a cast node requires multi-step planning or subagent delegation. +- `streaming-cast` — Implement LangGraph v2 streaming for graphs with subgraphs and agents. Covers stream modes (values, messages, updates, custom, events), StreamWriter, subgraph/agent streaming with namespace parsing, and transport integration (SSE, WebSocket). - `testing-cast` — Write pytest tests with LLM mocking strategies. Covers node-level unit tests and graph integration tests. ## The CLAUDE.md Feedback Loop @@ -168,6 +171,7 @@ sequenceDiagram participant AA as architecting-act participant DC as developing-cast participant DD as developing-deepagent + participant SC as streaming-cast participant TC as testing-cast end participant P as Act Project @@ -190,6 +194,12 @@ sequenceDiagram DD->>P: backend → tools → subagents → middleware → agent assembly end + opt Streaming required + U->>SC: "Add streaming to the chatbot cast" + SC->>P: Read graph.py (graph structure) + SC->>P: Stream mode selection → StreamWriter → subgraph/agent streaming + end + Note over U,P: Phase 3 — Testing (Harness: mocking strategies + coverage guides) U->>TC: "Write tests for the chatbot cast" TC->>P: Read implementation code @@ -210,7 +220,10 @@ sequenceDiagram 3. Implement → "Implement the chatbot based on CLAUDE.md" (developing-cast: reads CLAUDE.md → implements state/nodes/agents/graph) -4. Test → "Write comprehensive tests for the chatbot" +4. Add Streaming → "Add streaming to the chatbot cast" + (streaming-cast: stream mode selection → token streaming, subgraph streaming) + +5. Test → "Write comprehensive tests for the chatbot" (testing-cast: LLM mocking + node unit tests + graph integration tests) ``` @@ -262,6 +275,7 @@ my_workflow/ │ ├── architecting-act/ # Design phase: patterns, templates, validation │ ├── developing-cast/ # Implementation phase: 50+ reference patterns │ ├── developing-deepagent/ # DeepAgent phase: backends, subagents, sandbox +│ ├── streaming-cast/ # Streaming phase: stream modes, subgraph streaming │ └── testing-cast/ # Testing phase: mocking, fixtures, coverage ├── casts/ │ ├── base_node.py # Base node class (sync/async, signature validation) diff --git a/README_KR.md b/README_KR.md index 622338d..c5c0e0c 100644 --- a/README_KR.md +++ b/README_KR.md @@ -131,6 +131,8 @@ OpenCode는 프로젝트 루트의 `.env`를 사용합니다(`langgraph.json`의 │ └── resources/ # 50개 이상 패턴: core, agents, tools, memory, middleware ├── developing-deepagent/ # DeepAgent 하네스 │ └── resources/ # create_deep_agent, 서브에이전트, 백엔드, 샌드박스, HITL +├── streaming-cast/ # 스트리밍 단계 하네스 +│ └── resources/ # 스트림 모드, 서브그래프 스트리밍, SSE/Websocket 통합 └── testing-cast/ # 테스팅 단계 하네스 └── resources/ # 모킹 전략, 픽스처, 커버리지 가이드 ``` @@ -140,6 +142,7 @@ OpenCode는 프로젝트 루트의 `.env`를 사용합니다(`langgraph.json`의 - `architecting-act` — 그래프 아키텍처 및 노드 구성 전략 설계. 요구사항을 파악하기 위한 대화형 질문 시퀀스를 사용하고, 구현 단계의 지속적인 명세가 되는 CLAUDE.md를 출력합니다. 4가지 모드: 초기 설계, Cast 추가, Sub-Cast 추출, Cast 재설계. - `developing-cast` — LangGraph Cast 구현 (state, nodes, `create_agent` 에이전트, tools, memory, middlewares, graph 조립). CLAUDE.md를 단일 진실 소스(Source of Truth)로 읽습니다. - `developing-deepagent` — DeepAgent 하네스 구현 (`create_deep_agent`, 서브에이전트, 백엔드, 샌드박스 실행, HITL). Cast 노드에 다단계 계획이나 서브에이전트 위임이 필요한 경우 사용합니다. +- `streaming-cast` — 서브그래프와 에이전트가 포함된 그래프를 위한 LangGraph v2 스트리밍 구현. 스트림 모드 (values, messages, updates, custom, events), StreamWriter, 네임스페이스 파싱을 통한 서브그래프/에이전트 스트리밍, 전송 계층 통합 (SSE, WebSocket)을 커버합니다. - `testing-cast` — LLM 모킹 전략을 사용한 pytest 테스트 작성. 노드 레벨 단위 테스트와 그래프 통합 테스트를 커버합니다. ## CLAUDE.md 피드백 루프 @@ -168,6 +171,7 @@ sequenceDiagram participant AA as architecting-act participant DC as developing-cast participant DD as developing-deepagent + participant SC as streaming-cast participant TC as testing-cast end participant P as Act Project @@ -190,6 +194,12 @@ sequenceDiagram DD->>P: backend → tools → subagents → middleware → agent assembly end + opt 스트리밍 필요 + U->>SC: "챗봇 Cast에 스트리밍 추가" + SC->>P: graph.py 읽기 (그래프 구조) + SC->>P: 스트림 모드 선택 → StreamWriter → 서브그래프/에이전트 스트리밍 + end + Note over U,P: 3단계 — 테스팅 (하네스: 모킹 전략 + 커버리지 가이드) U->>TC: "챗봇 Cast 테스트 작성" TC->>P: 구현 코드 읽기 @@ -210,7 +220,10 @@ sequenceDiagram 3. 구현 → "CLAUDE.md 기반으로 챗봇 구현" (developing-cast: CLAUDE.md 읽기 → state/nodes/agents/graph 구현) -4. 테스트 → "챗봇에 대한 포괄적인 테스트 작성" +4. 스트리밍 추가 → "챗봇 Cast에 스트리밍 추가" + (streaming-cast: 스트림 모드 선택 → 토큰 스트리밍, 서브그래프 스트리밍) + +5. 테스트 → "챗봇에 대한 포괄적인 테스트 작성" (testing-cast: LLM 모킹 + 노드 단위 테스트 + 그래프 통합 테스트) ``` @@ -262,6 +275,7 @@ my_workflow/ │ ├── architecting-act/ # 설계 단계: 패턴, 템플릿, 검증 │ ├── developing-cast/ # 구현 단계: 50개 이상 참조 패턴 │ ├── developing-deepagent/ # DeepAgent 단계: 백엔드, 서브에이전트, 샌드박스 +│ ├── streaming-cast/ # 스트리밍 단계: 스트림 모드, 서브그래프 스트리밍 │ └── testing-cast/ # 테스팅 단계: 모킹, 픽스처, 커버리지 ├── casts/ │ ├── base_node.py # 베이스 노드 클래스 (동기/비동기, 시그니처 검증) diff --git a/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/.claude/skills/streaming-cast/SKILL.md b/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/.claude/skills/streaming-cast/SKILL.md index 79c203a..59ec753 100644 --- a/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/.claude/skills/streaming-cast/SKILL.md +++ b/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/.claude/skills/streaming-cast/SKILL.md @@ -141,7 +141,7 @@ See [patterns/integration.md](./resources/patterns/integration.md). SSE is the L |----------|----------| | filtering by node name, tag, or namespace | [patterns/filtering.md](./resources/patterns/filtering.md) | | combining multiple stream modes | [patterns/multiple-modes.md](./resources/patterns/multiple-modes.md) | -| SSE / WebSocket transport integration | [patterns/frontend-integration.md](./resources/patterns/frontend-integration.md) | +| SSE / WebSocket transport integration | [patterns/integration.md](./resources/patterns/integration.md) | --- diff --git a/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/TEMPLATE_README.md b/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/TEMPLATE_README.md index 01867e4..d93e93d 100644 --- a/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/TEMPLATE_README.md +++ b/act_operator/act_operator/scaffold/{{ cookiecutter.act_slug }}/TEMPLATE_README.md @@ -186,6 +186,7 @@ Agent Skills are folders of instructions that enable AI agents to **discover** c | `@architecting-act` | Design architecture | Starting {{ cookiecutter.act_name }} Project, Planning new cast, redesigning existing cast, unclear about structure, need CLAUDE.md | | `@developing-cast` | Implement LangGraph cast | Building nodes/agents (create_agent)/tools, need LangGraph patterns | | `@developing-deepagent` | Implement DeepAgent | Using create_deep_agent, need subagents/backends/sandbox/long-term memory | +| `@streaming-cast` | Add streaming | Adding streaming to runtime/API endpoint, need token streaming, custom stream events, subgraph streaming | | `@testing-cast` | Write tests | Creating pytest tests, mocking strategies, fixtures | ### How to Use @@ -205,6 +206,7 @@ Skills guide you through their specific domain: - `architecting-act`: Interactive Q&A → generates `CLAUDE.md` (architecture diagram, node specs, development commands) - `developing-cast`: Reads `CLAUDE.md` (Optional) → implements LangGraph cast code - `developing-deepagent`: Reads `CLAUDE.md` (Optional) → implements DeepAgent components (create_deep_agent) +- `streaming-cast`: Reads graph.py → implements streaming (stream modes, StreamWriter, subgraph/agent streaming) - `testing-cast`: Creates pytest test files ### Recommended Development Flow @@ -215,6 +217,8 @@ Skills guide you through their specific domain: 2. @developing-cast → Implement nodes, agents (create_agent), graphs ↓ (if DeepAgent nodes needed) @developing-deepagent → Implement create_deep_agent, subagents, backends + ↓ (if streaming needed) + @streaming-cast → Add streaming (stream modes, token streaming, subgraph streaming) ↓ 3. @testing-cast → Write and run tests ``` @@ -522,6 +526,7 @@ Agent Skills는 AI 에이전트가 기능을 **발견(Discover)** 하고, 관련 | `@architecting-act` | 아키텍처 설계 | {{ cookiecutter.act_name }} 프로젝트 시작, 새 cast 계획, 기존 cast 재설계, 구조 불명확, CLAUDE.md 필요 시 | | `@developing-cast` | LangGraph Cast 구현 | 노드/에이전트(create_agent)/툴 구현, LangGraph 패턴 필요 시 | | `@developing-deepagent` | DeepAgent 구현 | create_deep_agent 사용, 서브에이전트/백엔드/샌드박스/장기 메모리 필요 시 | +| `@streaming-cast` | 스트리밍 구현 | 런타임/API 엔드포인트 스트리밍 추가, 토큰 스트리밍, 커스텀 스트림 이벤트, 서브그래프 스트리밍 필요 시 | | `@testing-cast` | 테스트 작성 | pytest 테스트 생성, 모킹 전략, 픽스처 | ### 사용 방법 @@ -541,6 +546,7 @@ Agent Skills는 AI 에이전트가 기능을 **발견(Discover)** 하고, 관련 - `architecting-act`: 대화형 Q&A → `CLAUDE.md` 생성 (아키텍처 다이어그램, 노드 명세, 개발 명령어) - `developing-cast`: `CLAUDE.md` 읽기(선택) → LangGraph Cast 코드 구현 - `developing-deepagent`: `CLAUDE.md` 읽기(선택) → DeepAgent 컴포넌트 구현 (create_deep_agent) +- `streaming-cast`: graph.py 읽기 → 스트리밍 구현 (스트림 모드, StreamWriter, 서브그래프/에이전트 스트리밍) - `testing-cast`: pytest 테스트 파일 생성 ### 권장 개발 흐름 @@ -551,6 +557,8 @@ Agent Skills는 AI 에이전트가 기능을 **발견(Discover)** 하고, 관련 2. @developing-cast → 노드, 에이전트(create_agent), 그래프 구현 ↓ (DeepAgent 노드가 필요한 경우) @developing-deepagent → create_deep_agent, 서브에이전트, 백엔드 구현 + ↓ (스트리밍이 필요한 경우) + @streaming-cast → 스트리밍 추가 (스트림 모드, 토큰 스트리밍, 서브그래프 스트리밍) ↓ 3. @testing-cast → 테스트 작성 및 실행 ```