자주 묻는 질문

AgentOS는 프로덕션 AI 에이전트를 구축하기 위한 오픈소스 TypeScript 런타임으로, Frame.dev가 개발했습니다. 멀티 에이전트 오케스트레이션, 인지 메모리, 멀티모달 RAG, 선택형 안전 가드레일(PII 편집, 콘텐츠 모더레이션, 그라운딩 검증), 음성 파이프라인, 37개 채널 어댑터, 13개 LLM 프로바이더 통합을 제공합니다. AgentOS는 또한 AI 네이티브 게이밍 플랫폼인 Wilds.ai 뒤의 AI 시스템도 구동합니다. 셀프 호스팅 가능하며 무료입니다.

네. 런타임, 큐레이션된 확장, 가드레일 팩, 큐레이션된 스킬은 모두 Apache 2.0 라이선스입니다. 이 라이선스에 따라 AgentOS를 상업적으로 사용하고 수정하고 재배포할 수 있습니다.

AgentOS는 13개 LLM 프로바이더를 지원합니다: OpenAI, Anthropic, Google Gemini, Groq, Together AI, Mistral, xAI (Grok), OpenRouter, Requesty, LiteLLM, Ollama, Claude Code CLI, Gemini CLI. 프로바이더 폴백 체인으로 자동 페일오버가 가능합니다.

AgentOS는 전부 TypeScript로 작성되었으며 Node.js에서 실행됩니다. npm 패키지는 @framers/agentos 입니다. 모든 TypeScript 또는 JavaScript 프로젝트와 함께 작동합니다.

AgentOS는 TypeScript 네이티브이며(Python이 아닙니다), Ebbinghaus 감쇠 곡선과 HEXACO 성격 모델링을 갖춘 인지 메모리를 포함합니다. PII 편집, 콘텐츠 모더레이션, 그라운딩 검증을 위한 선택형 가드레일 팩을 제공하고, 37개 채널 어댑터(Discord, Telegram, Slack, 이메일 등)를 제공하며, 그래프 기반 에이전트 DAG를 포함한 6가지 오케스트레이션 전략을 지원합니다. 또한 88개의 큐레이션된 스킬과 계층별 토큰 예산 안에서 관련 도구와 스킬만 컨텍스트에 넣는 능력 발견 엔진을 함께 제공합니다.

