jjyaoao/HelloAgents

HelloAgents – 프로덕션 수준의 다중 에이전트 프레임워크 (Python)

무엇인가요 – OpenAI 호환 API 위에 구축된 Python 라이브러리로, 다중 에이전트 애플리케이션을 구축하기 위한 즉시 사용 가능한 확장 가능한 플랫폼을 제공합니다. 도구 응답 프로토콜, 컨텍스트 관리, 세션 지속성, 하위 에이전트 라우팅, 옵티미스틱 파일 잠금, 서킷 브레이커, 기술 로딩, 진행 추적, 로깅, 관측성, SSE를 통한 스트리밍, 비동기 라이프사이클 등 엔지니어링 수준의 기능을 통합하여, 반복 코드보다 에이전트 로직에 집중할 수 있도록 합니다.

핵심 개념

구성 요소	역할
HelloAgentsLLM	OpenAI 호환, Anthropic, Gemini 제공자 중 하나를 감싸는 래퍼. `LLM_BASE_URL`에서 자동으로 적절한 어댑터를 감지합니다.
에이전트 기본 클래스 (`ReActAgent`, `SimpleAgent`, `ReflectionAgent`, `PlanAndSolveAgent`)	함수 호출 / ReAct 패턴을 구현하며, 도구 호출, 도구 응답, 반복적 추론을 처리합니다.
ToolRegistry & ToolResponse	내장 또는 사용자 정의 도구(파일 읽기/쓰기, 작업 위임, TODO 추적, 개발 로그, 기술 추출)를 등록. 레지스트리는 `ToolResponse` 스키마를 강제합니다.
SessionStore	대화 기록을 디스크에 지속하여 에이전트가 나중에 재개할 수 있도록 합니다.
HistoryManager / TokenCounter / ContextBuilder	컨텍스트 창을 관리하고, 토큰 수를 세며, 제한에 도달하면 자르기 기능을 제공합니다.
CircuitBreaker	설정 가능한 실패 임계값을 초과하면 무한한 도구 호출을 방지합니다.
TraceLogger	구조화된 추적을 출력하여 관측성 제공(디버깅 또는 모니터링에 유용).
스트리밍 (SSE)	부분적인 LLM 출력을 실시간으로 클라이언트에 전송합니다.

빠른 시작

pip install hello-agents

from hello_agents import ReActAgent, HelloAgentsLLM, ToolRegistry
from hello_agents.tools.builtin import ReadTool, WriteTool, TodoWriteTool

llm = HelloAgentsLLM()                     # .env에서 제공자 자동 감지
registry = ToolRegistry()
registry.register_tool(ReadTool())
registry.register_tool(WriteTool())
registry.register_tool(TodoWriteTool())

agent = ReActAgent(name="assistant", llm=llm, tool_registry=registry)
agent.run("프로젝트 구조를 분석하고 보고서를 생성")

API 자격 증명을 포함하는 .env 파일을 생성합니다:

LLM_MODEL_ID=your-model-name
LLM_API_KEY=your-api-key
LLM_BASE_URL=api.your‑provider.com

라이브러리는 URL 기반으로 올바른 어댑터(OpenAI 호환, Anthropic, Gemini)를 자동으로 선택합니다.

설치 및 호환성

Python ≥ 3.10
PyPI에서 배포됨: hello-agents
MIT 스타일 소스 코드이지만, 프로젝트는 CC BY‑NC‑SA 4.0 (비영리, 공유 동일)로 라이선스됨. 상용 사용은 유지보수자에게 문의 필요.

프레임워크 확장하기

사용자 정의 도구 추가 – ToolResponse를 구현(함수, 클래스, 확장 가능한 스타일)하고 ToolRegistry.register_tool()로 등록합니다.
새로운 에이전트 만들기 – hello_agents.core.agent.Agent를 상속하고 plan/act 메서드를 오버라이드하거나, 제공된 에이전트(SimpleAgent, ReActAgent 등)를 재사용합니다.
새로운 LLM 제공자 연결 – core/llm_adapters.py에 기존 OpenAI/Anthropic/Gemini 인터페이스를 따르는 어댑터를 추가합니다.

문서 및 리소스

Docs 폴더 – 16개의 핵심 기능(도구 응답 프로토콜, 컨텍스트 엔지니어링, 관측성, 서킷 브레이커, 세션 지속성, 하위 에이전트 메커니즘, 기술 시스템, 옵티미스틱 잠금, TODO 진행 상황, 개발 로그, 비동기 라이프사이클, SSE 스트리밍, 함수 호출 아키텍처, 로깅 시스템, 사용자 정의 도구 개발)에 대한 상세 가이드.
예제 – examples/ 폴더 내 실행 가능한 스크립트로 일반적인 워크플로우를 보여줍니다.
학습용 버전 – Datawhale "Hello‑Agents" 튜토리얼과 일치하는 안정 브랜치(learn_version) 제공.
커뮤니티 포트 – 비Python 생태계용 Go(HelloAgents-go) 및 TypeScript(HelloAgents-ts) 재구현.

라이선스

코드는 Creative Commons BY‑NC‑SA 4.0 하에 배포됩니다. 저자에게 출처를 표기하고 동일한 라이선스를 유지하는 한, 비영리 목적에서 사용, 수정, 공유할 수 있습니다. 상용 사용은 유지보수자와 별도 계약 필요.

결론 – HelloAgents는 다중 에이전트 AI 시스템을 위한 프로덕션 준비된 틀을 제공하며, 도구 오케스트레이션, 컨텍스트 제한, 지속성, 관측성과 같은 번거로운 엔지니어링 문제를 처리하여 개발자가 에이전트의 도메인 로직에 집중할 수 있도록 합니다.