Agentic Framework를 처음부터 구축하기 🚀
Source: Dev.to
위의 링크에 포함된 전체 텍스트를 제공해 주시면, 해당 내용을 한국어로 번역해 드리겠습니다. (코드 블록, URL, 마크다운 형식 및 기술 용어는 그대로 유지됩니다.)
도전 과제: 왜 새로운 프레임워크를 만들까?
나는 솔직히 에이전트가 스스로 전략을 사용해 사고하고 추론하는 것이 무엇이 필요한지 궁금했다—우리가 작업을 수행하는 방식과 비슷하게. 당시 에이전시 프레임워크는 적은 코드로 괜찮은 에이전트를 만들 수 있는 제어가 거의 없었기에, 직접 시도해보고 싶었다.
대부분의 기존 에이전트 프레임워크는 다음 중 하나이다:
- 에이전트를 단순 LLM + 툴 루프 로 취급한다
- 장황하거나 반복적인 설정이 필요하다
- 추론이나 전략의 유연성을 제한한다
첫날부터 나는 다른 것을 원했다:
- 작업 중에 생각하고, 행동하고, 전환할 수 있는 에이전트
- 이해하기 쉬운 명확하고 타입 안전한 API
- 어떤 에이전시 작업에도 적용할 수 있는 조합 가능한 전략
- 개발자가 언제나 에이전트가 무엇을 하고 왜 하는지 알 수 있도록 관찰 가능한 이벤트
목표는 간단했다: 똑똑하고 반응형 AI 에이전트를 직관적이고 안전하며 강력하게 만들면서 유연성을 희생하지 않는 것.
반응형 에이전트의 핵심 원칙
-
반응형 의사결정
- 에이전트는 고정된 계획을 따르기보다 작업 입력 및 중간 결과에 반응합니다.
- 내장된 리플렉션을 통해 결과가 기대와 다를 경우 전략을 전환할 수 있습니다.
-
도구 통합 및 MCP 지원
- 에이전트는 맞춤형 Python 도구를 실행하거나 MCP 서버를 활용하여 모듈식 워크플로를 구성할 수 있습니다.
- 이를 통해 복잡한 오케스트레이션 없이 분산형 다중 도구 파이프라인을 구현할 수 있습니다.
-
관측 가능성 및 투명성
- 모든 에이전트 행동은 관측 가능한 이벤트를 발생시킵니다.
- 개발자는 실시간으로 추론, 도구 사용 및 의사결정 경로를 추적할 수 있습니다.
-
조합성 및 타입 안전성
- 추론 전략은 모듈식이며 교체, 확장 또는 결합이 쉽습니다.
- 타입 안전 API는 런타임 오류를 줄이고 개발을 예측 가능하게 합니다.
-
사용 용이성
- 빌더 패턴은 깔끔하고 최소한의 보일러플레이트 설정을 제공합니다.
- 빠른 시작 시간과 폭넓은 모델 지원으로 실험이 빠르고 보람됩니다.
Reactive Loop 설계
프레임워크의 핵심은 reactive loop이며, 이는 에이전트가 작업을 처리하는 방식을 안내합니다:
Receive Task → Reasoning Layer → Tool Execution → Observe Feedback → Reflect & Adapt → (repeat)- Receive Task – 에이전트가 사용자 또는 시스템으로부터 입력을 받습니다.
- Reasoning Layer – 어떤 도구나 전략을 사용할지 결정합니다.
- Tool Execution – 커스텀 또는 MCP 기반 도구를 실행합니다.
- Observe Feedback – 이벤트, 결과 및 출력물을 추적합니다.
- Reflect & Adapt – 필요에 따라 전략을 업데이트하고, 다시 반복합니다.
이 아키텍처는 에이전트가 정적이지 않음을 보장합니다. 에이전트는 실행 중에 학습하고 적응하여 다양한 에이전트 작업에 적합합니다.
구현 하이라이트
- Builder Pattern – 간단하고 가독성 좋은 에이전트 생성.
- Composable Strategies – 에이전트를 다시 작성하지 않고도 추론 모듈을 교체 가능.
- Observable Events – 디버깅 및 인사이트 확보가 원활.
- Type‑Safe APIs – 오류를 조기에 포착하고 개발자 신뢰도를 향상.
- MCP Integration – 분산 에이전트 아키텍처와 모듈형 워크플로를 지원.
예시: 최소 반응형 에이전트
아래는 정확하고 문서와 일치하는 예시로, 사용자 정의 파이썬 도구와 MCP 도구를 모두 사용하는 반응형 에이전트를 보여줍니다:
import asyncio
from reactive_agents.agents import ReactAgentBuilder
from reactive_agents.tools.decorators import tool
# Define a simple custom tool
@tool(description="Greet a user")
async def greet(name: str) -> str:
"""Use this tool to greet the user by their provided name."""
return f"Hello, {name}! Welcome to Reactive Agents."
async def main():
agent = await (
ReactAgentBuilder()
.with_name("DemoAgent")
.with_model("ollama:qwen3:4b") # Example model string
.with_tools(["brave-search", greet]) # Auto‑detects MCP tools vs custom tools
.with_observable_events() # Track events
.build()
)
result = await agent.run(
"Greet a new user and fetch latest news about AI."
)
print(result)
if __name__ == "__main__":
asyncio.run(main())이 코드 조각은 반응형 추론, 도구 실행, 그리고 관찰 가능한 이벤트를 보여주며, 새로운 사용자도 이해하기 쉽게 구성되어 있습니다.
Lessons Learned While Building the Framework
- 관측성을 초기에 설계하세요 – 이벤트 추적 없이는 복잡한 에이전트를 디버깅하기 어렵습니다.
- 추론을 모듈화하세요 – 조합 가능한 전략은 기존 코드를 깨뜨리지 않고 실험을 가능하게 합니다.
- API를 직관적으로 유지하세요 – 개발자는 설정에 얽히기보다 에이전트 설계에 더 많은 시간을 투자해야 합니다.
- 다양한 도구와 제공자를 지원하세요 – 유연성은 실제 에이전트 작업에 필수적입니다.
앞으로
Reactive Agents는 알파‑단계이지만 프로덕션에 사용할 수 있습니다. API는 진화할 수 있지만 핵심 원칙은 안정적입니다: 반응 루프, 조합 가능한 추론, 가시성, 그리고 도구 통합.
이 프레임워크가 개발자들이 새로운 방식으로 에이전시 AI를 탐구하도록 영감을 주길 바랍니다. 단순히 반응하는 것이 아니라 동적으로 추론하고, 행동하며, 개선하는 더 똑똑한 애플리케이션을 만들 수 있기를 바랍니다.
참여하기
시도해보고, 저장소에 스타를 달고, 혹은 기여하세요:
GitHub:
buell/reactive-agents
Whether it’s extending reasoning strategies, adding tools, or improving observability, **your contributions help shape the next generation of reactive AI agents**.