Paracosm (https://paracosm.agentos.sh)은 AgentOS 위에 구축된 구조화된 월드 모델 시뮬레이션 엔진입니다. JSON ScenarioPackage와 HEXACO 리더 프로파일을 시드 기반 결정론적 커널을 중심으로 한 턴 루프로 컴파일하며, AgentOS 에이전트들이 이벤트를 제안하고, 런타임에 새로운 JavaScript 도구를 단조해내며(AgentOS가 node:vm에서 10초 제한으로 실행합니다), 분기하고 재생할 수 있는 반사실 산출물을 생성합니다. 세 가지 모드가 하나의 스키마를 공유합니다. 턴 루프 문명 시뮬레이션(Mars Genesis가 대표 예시), 배치 트라젝토리 디지털 트윈, 그리고 배치 포인트 몬테카를로 예측. Apache 2.0 라이선스로 오픈소스, npm install paracosm. 라이브 데모: https://paracosm.agentos.sh/sim. 소스: https://github.com/framerslab/paracosm. 긴 런치 포스트(왜 만들었는지, wilds.ai 볼트 이야기, 엔진 참조): https://agentos.sh/blog/paracosm-launch.

Wilds.ai (https://wilds.ai)는 AgentOS와 Paracosm 위에 구축된 AI 네이티브 게임 플랫폼입니다. 영속적인 인지 메모리와 HEXACO 성격 특성을 가진 AI 캐릭터들이 공유된 월드 모델 안에 거주하며, 근거 있는 LLM-as-judge 이벤트를 통해 서로 분기됩니다. 플레이어는 기존 월드에 들어가거나, 분기하거나, 브라우저에서 새 월드를 컴파일할 수 있습니다. Wilds.ai는 AgentOS + Paracosm 스택의 정식 프로덕션 배포이며, 두 프로젝트 모두의 공식 커뮤니티 및 지원 채널(https://wilds.ai/discord)입니다.

Wunderland (https://wunderland.sh)는 활발히 개발 중인 자매 프로젝트로, AgentOS 확장 및 스킬 레지스트리 위에 batteries-included CLI와 데몬을 패키징합니다. 60개 명령 CLI(setup, chat, rag, agency, workflows, evaluate, provenance, knowledge, marketplace 등), 5단계 보안 모델(dangerous / permissive / balanced / strict / paranoid), 9개 에이전트 프리셋, 단계적 HITL 권한 부여, 그리고 AgentOS 문서에 기재된 것과 동일한 인지 메모리 및 그래프 기반 RAG 아키텍처를 함께 제공합니다. 애플리케이션에 임베드할 TypeScript SDK가 필요하면 @framers/agentos를, pnpm add -g wunderland로 설치하고 마법사로 구성할 수 있는 글로벌 CLI를 원한다면 Wunderland를 사용하세요. 소스는 github.com/jddunn/wunderland(0.71.0부터 Apache 2.0). 프리뷰 릴리스이므로 API와 CLI 표면이 아직 변경될 수 있습니다. 시작 가이드: https://docs.agentos.sh/wunderland.

GMI는 Generalized Mind Instance의 약자입니다. AgentOS 런타임이 세션마다 생성하는 에이전트로, 해당 세션의 페르소나(HEXACO 특성), 대화 기록, 무드, 추론 트레이스를 보관하고, 검색, 프롬프트 조립, 모델 호출, 도구 호출을 거쳐 각 턴을 실행하며, 세션 간에 유지되는 인지 메모리를 부여받을 수 있습니다. 경량 헬퍼 agent()는 모델을 직접 호출하며 runtime: 'gmi'를 전달하지 않으면 GMI를 생성하지 않습니다. gmi()와 전체 런타임(AgentOS.processRequest)은 GMI를 생성합니다.

HEXACO는 심리학 연구(Ashton & Lee, 2007)에서 비롯된 6요인 성격 모델입니다. 6가지 차원은 정직성-겸손성, 정서성, 외향성, 친화성, 성실성, 경험에 대한 개방성입니다. AgentOS에서 HEXACO 특성은 에이전트가 소통하고 기억하는 방식을 형성합니다. agent()는 0.65를 넘거나 0.35 미만인 특성을 행동 지시문으로 시스템 프롬프트에 씁니다. 인지 메모리에서는 정서성이 높을수록 회상할 때 기억이 다시 쓰이는 정도(재공고화)가 커지고, 성실성이 높을수록 경쟁하는 기억에 대한 검색 유도 망각이 강해집니다.

AgentOS 인지 메모리는 인지과학 연구의 8가지 메커니즘을 구현합니다: 재공고화, 검색 유도 망각, 비자발적 회상, 앎의 느낌, 시간적 요지 추출, 스키마 부호화, 출처 신뢰도 감쇠, 정서 조절. 기억은 Ebbinghaus 망각 곡선(Ebbinghaus, 1885)을 따라 시간이 지나면서 감쇠하며, 검색에 성공할 때마다 기억이 더 안정됩니다(간격 반복과 같은 효과). 작업 메모리는 Baddeley의 다중 구성 요소 모델(Baddeley, 2000)을 따르며 기본 7개 슬롯을 가집니다. 개방성이 높으면 하나가 늘고 성실성이 높으면 하나가 줄며, 슬롯 수는 5~9개 범위에 머뭅니다. 새 기억은 기본적으로 일화 기억으로 저장되고 작업 메모리 슬롯 하나를 차지합니다. 슬롯이 가득 차면 활성도가 가장 낮은 슬롯이 비워지고, 그 기억은 저장된 채로 남습니다. 이후 공고화가 오래되고 자주 검색된 일화 기억을 의미 기억으로 바꿉니다.

AgentOS에는 선택형 가드레일 팩이 6개 있습니다: PII 편집(이름, 이메일, 전화번호, SSN 등), 유해성·위협·NSFW 콘텐츠를 감지하는 ML 분류기, 생성된 코드의 위험한 패턴을 찾는 정적 분석, 소스 문서 대비 그라운딩 검증, 에이전트를 과제에 유지하는 토픽성 강제, 그리고 정책에 어긋나는 출력을 다시 쓰거나 차단하는 콘텐츠 정책 리라이터입니다. 각 팩은 AgentOS 런타임에서 활성화하는 확장입니다. 분류기 팩은 로컬 모델을 불러올 수 없을 때만 프롬프트 인젝션 점수를 매깁니다. 알려진 인젝션 문구에는 내장된 문구 목록 가드레일을 사용하세요.

능력 발견 엔진은 시맨틱 검색으로 도구와 스킬을 찾아, 각각 엄격한 토큰 예산을 가진 3개 계층으로 프롬프트에 넣습니다. Tier 0은 카테고리 요약을 항상 컨텍스트에 둡니다(기본 200 토큰). Tier 1은 해당 턴의 상위 5개 시맨틱 매치를 추가합니다(800 토큰). Tier 2는 상위 2개 매치의 전체 스키마 또는 SKILL.md 텍스트를 추가합니다(2,000 토큰). discover_capabilities라는 메타 도구로 에이전트가 런타임에 사용 가능한 도구를 조회할 수 있습니다.

QueryRouter는 각 쿼리를 4단계 중 하나로 분류하고 그에 맞춰 검색합니다: T0은 검색 없이 대화에서 답하고, T1은 한 번의 벡터 검색을 실행하며(임베딩 프로바이더가 설정되지 않았으면 키워드 검색), T2는 청크 15개를 가져와 그래프 확장으로 관련 청크를 더하고 합친 결과를 상위 5개로 재순위화하며, T3는 쿼리를 문장 단위로 최대 5개의 하위 쿼리로 나누어 각각 청크 10개를 가져오고, 그래프 확장으로 관련 청크를 더한 뒤 합친 결과를 상위 10개로 재순위화하며, 심층 리서치가 켜져 있으면(기본값은 SERPER_API_KEY가 설정된 경우) 심층 리서치를 실행해 그 결과를 합칩니다. 그런 다음 검색한 내용으로 답하고 출처 인용과 함께 반환합니다.

적응형 지능은 AgentOS 에이전트가 재학습 없이 행동을 조정하는 방식입니다. 다섯 가지 메커니즘이 함께 작동합니다: (1) 턴별 프롬프트 조립: GMI의 PromptEngine이 페르소나, 기분, 대화 기록, 검색된 기억, 사용 가능한 도구로 매 턴 시스템 프롬프트를 만듭니다. (2) 자기 평가: 자기 개선을 켜면 self_evaluate 도구가 에이전트 자신의 답변을 채점하고, 세션의 temperature나 장황함을 바꾸거나 adapt_personality로 특성을 조정할 수 있습니다. (3) 성격으로 조절되는 기억: HEXACO 특성이 기억 메커니즘을 조정합니다. 개방성이 높을수록 비자발적 회상이 일어날 가능성이 커지고, 성실성이 높을수록 경쟁하는 기억에 대한 검색 유도 망각이 강해집니다. (4) 기억 공고화: 공고화 과정은 감쇠한 기억을 정리하고, 중복을 병합하고, 오래되고 자주 검색된 일화 기억을 의미 기억으로 바꾸며, LLM이 설정되어 있으면 클러스터에서 통찰 기억을 도출합니다. (5) QueryRouter 단계: 검색 깊이는 쿼리에 따라 정해지며, 대화에 이미 답이 있으면 검색하지 않고 가장 어려운 쿼리에는 전체 코퍼스에 걸친 심층 리서치를 수행합니다.

창발적 행동은 명시적으로 프로그래밍된 것이 아니라 에이전트가 런타임에 갖추게 되는 능력입니다. AgentOS는 다섯 가지 형태를 지원합니다: (1) 런타임 도구 단조: AgentOS 런타임에서 emergent: true로 설정하면 에이전트가 forge_tool로 JavaScript 새 도구를 작성합니다. EmergentCapabilityEngine은 각 도구를 시간 제한과 함께 node:vm에서 실행하고, 도구가 등록되기 전에 LLM 심판이 코드와 테스트 실행을 검토합니다. (2) 스스로 조정하는 성격: adapt_personality는 실행 중인 에이전트의 HEXACO 특성을 정해진 범위 안에서 움직입니다. persistWithDecay와 뮤테이션 스토어를 사용하면 각 변경이 기록되고, 저장된 기록은 에이전트가 적응하는 날에 하루 최대 한 번 강도가 줄어듭니다. (3) 동적 스킬 관리: 에이전트는 manage_skills로 런타임에 스킬을 켜거나 끄며 행동 레퍼토리를 과제에 맞춥니다. (4) 조합 가능한 워크플로 생성: 에이전트는 create_workflow로 등록된 도구를 다단계 파이프라인으로 조합해 기존 구성 요소에서 새로운 능력을 만듭니다. (5) 단계별 도구 승격: 단조된 도구는 session 단계에서 시작합니다. 5회 이상 사용되고 성공률이 0.8 이상이며 두 LLM 검토자가 승인하면 agent 단계로 이동합니다. 호스트는 EmergentToolRegistry.promote()로 도구를 shared 단계로 승격할 수 있습니다.

네. AgentOS는 두 가지 상호 보완적인 LLM-as-judge 메커니즘을 제공합니다. 에이전시 수준에서, hitl.llmJudge()는 결정을 LLM에 위임하는 승인 핸들러를 만듭니다. 각 ApprovalRequest를 구성 가능한 기준에 대해 평가하고 신뢰 점수와 함께 구조화된 결정을 반환합니다. 신뢰도가 임계값 아래로 떨어지면, 결정은 폴백 핸들러(다른 hitl 핸들러 또는 사람)로 에스컬레이션됩니다. 그래프 수준에서, humanNode() 빌더는 인터럽트 결정을 LLM에 위임하는 judge 옵션을 받습니다. 판단자가 확신하면 그래프는 중단 없이 계속됩니다. 신뢰도가 낮으면 실행은 일반 사람 인터럽트로 폴스루됩니다. 두 접근 방식 모두 구성 가능한 model, provider, criteria, confidence threshold를 지원합니다.

네. hitl.guardrailOverride가 활성화되면, 승인 결정 후에 가드레일이 실행되어 파괴적이거나 민감한 작업을 여전히 차단할 수 있습니다. 이것은 자동 승인, 사람 승인 또는 hitl.llmJudge() 이후에 두 번째 안전 계층을 추가합니다. 기본 사후 승인 가드레일에는 code-safety와 pii-redaction이 포함되며, hitl.postApprovalGuardrails로 목록을 구성할 수 있습니다. 승인 핸들러가 최종 결정권을 갖도록 명시적으로 원하는 경우에만 오버라이드를 비활성화하세요.

npm으로 설치: npm install @framers/agentos. AgentOS는 Node.js 22 이상이 필요합니다. CLI 도구는 동반 패키지를 설치하세요: npm install -g wunderland.

Import the agent function and configure it with a provider, instructions, and optional personality traits:

import { agent } from '@framers/agentos'

const myAgent = agent({
  provider: 'openai',
  instructions: 'You are a helpful assistant.',
  personality: {
    openness: 0.8,
    conscientiousness: 0.9,
  },
})

const reply = await myAgent.generate('Hello!')
console.log(reply.text)

AgentOS는 VoicePipelineOrchestrator로 음성을 처리합니다. 스트리밍 STT 세션, 스트리밍 TTS 세션, 발화 종료 감지기, 끼어들기(barge-in) 핸들러를 전달하면, WebSocket 같은 전송 계층을 통해 이들을 에이전트 세션에 연결합니다. 음성 카탈로그에는 13개 STT 프로바이더와 13개 TTS 프로바이더가 있습니다. 그중 사용할 수 있는 것은 Whisper(OpenAI), Deepgram, AssemblyAI를 포함한 11개 STT 프로바이더와 ElevenLabs, OpenAI TTS, Google Cloud TTS를 포함한 10개 TTS 프로바이더입니다. 나머지 5개 항목(Whisper.cpp, NVIDIA NeMo, Coqui XTTS, Bark, StyleTTS2)은 사용 불가로 표시되어 있으며, 프로바이더 리졸버는 이들을 건너뜁니다. Twilio, Telnyx, Plivo 프로바이더가 전화를 걸고 종료합니다.

AgentOS는 셀프 호스팅 가능하며 Node.js 22 이상이 실행되는 모든 곳에서 작동합니다. Docker로 자체 인프라에 배포하거나, AWS, GCP, Azure 같은 클라우드 프로바이더, 또는 Vercel, Railway, Fly.io 같은 플랫폼을 사용하세요. SQLite는 설정이 필요 없고, 더 큰 규모가 필요하면 MigrationEngine이 저장된 데이터를 Postgres, Qdrant 또는 Pinecone으로 옮깁니다.

네. 로컬 LLM 추론을 위한 Ollama와 함께 사용하면 AgentOS는 완전히 오프라인으로 작동합니다. Ollama는 Llama, Mistral, Phi와 같은 오픈 웨이트 모델에 로컬 접근을 제공합니다. SQLite 스토리지 백엔드와 인메모리 벡터 스토어는 외부 서비스가 필요하지 않습니다. Wunderland CLI의 ollama-setup 명령은 Ollama를 감지하거나 설치하고 에이전트가 사용하도록 구성합니다.

네. AgentOS에는 개인 데이터 편집, 콘텐츠 모더레이션, 출처 대조 검증을 수행하는 선택형 가드레일 팩, 민감한 도구 호출에 대한 승인 게이트, 한도를 넘는 호출을 거부하는 지출 예산, 장애가 난 프로바이더를 로테이션에서 빼는 서킷 브레이커가 있습니다.

AgentOS는 LLM 프로바이더에 도달하기 전에 개인 데이터를 제거하는 PII 마스킹 가드레일과 데이터를 자체 인프라에 유지하는 셀프 호스팅 배포를 제공합니다. 메모리는 접근 요청에 대비해 JSON, Markdown, Obsidian, SQLite로 내보낼 수 있습니다. 기억을 잊게 하면 회상 대상에서 빠지지만 그 행은 데이터베이스에 남으므로, 삭제 요청에는 자체 저장소에서의 삭제가 필요합니다. GDPR과 SOC 2 준수는 라이브러리 자체의 속성이 아니라 배포 팀의 조직적 책임입니다.

네. 프로덕션 배포, 엔터프라이즈 라이선싱, 전담 지원, 맞춤형 통합은 [email protected]로 팀에 연락하세요. 엔터프라이즈 지원에는 우선순위 이슈 해결, 아키텍처 컨설팅, 배포 지원이 포함됩니다.

[email protected]

물론입니다. AgentOS는 처음부터 셀프 호스트되도록 설계되었습니다. 셀프 호스트 배포의 경우, 데이터는 SQLite, Postgres, pgvector, Qdrant 또는 Neo4j와 함께 자체 인프라에 유지됩니다. 벤더 호스팅 관리형 벡터 데이터베이스를 선호한다면 Pinecone도 지원됩니다. 설정 헬퍼로 Docker를 사용해 로컬 Qdrant 컨테이너를 시작할 수 있습니다.