🔥 Hephaestus: 반구조화된 에이전트 프레임워크 (Semi-Structured Agentic Framework)

AI 워크플로우가 에이전트가 수행해야 할 일을 발견함에 따라 스스로 지침(instructions)을 작성할 수 있다면 어떨까요?

Quick Start • Documentation • Examples • Join our discord • Hephaestus Dev

</div>

🎥 Hephaestus 작동 영상

Hephaestus가 어떻게 여러 AI 에이전트를 조정(coordinate)하고, 그들의 궤적(trajectories)을 모니터링하며, 워크플로우를 동적으로 구축하는지 확인해 보세요.

</div>

NEW: Hephaestus Dev

Hephaestus를 개발 도구로 사용할 준비가 되셨나요? 저희는 소프트웨어 개발을 위해 5가지 프로덕션 준비 완료(production-ready) 워크플로우가 사전 구성된 Hephaestus Dev를 구축했습니다:

워크플로우 (Workflow)	기능
PRD to Software Builder	제품 요구 사항 문서 (Product Requirements Document)로부터 완전한 소프트웨어를 구축
...

python run_hephaestus_dev.py --path /path/to/project

Hephaestus Dev 시작하기 →

내가 계속해서 마주쳤던 문제

나는 AI 에이전트가 복잡한 소프트웨어 프로젝트를 처리할 수 있는 시스템을 구축하려고 노력하고 있었습니다. 여러분도 아는 그런 종류 말입니다: "OAuth, JWT, 속도 제한(rate limiting), 그리고 포괄적인 테스트를 포함한 인증 시스템을 만들어줘."

전통적인 에이전트 프레임워크(agentic frameworks)는 분기(branch)와 루프(loop)를 생성할 수 있지만, 한 가지 한계가 있습니다: 모든 분기에는 미리 정의된 지침(predefined instructions)이 필요하다는 점입니다. 여러분은 예상되는 모든 시나리오에 대해 작업 설명(task descriptions)을 사전에 작성해야만 합니다.

하지만 여러분이 예상하지 못한 발견은 어떻게 될까요? 테스트 에이전트가 최적화 기회, 보안 문제, 또는 더 나은 아키텍처 패턴을 발견했을 때는 어떻게 해야 할까요?

대신 제가 시도한 방법은 다음과 같습니다: 문제를 해결하는 데 필요한 논리적 단계 유형(예: "계획(Plan) → 구현(Implement) → 테스트(Test)")을 정의하고, 에이전트가 발견한 내용에 따라 어떤 단계에서든 작업을 생성할 수 있도록 하는 것입니다.

실제로 일어난 일: 스스로 구축되는 분기 트리 (Branching Tree)

경직된 순서 대신, 저는 다음과 같은 단계 유형을 설정했습니다:

1단계 (분석, Analysis): 이해, 계획, 조사
2단계 (구현, Implementation): 구축, 수정, 최적화
3단계 (검증, Validation): 테스트, 확인, 품질 점검

핵심 통찰은 다음과 같습니다: 에이전트는 자신이 원하는 어떤 단계에서든 작업을 생성(spawn)할 수 있습니다.

인증 시스템을 테스트하는 검증 에이전트가 우아한 캐싱 패턴을 발견할 수도 있습니다. 에이전트가 막히거나(또는 당신이 작성한 미리 정의된 분기 로직을 따르는 대신), 다음과 같이 행동합니다:

1단계 조사 작업을 생성합니다: "인증 캐싱 패턴 분석 - 12개의 다른 API 경로에 적용하여 속도를 40% 향상시킬 수 있음"
자신의 검증 작업을 계속 수행합니다
다른 에이전트가 해당 조사 작업을 넘겨받아 탐색을 시작합니다

워크플로우가 스스로 분기된 것입니다. 당신이 "만약 최적화 기회를 발견하면 조사 작업을 생성하라"라고 예측했기 때문이 아니라, 에이전트가 탐색할 가치가 있는 무언가를 발견했고 그것을 위한 작업을 생성할 자유가 있었기 때문입니다.

