aisuite 기반의 데스크톱 AI 에이전트

aisuite를 기반으로 구축된, 당신의 데스크톱에서 실행되는 AI 에이전트입니다. OpenCoworker는 단순한 채팅을 넘어 심층적인 연구를 수행하고 당신의 컴퓨터에서 작업을 대신 수행할 수 있는 데스크톱 AI 에이전트입니다. (권한 허용 시) 문맥 파악을 위해 파일을 읽을 수 있고, 메시지(Slack, 이메일 등)를 읽거나 보낼 수 있으며, PDF 보고서, 문서, 스프레드시트와 같은 실제 결과물을 생성할 수 있습니다. 또한 일일 뉴스 요약 제공과 같은 예약된 자동화(scheduled automations)도 지원합니다.

사용자의 API 키(OpenAI, Anthropic, Google)를 직접 가져오거나, Ollama를 사용하여 완전히 로컬에서 실행해야 합니다. 데이터는 사용자의 기기에 그대로 유지됩니다.

⬇ macOS용 다운로드
macOS 13+ (Apple Silicon)

⬇ Windows용 다운로드
Windows 10/11 (x64) ·

빠른 시작(Quickstart): — 설치, 모델 연결, 첫 작업, 자동화.
소스는 이 저장소의 platform/ 아래에 있습니다.

— aisuite를 사용하여 자신만의 에이전트 하네스(agent harness)를 구축하기 위한 작동 참조 모델입니다.

aisuite는 LLM(Large Language Models) 구축을 위한 경량 Python 라이브러리로, 두 개의 계층으로 구성됩니다: 제공자 전반에 걸친 통합된 Chat Completions API (채팅 완료 API), 그리고 그 위에 도구(tools)와 툴킷(toolkits)을 얹은 **Agents API (에이전트 API)**입니다. 이 저장소는 또한 aisuite를 사용하여 구축된 데스크톱 AI 동료인 OpenCoworker의 홈이기도 합니다:

┌───────────────────────────────────────────────┐
│ OpenCoworker │ 일상적인 작업을 수행하기 위한 에이전트 하네스
├───────────────────────────────────────────────┤
...

Chat Completions API (채팅 완료 API) — OpenAI, Anthropic, Google, Mistral, Hugging Face, AWS, Cohere, Ollama, OpenRouter 등을 위한 통합된 OpenAI 스타일의 인터페이스입니다. 문자열 하나만 변경하여 제공자를 교체할 수 있습니다.

Agents API (에이전트 API) · Toolkits (툴킷) · MCP — 모델에 실제 Python 함수를 도구로 제공하고, 멀티 턴 루프(multi-turn loops)를 실행하며, 준비된 툴킷(파일, git, shell) 또는 모든 MCP 서버를 연결하고, 도구 정책(tool policies)으로 이 모든 것을 관리합니다.

OpenCoworker — aisuite를 사용하여 구축된 데스크톱 AI 동료로, 일상적인 작업을 위한 앱 형태로 제공됩니다.

기본 패키지를 설치하거나, 사용할 계획인 제공자의 SDK를 포함하세요:

pip install aisuite # 기본 패키지, 제공자 SDK 미포함
pip install 'aisuite[anthropic]' # 특정 제공자의 SDK 포함
pip install 'aisuite[all]' # 모든 제공자의 SDK 포함

호출하려는 제공자들을 위한 API 키도 필요합니다. Chat Completions 퀵스타트(quickstart)에서 키 설정 및 첫 호출 방법을 다룹니다.

설치 프로그램을 다운로드하고 본인의 API 키를 사용하세요 (또는 Ollama를 사용하여 로컬 모델을 실행하세요):

⬇ macOS (Apple Silicon) · ⬇ Windows 10/11 (x64) · OpenCoworker 퀵스타트

Chat API는 모델 상호작용을 위한 고수준 추상화 (high-level abstraction)를 제공합니다. 이는 모든 핵심 파라미터 (temperature, max_tokens, tools 등)를 제공자 중립적인 (provider-agnostic) 방식으로 지원하며, 요청 및 응답 구조를 표준화하여 사용자가 SDK의 차이점보다는 로직에 집중할 수 있도록 합니다.

