sergenes/mini_agent

에이전트 프레임워크 없이 구축된 최소한의 AI 에이전트입니다. 파이썬, OpenAI SDK, 그리고 while 루프만 사용했습니다.

본 프로젝트는 Sergey Neskoromny가 작성한 Medium 아티클 시리즈와 함께 합니다:

Part 1: 처음부터 AI 에이전트 구축하기: 마법 없이, 결정론적 루프만으로 — 핵심 루프, 제공자(providers), 도구(tools), 혼합 모드(mixed mode)
Part 2: 당신의 AI 에이전트는 실패할 것입니다. 복구 가능하게 만드는 방법은 다음과 같습니다. — 신뢰성 계층: 재시도(retry), 서킷 브레이커(circuit breaker), 스키마 유효성 검사(schema validation), 추적(tracing), 제공자 폴백(provider fallback)

AI 도구, 모바일 개발, 그리고 제가 현재 만들고 있는 모든 것에 대한 더 많은 내용은 LinkedIn과 Medium에서 저를 팔로우하세요!

이 에이전트는 작업을 받아들이고, 필요할 때 도구를 호출하며, 결과를 관찰하고, 최종 답변을 얻을 때까지 루프를 반복합니다. 세 가지 모드가 있습니다:

Mode	작동 방식
local	모든 LLM 호출은 로컬 Ollama 모델로 전송됩니다 — 완전 오프라인
remote	모든 LLM 호출은 클라우드 제공자(OpenAI, Anthropic 또는 Gemini)로 전송됩니다
mixed	로컬 Ollama가 루프를 조정하고; ask_remote()를 통해 복잡한 하위 작업을 원격 모델에 위임합니다

git clone https://github.com/sergenes/mini-agent
cd mini-agent
python -m venv .venv
...

로컬/혼합 모드의 경우, Ollama를 설치하고 함수 호출을 지원하는 모델을 풀(pull)하세요:

ollama pull llama3.1 # 좋은 기본값
ollama pull qwen2.5 # 도구 사용에 강함
ollama pull mistral-nemo # 가벼운 대안
...

python agent.py --mode local "847의 15%는 얼마입니까?"
python agent.py --mode local --local-model qwen2.5 "도쿄 날씨와 오늘 날짜는 무엇인가요?"

# OpenAI
python agent.py --mode remote --provider openai "ReAct 에이전트가 어떻게 작동하는지 설명하세요"
python agent.py --mode remote --provider openai --model gpt-4o "MCP에 대한 상세 설명을 작성해 주세요"
...

python agent.py --mode mixed "오늘 날짜와 양자 얽힘을 간단한 용어로 설명해주세요"
python agent.py --mode mixed --local-model qwen2.5 --provider anthropic "..."

혼합 모드에서는 로컬 모델이 스스로 처리할 것과 ask_remote()를 호출해야 할 시점을 결정합니다.

혼합 모드에서는 로컬 모델이 스스로 처리할 것과 ask_remote()를 호출해야 할 시점을 결정합니다.

간단한 도구 호출(calculate, get_date)은 로컬에서 처리됩니다. 지식 기반 작업은 클라우드로 전송됩니다.

python agent.py --mode local --interactive
python agent.py --mode mixed --interactive

순서대로 제공업체를 시도하고, 구조화된 도구 호출을 지원하지 않는 모델은 건너뜁니다:

