civai-technologies/cursor-agent

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: 명확한 지침을 통해 파일에 정밀한 편집을 수행합니다

• 전체 파일 교체를 지원합니다
• JSON 딕셔너리를 사용한 라인 기반 편집을 지원합니다 (예: {"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

• Meta의 Llama 3 모델

ollama-llama3.1

• Meta의 Llama 3.1 모델

ollama-mistral

• Mistral AI의 모델

ollama-gemma3

• Google의 Gemma 모델

ollama-deepseek-r1

• DeepSeek의 추론 (Reasoning) 모델

ollama-phi4

• Microsoft의 Phi 모델

ollama-qwen2.5

• Qwen의 최신 모델

사용 가능한 전체 모델 목록은 Ollama Library를 참조하세요.

도구 호출 (Tool calling) 및 멀티모달 (Multimodal) 지원은 특정 모델의 역량에 따라 달라질 수 있음에 유의하십시오.

import asyncio
from cursor_agent_tools import create_agent
async def main():
...

이 예제는 커스텀 페르소나(personality)와 행동 지침을 가진 특화된 코딩 튜터 에이전트(coding tutor agent)를 생성합니다. 적절한 시스템 프롬프트(system prompts)를 작성함으로써 다음과 같이 다양한 도메인을 위한 커스텀 에이전트를 유사하게 생성할 수 있습니다:

• 데이터 분석 어시스턴트 (pandas/numpy에 집중)
• DevOps 자동화 전문가 (CI/CD 및 배포 스크립트용)
• 문서 작성자 (코드로부터 잘 구조화된 문서를 생성)
• 보안 코드 리뷰어 (코드 내 취약점 식별)
• 알고리즘 최적화 전문가 (성능 개선)

from cursor_agent_tools import run_agent_interactive
import asyncio
async def main():
...

대화형 모드(interactive mode)는 다음과 같은 경우를 제외하고는 사용자 상호작용 없이 자동으로 계속 진행되도록 설계되었습니다:

• AI가 사용자에게 명시적으로 추가 정보를 요청하는 경우
• 사용자의 결정이 필요한 오류가 발생하는 경우
• --auto 플래그가 사용되어 각 단계 후에 사용자 입력을 요청하는 경우
• 최대 도구 호출 제한(maximum tool call limit)에 도달하여 계속 진행하기 위한 사용자 확인을 요청하는 경우

사용자 입력이 요청되거나 제공될 때, 시스템은 다음과 같은 방식으로 이 입력을 대화 흐름에 지능적으로 통합합니다:

• AI 모델 자체를 사용하여 문맥에 적합한 후속 프롬프트(continuation prompt)를 생성
• 사용자의 입력을 기존 대화 기록(conversation history)과 매끄럽게 통합
• 구현 프로세스의 자연스러운 흐름 유지

대화형 모드에는 에이전트가 명시적으로 사용자 입력을 요청하는 시점을 감지하는 기능이 내장되어 있습니다. 에이전트의 응답에 다음과 같은 문구가 포함된 경우:

• "...에 대한 추가 정보가 필요합니다"
• "...에 대해 더 자세한 내용을 제공해 주시겠습니까?"
• "...에 대한 귀하의 선호도를 알려주세요"
• "...에 대해 제가 무엇을 하기를 원하십니까?"

시스템은 자동 계속(auto-continue) 모드에서도 자동으로 일시 중지하고 사용자의 입력을 기다립니다. 이를 통해 에이전트가 진정으로 명확한 설명이나 사용자의 결정을 필요로 할 때 대화가 적절히 일시 중지되도록 보장합니다.

안전성을 확보하고 자동화가 통제 불능 상태로 실행되는 것을 방지하기 위해, 에이전트는 단일 에이전트 응답 (agent response)을 처리하는 동안 수행된 도구 호출 (tool calls)의 총 횟수를 추적합니다. 이 횟수가 특정 임계값(기본값: 5)에 도달하면, 에이전트는 추가적인 변경을 수행하기 전에 사용자 확인을 요청합니다. 이는 다음과 같은 보호 장치 역할을 합니다:

• 코드베이스에 의도치 않은 광범위한 변경이 발생하는 것을 방지
• 복잡한 작업에 대한 가시성 제공
• 계속 진행하기 전에 진행 상황을 검토할 수 있도록 함
• 필요한 경우 에이전트의 방향을 재설정할 기회 제공

도구 호출 추적 방식에 관한 중요한 세부 사항:

• 카운터는 하나의 논리적 반복 (logical iteration, 즉 하나의 에이전트 응답) 내의 모든 도구 호출을 추적합니다.
• 카운터는 새로운 사용자 입력이 제공되거나 새로운 쿼리가 시작될 때까지 초기화되지 않습니다 (NOT reset).
• 에이전트가 동일한 반복을 계속 수행하는 동안에도 카운터는 유지됩니다.

한도에 도달하면 다음과 같은 메시지가 표시됩니다:

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):

승인할 경우, 에이전트는 다음과 같이 동작합니다:

• 현재 반복 내에서 더 많은 도구 호출을 계속 수행합니다.
• 해당 반복에 대해 한도를 5만큼 늘립니다.
• 새로운 한도에 도달하면 다시 확인을 요청합니다.
• 도구 호출의 총 횟수를 계속 추적합니다 (카운터는 초기화되지 않습니다).

거부할 경우, 에이전트는 다음과 같이 동작합니다:

• 해당 반복을 위한 추가적인 도구 호출을 중단합니다.
• 이미 수행된 변경 사항을 가지고 현재 반복을 완료합니다.
• 준비가 되면 다음 반복으로 넘어갑니다.

이러한 적응형 한도 (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 파일을 참조하세요.

• 스트리밍 응답 (Streaming responses)
• 더 많은 모델 제품군 지원 (예: Gemini, Llama 등)
• 웹 인터페이스 (Web interface)
• 인증을 포함한 다중 사용자 지원 (Multi-user support with authentication)
• 벡터 기반 코드베이스 검색 (Vector-based codebase search)
• 테스트 도구 통합 (Testing tools integration)
• 포괄적인 데모 스위트 (Comprehensive demo suite)
• 문서 웹사이트 (Documentation website)

이 프로젝트는 MIT 라이선스(MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

Femi Amoo (Nifemi Alpine)

CIVAI TECHNOLOGIES 창립자