이는 예상된 시나리오가 아니라 실제 발견을 바탕으로 성장하는 **작업의 분기 트리 (branching tree of tasks)**를 만들어냅니다.

이것이 실제로 어떻게 작동하는지 보여드리겠습니다:

예시: PRD를 통한 구축

저는 Hephaestus에게 제품 요구사항 문서(PRD)를 제공합니다: "인증, REST API, React 프론트엔드를 갖춘 웹 애플리케이션을 구축하라."

1단계 에이전트는 PRD를 읽고 5가지 주요 구성 요소를 식별합니다:

인증 시스템 (Authentication system)
REST API 레이어 (REST API layer)
React 프론트엔드 (React frontend)
데이터베이스 스키마 (Database schema)
백그라운드 워커 (Background workers)

에이전트는 각 구성 요소에 대해 하나씩, 총 5개의 2단계 작업을 생성합니다. 이제 저는 각 요소에 집중하는 5개의 에이전트가 병렬로 구축을 진행하는 상태가 됩니다.

2단계 에이전트 중 하나가 REST API 구축을 완료하고 3단계 검증 작업을 생성합니다: "REST API 엔드포인트 테스트."

3단계 에이전트가 테스트를 시작합니다. 모든 테스트를 통과합니다. 하지만 그때 에이전트가 무언가를 발견합니다:

"인증 (auth) 엔드포인트가 데이터베이스 쿼리를 60% 줄여주는 캐싱 패턴 (caching pattern)을 사용하고 있습니다. 이를 통해 모든 API 경로 (routes)의 속도를 크게 향상시킬 수 있습니다."

여기서부터 흥미로운 지점이 시작됩니다.

3단계 에이전트는 단순히 이 관찰 내용을 로그에 남기고 다음으로 넘어가지 않습니다. 워크플로 계획 (workflow plan)에 "최적화 조사"라는 항목이 없다고 해서 멈춰 서지도 않습니다.

대신, 에이전트는 새로운 1단계 조사 작업 (Phase 1 investigation task)을 생성합니다: "인증 캐싱 패턴 분석 — 주요 성능 향상을 위해 다른 API 경로에 적용 가능 여부 확인."

<div align="center"> <img src="assets/hephaestus_overview.png" alt="Hephaestus System Overview" width="100%"> <p><em>실시간 뷰: 3개 단계에 걸쳐 작동하는 2개의 에이전트, 90%의 일관성 (coherence)으로 모니터링 중인 Guardian</em></em></p> </div>

새로운 1단계 에이전트가 생성되어 캐싱 패턴을 조사하고, 그것이 실행 가능하다는 것을 확인한 뒤, **2단계 구현 작업 (Phase 2 implementation task)**을 생성합니다: "모든 API 경로에 캐싱 패턴 적용."

또 다른 에이전트가 이를 구현합니다. 또 다른 에이전트가 이를 검증합니다.

워크플로가 스스로 분기(branch)되었습니다. 아무도 이 최적화를 계획하지 않았습니다. 한 에이전트가 테스트 도중 이를 발견하고, 이를 탐구하기 위한 새로운 작업을 만들어낸 것입니다.

한편, 다른 3단계 에이전트는 인증 (authentication) 컴포넌트를 테스트하고 있습니다. 테스트가 실패합니다. 그래서 에이전트는 **2단계 버그 수정 작업 (Phase 2 bug fix task)**을 생성합니다: "인증 토큰 만료 검증 수정 — 현재 구현 방식은 만료된 토큰을 허용함."

수정 에이전트가 해결책을 구현하고 **3단계 재테스트 (Phase 3 retest)**를 생성합니다: "인증 수정 사항 검증."

방금 무슨 일이 일어난 걸까요?

새롭게 나타난 모습을 보십시오:

graph TB
    P1[Phase 1: PRD 분석<br/>5개의 티켓 생성] --> P2A[Phase 2: 인증 구축]
    P1 --> P2B[Phase 2: API 구축]
...

이 워크플로우는 스스로 구축되었습니다:

