Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Agentica는 CLI, 로컬 Web, 데스크톱 App으로 동작하는 에이전트 프레임워크입니다. DeepSeek 같은 개방형 모델에 깊이 적응하여 높은 정확도와 효율성을 자랑합니다. 특히 OpenAI Codex와 비교했을 때 코딩 및 데이터 분석 문제에서 동등하거나 더 높은 성능을 보이며 속도와 토큰 사용량 면에서도 우수함을 입증했습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기도구 측면은 의도적으로 좁게 가져가고 인터페이스는 낮은 수준을 유지하여 DeepSeek과 같은 개방형 모델에 깊이 적응했습니다. OpenAI Codex와 각각 동일한 모델 및 공개된 문제 세트를 사용하여 정면 비교했을 때:
<p align="center"> <img src="https://raw.githubusercontent.com/shibing624/agentica/main/docs/assets/benchmark-agentica-vs-codex.png" width="920" alt="Benchmark: Agentica는 coding 및 data analysis 두 공개 문제 세트에서 Codex에 못지않은 정확도를 보이며, 클럭 시간과 입력 토큰 모두 적다" /> </p>프로그래밍 문제는 만점, 데이터 분석 문제는 더 높은 정확도——게다가 2배 빠르고 입력 토큰은 3분의 2가 적습니다. 재현 명령어, 항목별 지표 및 원본 predictions.jsonl는 평가 페이지를 참조하세요.
터미널 세션 하나는 협업이 가능한 agent입니다. 프로세스 내의 task는 임시 subagent를 호출하고, 프로세스 레벨의 delegate는 독립적인 큰 작업을 수행하기 위해 별도의 agent를 시작하며, 터미널 간의 peer 메시지는 두 세션이 서로 대화할 수 있게 합니다——이 모든 과정에 추가 배포가 필요하지 않습니다.
실행된 경험은 자동으로 재사용 가능한 SKILL.md로 컴파일됩니다. 다음에 유사한 작업을 만날 경우, agent는 처음부터 시작하는 것이 아니라 자신이 이전에 얻었던 결론을 읽습니다. 프로세스는 Skills 문서를 참조하세요.
업계 주류의 방식은 LLM이 이전 내용을 요약하여 초록을 만드는 것입니다. 이는 추가 호출 비용이 들고, 손실적이며, 요약 과정에서 사라진 세부 정보는 다시 가져올 수 없습니다. Agentica의 압축 경로는 전 과정에 걸쳐 LLM 요약을 사용하지 않습니다:
read_file을 사용해야 합니다. 대화 자체에 파일을 읽는 능력이 없을 때는 조용히 잘라내고 그 사실을 설명하며, 아무도 열 수 없는 경로를 절대 제공하지 않습니다.<context_window>를 추가하고 인계 노트(notes)를 사용하여 빈 활동 창을 만듭니다. 가짜 요약 라운드를 합성하지 않습니다.원본은 항상 session JSONL에 남아 있으며, search_session으로 언제든지 키워드 검색을 통해 회수할 수 있습니다. 결과: 장기 대화에서 기억 상실이 없고, 압축을 위해 추가 토큰 비용이 들지 않으며, 모든 압축 지점을 추적할 수 있습니다. 세부 사항은 압축 문서를 참조하세요.
微信 / 企微 / 飞书 / Telegram을 통해 로컬 agent에 직접 연결: @대화 이름으로 주소를 찾거나, 사람의 언어로 한 문장만 말하여 게이트웨이 agent가 이 기기상의 모든 대화를 지휘하게 할 수 있습니다.
CLI(agentica)와 Web/Desktop 백엔드(agentica-gateway) 모두 uv tool을 사용하여 격리 환경에 설치하며, 시스템 Python에 종속되지 않습니다. uv가 없다면:
curl -LsSf https://astral.sh/uv/install.sh | sh # 독립 설치, ~/.local/bin에 저장
# macOS의 경우: brew install uv
# CLI
uv tool install agentica
...
이미 CLI를 설치했고 Web을 추가할 경우: `uv tool install --force
<details> <summary><b>🪟 Windows에서 'Windows가 사용자의 컴퓨터를 보호했습니다' 알림</b></summary>SmartScreen은 서명되지 않은 설치 프로그램을 차단합니다. 이때 '추가 정보' → '실행'을 클릭해야 합니다. 처음 한 번만 필요합니다.
</details> <details> <summary><b>🐧 Linux에서 AppImage 더블클릭 시 반응 없음</b></summary>브라우저를 통해 다운로드한 AppImage는 기본적으로 실행 권한이 없습니다 (deb는 패키지 관리자를 사용하므로 이 문제가 없습니다):
chmod +x Agentica-x86_64.AppImage
소스 코드에서 직접 실행할 수도 있습니다: cd desktop && npm install && npm start (자세한 내용은 desktop/README.md를 참조하세요).
어떤 모델 제공업체의 API Key를 사용해도 됩니다 (우선순위: 셸 환경 변수 > .env > config.yaml):
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_API_KEY="sk-xxx"
# 또는 무료로 시작할 수 있는 지푸(智谱) 사용: export ZAI_API_KEY="your-api-key"
~/.agentica/.env에 작성하거나, agentica setup을 실행하여 ~/.agentica/config.yaml 파일을 생성할 수도 있습니다 (CLI 내에서 /model로 언제든지 전환 가능). 전체 설명은 설치 문서를 참조하세요.
터미널에 입력:
agentica
대화형 터미널로 진입한 후 바로 말하면 됩니다. 예를 들어, '이 저장소의 단위 테스트가 왜 실패했는지 봐줘'와 같이 요청할 수 있습니다.
<img src="https://raw.githubusercontent.com/shibing624/agentica/main/docs/assets/cli_snap.png" width="800" alt="Agentica CLI 스크린샷" />uv tool install "agentica[gateway]"
agentica-gateway
로컬 웹 페이지는 http://127.0.0.1:8881/chat에서 접근 가능합니다 (채팅, 기록, 설정). 최초 실행 시 default 계정이 생성되고 임의 초기 비밀번호가 터미널에 표시됩니다. 관리자는 '사용자 관리' 페이지에서 계정을 추가할 수 있으며, 각 계정은 독립적인 세션과 메모리를 가집니다. 위챗(微信) / 텐센트 워크스페이스(企微) / 피쉬부(飞书) / Telegram 직접 연결 방법은 Gateway 문서를 참조하세요.
자체 호스팅 (Docker, 이미지에 UI가 포함되어 있어 실행 시 Node 설치 불필요):
cp .env.docker.example .env # OPENAI_API_KEY 채우기
docker compose up -d --build
브라우저에서 http://127.0.0.1:8881/chat을 열면 됩니다. 데이터는 named volume에 저장되며, 현재 디렉토리는 컨테이너의 /workspace로 마운트됩니다.
이미 실행 중인 gateway에서 Node 스크립트를 작성할 때 사용하며, Web UI를 시작하는 단계가 아닙니다:
npm install @agentica-ai/sdk
패키지 이름은 반드시 **@agentica-ai/sdk**로 전체를 적어야 합니다 (registry.npmjs.org, agentica-sdk로 쓰지 마세요).
源码는 sdk-ts/에 있습니다.
Agent가 자료 검색 및 파일 작성 작업을 직접 수행하도록 하고, run_sync 한 줄로 작동을 시작할 수 있습니다:
from agentica import Agent, OpenAIChat, BuiltinWebSearchTool, BuiltinFileTool, BuiltinExecuteTool
agent = Agent(
...
즉시 사용 가능한 완전체(내장 도구 + 압축 + 장기 기억 + 스킬 + MCP):
from agentica import DeepAgent
agent = DeepAgent()
핵심 엔진
asyncio.gather() 병렬 도구 실행, 동기 어댑터 호환read_file / write_file / apply_patch / grep / glob, execute, 웹 검색; 장문 보고서는 write_file을 이용해 HTML로 작성제품 진입점
agentica 대화형 터미널; 프로세스 내의 task, 프로세스 레벨의 delegate, 크로스 터미널 peer 메시지agentica-gateway 로컬 SPA(채팅 / 트랙잭션 / 설정) + IM 채널협업
Agent.as_tool() , Workflow, Swarm, Markdown Subagent; CLI: task / delegate / peer 메시지 (참고 터미널 문서)refine() + 다중 Critic 병렬 심사, SchemaCritic 프로그램 레벨 제로 비용 검증 / AgentCritic 이종 강력 모델 게이트키핑, 루프 감지를 통한 자동 조기 종료기억 및 진화
AGENTS.md에 작성search_session을 통해 언제든 복구 가능하며, 인계는 <session>.notes.md 작성SKILL.md로 만듦통합
아키텍처 및 실행 엔진(Agentic Loop, 2단계 컨텍스트 압축, 4단계 가드레일)은 아키텍처 문서를 참조하세요.
task / delegate / peer| 메커니즘 | 기능 | 사용 시점 |
|---|---|---|
task | 동일 프로세스 subagent (기본 auxiliary 모델, 읽기 전용) | 코드 검색, 자료 조사 등 짧은 작업 |
| ... | ||
| 선택 상세: Choosing · 터미널 문서。 |
examples/에서 전체 예시를 확인하고, 다음 내용을 다룹니다:
| 카테고리 | 내용 |
|---|---|
| 기본 사용법 | Hello World, 스트리밍 출력, 구조화된 출력, 다중 라운드 대화, 멀티모달, Agentic Loop 비교 |
| ... | |
| → 전체 예시 디렉토리 보기 |
| Agentica | Claude Code | Codex CLI | |
|---|---|---|---|
| 모델 선택 | ✅ 다중 벤더 자유 전환 | Claude 모델만 지원 | OpenAI 모델만 지원 |
| ... |
analyze_image 내장 기능 추가. 공개된 from agentica import …는 변경되지 않으며, 서브 모듈은 영역별 패키지로 분류되었습니다; worktree가 더 이상 이동하며 잠금 처리되지 않습니다. 자세한 내용은 Release-v1.4.17를 참조하세요.search_session으로 검색합니다; 인터랙티브 CLI에 선택적 attach / 외부 hooks 추가 (기본값 비활성화); MCP는 2.x만 지원합니다. 자세한 내용은 Release-v1.4.16를 참조하세요.@agentica-ai/sdk와 Gateway Docker 이미지가 추가되었습니다; /export는 기본적으로 session JSONL을 출력합니다; apply_patch는 정확히 일치하는 경우에만 적용됩니다; CLI가 도구 출력 내의 [/path]를 Rich 마크로 인식하지 않습니다. 자세한 내용은 Release-v1.4.15를 참조하세요.apply_patch + write_file 수집 및 (read_file은 tail 지원); Worktree 기본적으로 저장소 내부로 진입; 시스템 스킬 패키지 내 로드; 데스크톱 버전 최초 실행 시 Python 런타임 자동 설치. 자세한 내용은 Release-v1.4.14 참고list_agents / send_message) 및 프로세스 레벨의 delegate(agentica --query --print 독립 실행, /ps /stop wait 관리) 추가, 프로세스 내 task 분업 명확화. 자세한 내용은 Release-v1.4.12 참고apply_patch 다중 파일 지원; CLI resume/상태 표시줄/압축 알림 강화; 프롬프트 및 grep/glob 스키마 축소; Learned Experiences 오염 및 write_todos 전체 재표시 문제 수정. 자세한 내용은 Release-v1.4.11 참고/rename 및 이름 기반 /resume 추가. 자세한 내용은 Release-v1.4.10 참고edit_file을 강제 거부 대신 팁(tip) 알림으로 변경; ask_user_question CLI 무한정 대기 문제 수정. 자세한 내용은 Release-v1.4.9 참고/cron 명령어 + daemon) 추가, 자체 관리 기능(/upgrade, /config set|env) 지원; 설정을 ~/.agentica/config.yaml로 통일. 자세한 내용은 Release-v1.4.7 참고--enable-diagnostics/--diagnostics-server) 제공; agentica doctor 지원; /goal을 통한 장기 작업 지원. 자세한 내용은 Release-v1.4.6 참고전체 사용 설명서: https://shibing624.github.io/agentica
Agentica가 도움이 되었다면, 별점(⭐ Star)을 눌러 더 많은 사람이 볼 수 있게 해주세요!
xuming624로 추가하고, 메모에 "llm"을 기재하여 기술 교류 그룹에 참여하세요.연구에서 Agentica의 자가 진화(Self-Evolution) 및 스킬 접근(Skill Access) 기능을 사용했다면, 다음을 인용해 주세요:
Shang, L., Xu, M., Sun, Y., Xia, T., Hu, L., Xu, L., & Zheng, N. (2026). When Self-Evolution Backfires: Pre-Commit Gating against Skill Contamination in LLM Agents. arXiv:2608.05810. https://arxiv.org/abs/2608.05810
BibTeX：