Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude, OpenAI, Ollama를 활용하여 Cursor의 코딩 어시스턴트 기능을 재현하는 Python 기반 AI 에이전트 프로젝트입니다. 코드 생성, 편집, 분석은 물론 파일 작업과 터미널 명령 실행 등 강력한 도구 세트를 제공합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기Claude, OpenAI, 그리고 로컬에서 호스팅되는 Ollama 모델을 사용하여 함수 호출 (Function Calling), 코드 생성 (Code Generation), 지능형 코딩 지원을 가능하게 하며 Cursor의 코딩 어시스턴트 기능을 재현하는 Python 기반 AI 에이전트입니다.
이 AI 에이전트 구현은 다음과 같은 포괄적인 기능 세트를 제공합니다:
모델 유연성 (Model Flexibility): Claude (Anthropic), OpenAI 모델 및 로컬에서 호스팅되는 Ollama 모델과 함께 작동합니다
코드 생성 (Code Generation): 자연어 설명을 기반으로 완전하고 기능적인 코드를 생성합니다
코드 편집 (Code Editing): 기존 코드 파일에 정밀한 편집을 수행합니다
코드 분석 (Code Analysis): 버그, 개선 사항 및 최적화를 위해 코드를 검토하고 분석합니다
함수 호출 (Function Calling): 사용자 요청에 따라 등록된 도구 및 함수를 호출합니다
대화 문맥 (Conversational Context): 일관된 상호작용을 위해 대화 기록을 유지합니다
프로젝트 인식 응답 (Project-Aware Responses): 질문에 답변할 때 프로젝트 문맥을 고려합니다
권한 시스템 (Permission System): 파일 작업 및 명령 실행에 대한 안전한 권한 처리를 제공합니다
로컬 모델 지원 (Local Model Support): Ollama를 통해 로컬에서 호스팅되는 오픈 소스 모델을 사용합니다
에이전트는 다음과 같은 포괄적인 도구 세트를 지원합니다:
파일 작업 (File Operations):
read_file: 유연한 라인 범위 제어를 통해 파일 내용을 읽습니다
edit_file: 명확한 지침을 통해 파일에 정밀한 편집을 수행합니다
{"1-5": "new content", "10-12": "more content"})delete_file: 파일 시스템에서 파일을 제거합니다
create_file: 지정된 내용으로 새 파일을 생성합니다
list_dir: 프로젝트 구조를 이해하기 위해 디렉토리 내용을 나열합니다
검색 기능 (Search Capabilities):
codebase_search: 관련 코드 스니펫을 찾기 위한 코드베이스의 의미론적 검색 (Semantic search)
grep_search: 파일 내에서 정규 표현식 (Regex) 기반 텍스트 검색을 수행합니다
file_search: 이름으로 파일을 찾는 퍼지 검색 (Fuzzy search)
web_search: 최신 정보를 위해 웹을 검색합니다
trend_search: 트렌드 주제 및 최신 개발 사항을 검색합니다
Image Analysis (이미지 분석):
query_images: LLM의 비전 (Vision) 기능을 사용하여 이미지를 분석하고 설명합니다
System Operations (시스템 운영):
run_terminal_cmd: 사용자의 승인 하에 터미널 명령어를 실행합니다
모든 도구는 실제 기능과 함께 구현되어 있으며, 필요에 따라 커스텀 도구로 확장할 수 있습니다.
설치 (Installation)
빠른 시작 (Quick Start)
사용 예시 (Usage Examples)
프로젝트 구조 (Project Structure)
설정 (Configuration)
권한 시스템 (Permission System)
기여하기 (Contributing)
API 문서 (API Documentation)
고급 사용법 (Advanced Usage)
제한 사항 및 고려 사항 (Limitations and Considerations)
로드맵 (Roadmap)
라이선스 (License)
감사의 글 (Acknowledgements)
Python 3.8 이상
Anthropic 및/또는 OpenAI의 API 키
pip install cursor-agent-tools
git clone https://github.com/civai-technologies/cursor-agent.git
cd cursor-agent
pip install -e . # 개발 모드로 설치
...
프로젝트 루트에 .env 파일을 생성하세요 (.env.example 파일을 복사하세요):
# 환경 (local, development, production)
ENVIRONMENT=local
# OpenAI 설정
...
import asyncio
from cursor_agent_tools import create_agent
async def main():
...
import asyncio
from cursor_agent_tools import create_agent
# Claude 사용
...
import asyncio
from cursor_agent_tools import create_agent
async def main():
...
에이전트는 Ollama에서 사용 가능한 모든 모델을 지원합니다. 인기 있는 옵션은 다음과 같습니다:
ollama-llama3
ollama-llama3.1
ollama-mistral
ollama-gemma3
ollama-deepseek-r1
ollama-phi4
ollama-qwen2.5
사용 가능한 전체 모델 목록은 Ollama Library를 참조하세요.
도구 호출 (Tool calling) 및 멀티모달 (Multimodal) 지원은 특정 모델의 역량에 따라 달라질 수 있음에 유의하십시오.
import asyncio
from cursor_agent_tools import create_agent
async def main():
...
이 예제는 커스텀 페르소나(personality)와 행동 지침을 가진 특화된 코딩 튜터 에이전트(coding tutor agent)를 생성합니다. 적절한 시스템 프롬프트(system prompts)를 작성함으로써 다음과 같이 다양한 도메인을 위한 커스텀 에이전트를 유사하게 생성할 수 있습니다:
from cursor_agent_tools import run_agent_interactive
import asyncio
async def main():
...
대화형 모드(interactive mode)는 다음과 같은 경우를 제외하고는 사용자 상호작용 없이 자동으로 계속 진행되도록 설계되었습니다:
--auto 플래그가 사용되어 각 단계 후에 사용자 입력을 요청하는 경우사용자 입력이 요청되거나 제공될 때, 시스템은 다음과 같은 방식으로 이 입력을 대화 흐름에 지능적으로 통합합니다:
대화형 모드에는 에이전트가 명시적으로 사용자 입력을 요청하는 시점을 감지하는 기능이 내장되어 있습니다. 에이전트의 응답에 다음과 같은 문구가 포함된 경우:
시스템은 자동 계속(auto-continue) 모드에서도 자동으로 일시 중지하고 사용자의 입력을 기다립니다. 이를 통해 에이전트가 진정으로 명확한 설명이나 사용자의 결정을 필요로 할 때 대화가 적절히 일시 중지되도록 보장합니다.
안전성을 확보하고 자동화가 통제 불능 상태로 실행되는 것을 방지하기 위해, 에이전트는 단일 에이전트 응답 (agent response)을 처리하는 동안 수행된 도구 호출 (tool calls)의 총 횟수를 추적합니다. 이 횟수가 특정 임계값(기본값: 5)에 도달하면, 에이전트는 추가적인 변경을 수행하기 전에 사용자 확인을 요청합니다. 이는 다음과 같은 보호 장치 역할을 합니다:
도구 호출 추적 방식에 관한 중요한 세부 사항:
한도에 도달하면 다음과 같은 메시지가 표시됩니다:
The agent has made 5 tool calls in this iteration.
Would you like to continue allowing the agent to make more changes?
Continue? (y/n):
승인할 경우, 에이전트는 다음과 같이 동작합니다:
거부할 경우, 에이전트는 다음과 같이 동작합니다:
이러한 적응형 한도 (adaptive limit)는 에이전트가 사용자의 승인 없이 너무 많은 변경을 수행하지 않도록 보장하는 동시에, 복잡한 작업이 효율적으로 완료될 수 있도록 합니다.
from cursor_agent_tools import create_agent
agent = create_agent(model='claude-3-5-sonnet-latest')
user_info = {
...
from cursor_agent_tools import create_agent
agent = create_agent(model='claude-3-5-sonnet-latest')
def custom_tool(param1, param2):
...
더 많은 예시는 examples 디렉토리를 확인하세요.
cursor-agent/
├── agent/ # 핵심 에이전트 구현
│ ├── init.py # 패키지 내보내기
...
| 변수 | 설명 | 기본값 |
|---|---|---|
ANTHROPIC_API_KEY | Claude용 Anthropic API 키 | None |
ANTHROPIC_API_MODEL | 사용할 Claude 모델 | claude-3-5-sonnet-latest |
ANTHROPIC_TEMPERATURE | Claude 온도 설정 | 0.0 |
OPENAI_API_KEY | OpenAI API 키 | None |
OPENAI_API_MODEL | 사용할 OpenAI 모델 | gpt-4o |
OPENAI_TEMPERATURE | OpenAI 온도 설정 | 0.0 |
ENVIRONMENT | 환경 모드 | local |
에이전트를 생성할 때, 그 동작을 사용자 정의할 수 있습니다:
from cursor_agent_tools import create_agent
from cursor_agent_tools.permissions import PermissionOptions
# 권한 옵션 생성
...
CursorAgent는 시스템 작업을 안전하게 처리하기 위한 강력한 권한 시스템을 포함합니다:
기본적으로 보안: 모든 파일 수정 및 명령어 실행에는 권한이 필요합니다.YOLO 모드: 작업에 대한 자동 승인을 위한 선택적 모드 (설정 가능한 규칙 사용)명령어 필터링: 자동으로 실행될 수 있는 명령어를 제어하는 허용 목록/금지 목록파일 삭제 보호: 파일 삭제 작업에 대한 특별 보호사용자 정의 UI: 다양한 환경에 적응할 수 있는 유연한 권한 요청 인터페이스
from cursor_agent_tools import create_agent
from cursor_agent_tools.permissions import PermissionOptions
# 기본 권한을 가진 에이전트 생성 (모든 작업에 확인 필요)
...
권한 시스템은 다양한 UI 환경에 맞게 조정될 수 있습니다:
from cursor_agent_tools.permissions import PermissionOptions, PermissionRequest, PermissionStatus
# GUI 애플리케이션을 위한 사용자 정의 권한 핸들러 생성
def gui_permission_handler(request: PermissionRequest) -> PermissionStatus:
...
권한 시스템에 대한 포괄적인 문서는 permissions_guide.md를 참조하세요.
기여 환영합니다! 이 프로젝트에 기여하는 방법에 대한 자세한 내용은 CONTRIBUTING.md를 참고해 주세요.
저장소를 Fork 및 clone 하세요
가상 환경 (virtual environment)을 생성하세요
개발 의존성 (development dependencies)을 설치하세요:
pip install -e ".[dev]"
.env 파일에 API 키를 설정하세요
기능 추가 또는 버그 수정을 위한 Pull Request를 제출하세요
린팅 (linting)을 위해 flake8을 사용합니다. 일관된 스타일을 보장하기 위해 코드가 다음 사항을 준수하는지 확인해 주세요:
flake8 cursor_agent_tools 명령어로 flake8 린팅 검사를 통과해야 합니다.
공백 (whitespace) 문제가 없어야 합니다. 포함된 스크립트를 사용하여 일반적인 공백 문제를 수정할 수 있습니다:
이 스크립트는 cursor_agent_tools 디렉토리 내의 trailing whitespace (W291) 및 공백이 포함된 빈 줄 (W293)을 자동으로 수정합니다.
python fix_whitespace_errors.py
# 팩토리 함수 (factory function) 임포트
from cursor_agent_tools import create_agent
def create_agent(
...
# 필요한 타입 (types) 임포트
from typing import Dict, List, Callable, Optional
from cursor_agent_tools import BaseAgent
...
전체 API 문서는 소스 코드의 docstring을 참조하세요.
도구 (Tools)는 에이전트 (agent)에 등록된 Python 함수입니다. cursor-agent 라이브러리는 에이전트의 능력을 향상시키기 위해 다양한 유형의 도구를 지원합니다:
from cursor_agent_tools import create_agent
agent = create_agent(model='claude-3-5-sonnet-latest')
def database_query(query: str, connection_string: str):
...
from cursor_agent_tools import create_agent
import requests
agent = create_agent(model='claude-3-5-sonnet-latest')
...
from cursor_agent_tools import create_agent
import pandas as pd
import json
...
에이전트는 줄 번호 (line numbers)를 사용하여 파일의 정밀한 편집을 지원합니다:
import json
from cursor_agent_tools import create_agent
async def main():
...
이 방식은 다음과 같은 몇 가지 장점이 있습니다:
더 많은 예시는 line_based_edit_example.py를 확인하세요.
from cursor_agent_tools import create_agent
agent = create_agent(model='claude-3-5-sonnet-latest')
user_info = {
...
API 키 보안 (API Key Security): API 키를 안전하게 보관하고 절대 저장소(repositories)에 커밋하지 마세요.
컨텍스트 윈도우 (Context Windows): 모델은 처리할 수 있는 코드의 양을 제한하는 토큰 제한(token limits)을 가지고 있습니다.
도구 실행 (Tool Execution): 함수 호출 (Function calling)은 시스템에서 코드를 실행하므로 적절한 보안을 구현하세요.
속도 제한 (Rate Limits): API에는 사용을 제한할 수 있는 속도 제한 (rate limits)이 있습니다.
비용 (Costs): API 사용 시 토큰 사용량에 따라 비용이 발생합니다.
제약 사항 및 해결 방법에 대한 자세한 목록은 constraints.md 파일을 참조하세요.
이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.
Femi Amoo (Nifemi Alpine)
CIVAI TECHNOLOGIES 창립자