1개의 분석 작업(analysis task)으로 시작
5개의 병렬 구현 작업(implementation tasks)으로 분기
하나의 테스트 단계에서 최적화 사항 발견 → 3단계 조사 브랜치(investigation branch) 생성
또 다른 테스트 단계에서 버그 발견 → 수정(fix) → 재테스트 루프 생성
모든 과정은 차단 관계(blocking relationships)를 가진 칸반 티켓(Kanban tickets)을 통해 조정됨

<div align="center"> <img src="assets/kanban_board.png" alt="Kanban Board Created in Real-Time" width="100%"> <p><em>에이전트에 의해 자동으로 구축된 칸반 보드: 백로그(Backlog) → 구축 중(Building) → 테스트 중(Testing) → 완료(Done)</em></p> </div> <div align="center"> <img src="assets/tickets_interaction.png" alt="Workflow Dependencies" width="100%"> <p><em>어떤 티켓이 다른 티켓을 차단하는지 보여주는 의존성 그래프(Dependency graph) - Hephaestus가 발견한 워크플로우 구조</em></p> </div>

이것이 모든 것을 바꾸는 이유

전통적인 워크플로우 (Traditional workflows): 모든 시나리오를 사전에 예측 → 경직된 계획 → 현실이 예측과 다를 때 무너짐

Hephaestus 방식: 작업 유형(work types) 정의 → 에이전트가 발견 → 워크플로우가 실시간으로 적응

워크플로우는 우리가 사전에 예측한 것이 아니라, 에이전트가 실제로 발견한 내용을 바탕으로 실시간으로 적응합니다.

세미-스트럭처드(Semi-Structured)의 최적 지점

이것이 왜 "세미-스트럭처드(semi-structured, 반구조화된)" 방식인지, 그리고 그것이 왜 중요한지에 대한 이유입니다:

완전 구조화된 워크플로우 (Fully structured workflows) (전통적인 프레임워크):

❌ 모든 시나리오에 대해 미리 정의된 프롬프트(predefined prompts)가 필요함
❌ 분기(branch)나 루프(loop)는 가능하지만, 각 경로에 대해 고정된 지침이 필요함
❌ 모든 발견 사항을 사전에 예측해야 함

완전 비구조화된 에이전트 (Fully unstructured agents) (혼돈):

❌ 조정(coordination)이 없음
❌ 중복 작업 발생
❌ 모순되는 변경 사항 발생
❌ 명확한 성공 기준이 없음

세미-스트럭처드 (Hephaestus):

✅ **단계 정의 (Phase definitions)**가 작업 유형의 구조와 가이드라인을 제공함
✅ 에이전트가 작업 설명(task descriptions)을 작성하며, 발견 사항에 따라 동적으로 움직임
✅ **칸반 티켓 (Kanban tickets)**이 차단 관계를 통해 작업을 조정함
✅ **가디언 모니터링 (Guardian monitoring)**이 에이전트가 단계별 목표에 부합하도록 보장함
✅ 워크플로우가 사용자의 예측이 아닌, 에이전트가 실제로 찾아낸 것에 맞춰 적응함

중요한 부분에는 구조(structure)를 제공합니다:

페이즈 유형 (Phase types)은 어떤 종류의 작업이 진행 중인지 정의합니다
완료 정의 (Done definitions)는 명확한 완료 기준을 설정합니다
가디언 (Guardian)은 페이즈 지침과의 정렬(alignment)을 검증합니다
티켓 (Tickets)은 의존성을 추적하고 혼란을 방지합니다

필요한 부분에는 유연성(flexibility)을 제공합니다:

에이전트가 즉석에서 상세한 작업 설명을 생성합니다
가능한 모든 분기(branch)를 미리 정의할 필요가 없습니다
발견 사항(discoveries)이 실시간으로 워크플로우 확장을 주도합니다
에이전트가 탐색함에 따라 새로운 작업 유형이 나타납니다

🚀 빠른 시작 (Quick Start)

사전 요구 사항 (Prerequisites)