모델 이름은 <provider>:<model-name> 형식을 사용합니다. aisuite는 적절한 파라미터와 함께 호출을 올바른 제공자로 라우팅(route)합니다:

import aisuite as ai
client = ai.Client()
models = ["openai:gpt-4o", "anthropic:claude-3-5-sonnet-20240620"]
...

→ 퀵스타트 (Quickstart): docs/chat-completions-quickstart.md — 설치, 키 설정, 로컬 모델 및 기타 예제.

aisuite는 도구 호출 (tool calling)을 한 줄의 코드로 만들어 줍니다. 일반적인 Python 함수를 전달하면 aisuite가 스키마 (schema)를 생성하고, 호출을 실행하며, 결과를 모델에 다시 전달합니다.

def will_it_rain(location: str, time_of_day: str):
"""오늘 특정 시간과 장소에 비가 올지 확인합니다.
Args:
...

max_turns가 설정되면, aisuite는 메시지를 보내고, 모델이 요청하는 모든 도구 호출을 실행하며, 결과를 모델에 반환하고, 대화가 완료될 때까지 이 과정을 반복합니다. 대화를 계속하고 싶다면 response.choices[0].intermediate_messages가 전체 도구 상호작용 이력을 담고 있습니다.

완전한 수동 제어를 선호하시나요? max_turns를 생략하고 OpenAI 형식의 JSON 도구 명세 (tool specs)를 전달하세요. aisuite는 모델의 도구 호출 요청을 반환하며, 사용자가 직접 루프를 실행하게 됩니다. 두 가지 스타일 모두에 대해서는 examples/tool_calling_abstraction.ipynb를 참조하세요.

더 오래 지속되는 구조화된 작업을 위해서는 일급 객체인 Agents API가 있습니다. 에이전트를 한 번 선언하고, Runner로 실행하며, 파일, git, 쉘을 위한 사전 구축된 샌드박스 도구 모음인 **툴킷 (toolkits)**을 연결할 수 있습니다:

import aisuite as ai
from aisuite import Agent, Runner
agent = Agent(
...

Agents API는 또한 프로덕션 하네스 (production harness)에 필요한 구성 요소들을 제공합니다:

도구 정책 (Tool policies)—RequireApprovalPolicy, 허용/차단 목록, 또는 어떤 도구 호출을 실행할지 결정하는 사용자 정의 호출 가능 객체(callable)를 제공합니다. 상태 저장소 (State stores)— 실행 내용을 유지하고 재개하며 (인메모리, 파일, 또는 Postgres), 프로세스 간에 대화를 지속합니다. 아티팩트 및 트레이싱 (Artifacts & tracing)— 에이전트가 생성한 결과물과 그 과정에서 거친 모든 단계를 캡처합니다.

aisuite는 Model Context Protocol (MCP)을 네이티브로 지원하므로, 보일러플레이트(boilerplate) 없이도 어떤 MCP 서버의 도구든 모델에 전달할 수 있습니다 (pip install 'aisuite[mcp]'):

client = ai.Client()
response = client.chat.completions.create(
model="openai:gpt-4o",
...

재사용 가능한 연결, 보안 필터, 도구 접두사(prefixing)를 위해서는 명시적인 MCPClient를 사용하세요.

→ 퀵스타트 (Quickstart): docs/agents-quickstart.md — 수동 도구 처리, 전체 Agents API, 정책, 상태 저장소, 그리고 MCP에 대해 심도 있게 다룹니다.

가벼운 어댑터 (adapter)를 구현함으로써 새로운 프로바이더 (providers)를 추가할 수 있습니다. 시스템은 발견을 위해 다음과 같은 명명 규칙 (naming convention)을 사용합니다:

요소	규칙
모듈 파일	<provider>_provider.py
클래스 이름	<Provider>Provider (대문자 시작)

예시:

# providers/openai_provider.py
class OpenaiProvider(BaseProvider):
...

이 규칙은 일관성을 보장하고 새로운 통합 기능의 자동 로딩을 가능하게 합니다.

기여(Contributions)를 환영합니다. 기여 가이드 (Contributing Guide)를 검토하고 토론을 위해 Discord에 참여해 주세요.

MIT License에 따라 배포됩니다 — 상업적 및 비상업적 용도로 자유롭게 사용할 수 있습니다.