`python agent.py --mode local --fallback llama3.1 mistral-nemo

│ Provider	Default model
openai	gpt-4o-mini
...

mini_agent/
├── agent.py # CLI 진입점 — 인자 파싱, REPL, 모드 디스패치
├── core.py # 에이전트 루프: run_agent() 및 run_agent_mixed()
...

• tools.py에 Python 함수 작성하기

• 이를 TOOL_FUNCTIONS에 추가하기

• 그 JSON 스키마를 TOOL_SCHEMAS에 추가하기

web_search와 get_weather 도구는 더미(stub)입니다. 에이전트를 진정으로 유용하게 만들려면 실제 API 호출(Brave Search, Tavily, OpenWeatherMap 등)로 대체해야 합니다.

┌─────────────────────────────────────────┐
│ messages = [system, user_task] │
│ │
...

혼합 모드(mixed mode)에서 ask_remote()는 로컬 모델이 호출할 수 있는 추가 도구입니다. 이를 호출하면 원격 제공업체와 함께 새로운 run_agent()가 실행됩니다.

mcp_server.py는 두 가지 도구 — to_uppercase와 count_words — 를 노출하는 독립적인 Model Context Protocol 서버입니다. 에이전트는 이를 mcp_client.py를 통해 투명하게 호출하며, 에이전트의 관점에서는 다른 어떤 도구와도 다를 바 없습니다.

서버가 시작되는지 확인하기:

python mcp_server.py

이는 표준 입력(stdin)에서 JSON-RPC 메시지를 기다리며 블록됩니다 — 이는 정상입니다. 종료하려면 Ctrl+C를 누르세요. 일반적으로 에이전트가 서브프로세스로 자동으로 실행합니다.

통신 방식:

agent (tools.py)
└── mcp_client.py # asyncio JSON-RPC 클라이언트
└── subprocess: mcp_server.py # stdio에서 작동하는 FastMCP 서버

각 도구 호출은 새로운 서브프로세스를 생성하고, initialize → call_tool 핸드셰이크를 수행한 후 종료됩니다. 자체 MCP 도구를 추가하려면, mcp_server.py에 @mcp.tool()을 사용하여 정의하고, tools.py에서 mcp_to_uppercase와 mcp_count_words와 동일한 패턴을 따라 래퍼 함수를 등록하세요.

calculate()는 Python의 eval()을 빈 빌트인(empty builtins)과 함께 사용합니다 — 데모에는 충분히 안전하지만, 프로덕션 환경에는 아닙니다. 실제 사용을 위해서는 적절한 수학 라이브러리(sympy, asteval)로 대체하세요.- Ollama 함수 호출은 llama3.1, llama3.2, qwen2.5, mistral-nemo와 함께 작동합니다. phi3나 deepseek-r1 같은 모델은

안정성(reliability)을 확실히 지원하지 못할 수 있습니다. - Gemini는 OpenAI와 호환되는 엔드포인트를 사용하며, 별도의 google-generativeai SDK가 필요합니다. - anthropic SDK는 --provider anthropic을 사용할 때만 필요합니다.

변경되지 않은 핵심 루프 위에 reliability.py를 추가했습니다. 모든 항목은 독립적으로 유용하므로 core.py에 변경할 필요가 없습니다.

LLM 수준의 복원력(resilience)

_RetryingProvider — 어떤 제공업체의 complete()도 지수 백오프(exponential backoff) + 지터(jitter)와 함께 래핑하며 (최대 5회 시도). 에이전트 루프는 일시적인 네트워크 오류를 절대 감지하지 못합니다.

도구 수준의 복원력(resilience)

with_retry() — 예외 발생 시 단일 도구 호출을 재시도합니다 (설정 가능한 시도 횟수 및 기본 지연 시간). CircuitBreaker — N번 연속 실패한 도구를 호출하는 것을 중단하고, 타임아웃 후 자동으로 재설정됩니다. validated_call() — 실행 전에 Pydantic을 사용하여 JSON 스키마에 따라 도구 인수를 검증합니다. 모델이 자체 수정할 수 있는 오류 문자열을 반환합니다. traced_call() — 결과와 무관하게 모든 호출(도구 이름, 인수, 결과, 지속 시간)에 대해 구조화된 로그 라인을 방출합니다.

run_agent_reliable() — 네 가지 도구 계층이 모두 쌓인 상태의 run_agent()입니다. 드롭인 대체품입니다.

제공업체 폴백(Provider fallback)

run_agent_with_fallback() — 제공업체 목록을 순서대로 시도하며, 예외* 또는* 암묵적 실패(모델이 구조화된 tool_calls 대신 일반 텍스트로 도구 호출 출력을 출력하는 경우)에 폴백합니다. _looks_like_failed_tool_call() — 암묵적 실패를 감지 가능한 오류로 변환하는 휴리스틱입니다. --fallback MODEL [MODEL …] CLI 플래그 예: --fallback llama3.1 mistral-nemo

agent.py — run_agent_reliable()이 이제 local 및 remote 모드의 기본값이 되었습니다.

핵심 에이전트 루프: agent.py, core.py, providers.py, tools.py, ui.py, MCP 클라이언트/서버.

MIT