Python 3.10+
tmux - 에이전트 격리를 위한 터미널 멀티플렉서 (Terminal multiplexer)
Git - 프로젝트는 반드시 git 저장소여야 합니다
Docker - Qdrant 벡터 스토어 (vector store) 실행용
Node.js & npm - 프론트엔드 UI용
Claude Code, OpenCode, Droid, 또는 Codex - 에이전트가 내부에서 실행할 CLI AI 도구
API 키: OpenAI, OpenRouter, Anthropic (또한 Azure OpenAI, Google AI Studio 지원 - LLM 구성 참조)

환경 설정 확인 (macOS)

시작하기 전에 모든 것이 올바르게 설치되고 구성되었는지 확인하십시오:

python check_setup_macos.py

이 스크립트는 다음을 확인합니다:

✅ 모든 필수 CLI 도구 (tmux, git, docker, node, npm, Claude Code)
✅ .env 파일의 API 키
✅ 구성된 MCP 서버
✅ 설정 파일 및 작업 디렉토리
✅ 실행 중인 서비스 (Docker, Qdrant)
✅ Python 및 프론트엔드 의존성 (dependencies)

스크립트는 설정된 항목과 주의가 필요한 항목을 보여주는 색상 코드 보고서를 제공합니다.

10분 만에 시작하기

첫 번째 자가 적응형 워크플로우 (self-adapting workflow)를 구축해 보세요:

👉 빠른 시작 가이드 (Quick Start Guide)

가이드는 다음 과정을 안내합니다:

API 키 설정 및 LLM (Large Language Model) 구성
MCP (Model Context Protocol) 서버 설정 (Hephaestus + Qdrant)
작업 디렉토리 (Working Directory) 설정
동적 작업 생성 (Dynamic Task Generation)을 통한 단계(Phases) 정의
실시간으로 적응하는 워크플로우 (Workflow) 실행
에이전트들이 협력하고 새로운 작업을 자동으로 발견하는 과정 관찰

<div align="center"> <img src="assets/hephaestus_observability.png" alt="Agent Observability" width="100%"> <p><em>실시간 관찰 가능성 (Real-time observability): 에이전트들이 워크플로우를 발견하고 구축하는 동안 격리된 Claude Code 세션에서 작업하는 모습을 지켜보세요</em></p> </div>

더 자세히 알고 싶으신가요? 다음 내용을 확인하려면 전체 문서 (Full Documentation)를 참조하세요:

전체 아키텍처 (Architecture) 및 기술적 세부 사항
API 레퍼런스 (Reference) 및 SDK 가이드
워크플로우 예시 및 템플릿
베스트 프랙티스 (Best Practices) 및 고급 기능

🤝 도움받기

📖 Documentation - 전체 가이드, API 레퍼런스 및 튜토리얼
💬 GitHub Discussions - 질문하기 및 아이디어 공유
🐛 Issue Tracker - 버그 보고 및 기능 요청
📧 Email - 지원 또는 협업을 위한 연락

Hephaestus: 워크플로우가 스스로 구축되는 곳

대장간의 그리스 신의 이름을 따온 Hephaestus는 에이전트가 작업하면서 워크플로우를 직접 만들어가는 시스템을 구축합니다

Quick Start • Documentation

License: AGPL-3.0 • Status: Alpha - 활발히 개발 중

</div>

Show HN: Hephaestus – 자율적 멀티 에이전트 오케스트레이션 프레임워크 (Autonomous Multi-Agent

요약

핵심 포인트

🔥 Hephaestus: 반구조화된 에이전트 프레임워크 (Semi-Structured Agentic Framework)

🎥 Hephaestus 작동 영상

NEW: Hephaestus Dev

내가 계속해서 마주쳤던 문제

실제로 일어난 일: 스스로 구축되는 분기 트리 (Branching Tree)

예시: PRD를 통한 구축

방금 무슨 일이 일어난 걸까요?

이것이 모든 것을 바꾸는 이유

세미-스트럭처드(Semi-Structured)의 최적 지점

🚀 빠른 시작 (Quick Start)

사전 요구 사항 (Prerequisites)

환경 설정 확인 (macOS)

10분 만에 시작하기

🤝 도움받기

댓글