AgentOS · TypeScript AI Agent Framework

기억하고, 자체 도구를 만들고, 장시간 세션을 생존하는 에이전트. 영구적인 코그니티브 메모리(Persistent cognitive memory), 선택적 HEXACO 성격, 다중 에이전트 오케스트레이션(multi-agent orchestration), 그리고 13개 LLM 제공업체에 걸친 단일 디스패치 인터페이스. Apache-2.0.

CI

tests

codecov

TypeScript

License

NVIDIA Inception

LongMemEval-S

LongMemEval-M

agentos-bench

Discord

벤치마크(Benchmarks) * 웹사이트(Website) * 문서(Docs) * npm * 디스코드(Discord) * 블로그(Blog)

AgentOS는 AI 에이전트가 기억하고, 적응하며, 자체 도구를 작성할 수 있게 하는 오픈 소스 TypeScript 프레임워크입니다.

• 최고의 오픈 소스 메모리 벤치마크: LongMemEval-S에서 $0.0090/정답(gpt-4o)으로 85.6%를 기록했으며 https://github.com/framerslab/agentos-bench/blob/master/results/LEADERBOARD.md에서, 재현 가능한 방법론을 갖춘 M 레벨에서는 70.2%를 기록한 유일한 오픈 소스 라이브러리입니다.
• 런타임 도구 생성(Runtime tool forging). 에이전트가 입력 및 출력을 위한 JSON Schema를 가진 JavaScript 함수를 작성하면, 선언된 테스트 케이스가 이를 실행하고, LLM 심사관이 결과를 검토하며, 승인되면 해당 도구가 세션의 도구 목록에 추가됩니다. 생성된 코드는 인-프로세스 node:vm 컨텍스트에서 또는 QuickJSExecutor를 사용하면 호출마다 QuickJS WebAssembly 인스턴스 내에서 실행됩니다.
• Ebbinghaus 망각 곡선과 8가지 신경과학 기반 메커니즘을 갖춘 영구적인 인지 메모리(cognitive memory)를 제공하며, 여기에는 검색 유도 망각(retrieval-induced forgetting), 재응고화(reconsolidation), 출처 신뢰도 감소(source-confidence decay) 등이 포함됩니다.
• 13개 LLM 공급자에 걸쳐 선택적인 HEXACO 성격(personality), 6가지 오케스트레이션 전략, 가드레일(guardrails), 그리고 음성(voice) 기능을 제공하며, 100개 이상의 확장 기능과 88개의 스킬은 로드되는 레지스트리를 가진 별도의 패키지로 배포됩니다.

설치 (Install)

npm install @framers/agentos

import { agent } from '@framers/agentos';

const tutor = agent({
...

전체 빠른 시작(Full quickstart) * 예제 레시피북(Examples cookbook) * API 참조(API reference)

세션(Sessions). 세션은 메모리 사용 여부와 관계없이 전체 대화를 유지합니다: 각 send()는 도구 호출, 그 결과, 그리고 모델의 사고 과정을 기록하며, 이후 모든 요청에서 이를 재생합니다. stream()은 자신의 차례를 프롬프트와 최종 텍스트(‘gmi’ 런타임 사용 시, send()가 하는 것처럼 모든 단계)로 기록합니다. 히스토리는 기본적으로 약 120K 토큰으로 제한됩니다. 상태 비저장 세션이 필요하면 history: false를 설정하고, 최대 토큰 수를 변경하려면 history: { maxTokens }를 설정하며, 직접 구성한 더 짧은 메시지 세트로 히스토리를 대체하려면 reseed()를 호출합니다. close()는 세션을 종료하고 그 역사를 해제합니다: 해당 ID로 다음 session(id)을 시작하면 비어 있으며, agent.usage(id)는 여전히 해당 ID가 사용한 양을 보고합니다.

const stateless = agent({ model, memory: false, history: false }).session('job-1');
const bounded = agent({ model, history: { maxTokens: 60_000 } }).session('job-2');
bounded.reseed([{ role: 'user', content: 'compact resume snapshot' }]);

창발적 설계 (Emergent Design)

세션 전반에 걸쳐 축적되어 행동을 구성하는 세 가지 요소가 있습니다: 메모리 (무엇이 말해지고, 결정되고, 검색되었는지), 도구 표면(tool surface) (에이전트가 도구를 생성하고 심판(judge)이 승인할 때 성장함), 그리고 프롬프트를 형성하고 메모리 인코딩을 조정하는 선택적 HEXACO 성격 벡터입니다. 이들 각각은 구성 가능하며 관찰 가능합니다.

런타임 도구 생성(Runtime tool forging). 에이전트가 특정 하위 작업에 대한 도구를 찾지 못할 경우, 기존 도구 체인이나 JavaScript 함수를 사용하여 forge_tool을 호출합니다. 이때 입력 및 출력용 JSON Schema와 테스트 케이스가 필요합니다. 코드 모드는 호스트가 emergentConfig.allowSandboxTools를 설정하기 전까지는 비활성화됩니다. eval, require 또는 process를 사용하는 소스는 실행 전에 거부됩니다. 생성된 코드는 기본적으로 인-프로세스(in-process)의 node:vm 컨텍스트에서 5초 타임아웃과 함께 실행되며, node:vm은 보안 경계가 아닙니다. QuickJSExecutor를 사용하면 각 호출이 자체 QuickJS WebAssembly 인스턴스 내에서 메모리가 제한된 상태로 실행됩니다. 별도의 LLM 심사관(judge)이 테스트 결과와 함께 후보 코드를 검토하고, 승인된 도구는 세션의 도구 목록에 추가됩니다. 생성된 도구는 SKILL.md 스킬로 내보내집니다. Emergent capabilities -> [HEXACO 성격(Personality) (선택 사항)]. 기본적으로 비활성화되어 있습니다. agent()는 트레이트 값들을 시스템 프롬프트에 지침으로 작성하며, 상기 트레이트 중 0.65 이상이거나 0.35 미만인 경우 각각 하나씩 기록합니다. 동일한 트레이트를 받은 인지 메모리 관리자(cognitive memory manager)는 이를 통해 인코딩과 여덟 가지 메커니즘 중 일곱 개를 조정하며, AgentGraph는 addPersonalityEdge()를 사용하여 특정 트레이트에서 분기됩니다. HEXACO 문서 -> 소울 파일(Soul files). 정체성(Identity), 목소리(voice), 하드 리밋(hard limits), 그리고 HEXACO 점수는 SOUL.md 작업 공간에 존재할 수 있습니다. 이의 memory/ 디렉토리는 마크다운 위키이며(index.md 카탈로그와 entities/, concepts/, log/ 페이지가 포함된 [[wikilinks]]), 에이전트의 장기 메모리 그 자체입니다: 마크다운이 진실의 원천(source of truth)이며, 벡터/그래프 인덱스는 이로부터 재구축되고, souledAgent()가 이를 엔드투엔드로 연결합니다. Soul Files -> ts import { souledAgent } from '@framers/agentos'; const aria = await souledAgent({ provider: 'anthropic', soul: '~/.agentos/agents/aria' }); --- ## 일반화된 마음 인스턴스 (Generalized Mind Instances, GMIs)

전체 런타임(full runtime)에서 모든 세션은 GMI에 의해 제공됩니다. GMI는 고유한 페르소나, 무드, 대화 기록 및 추론 흔적을 가진 영속적인 에이전트입니다. agent({ runtime: 'gmi' })를 사용하면 에이전트의 세션도 GMI가 됩니다. runtime: 'gmi' 없이 사용하는 agent()는 경량 헬퍼(lightweight helper)이며, 프롬프트로 모델을 호출하고 세션 기록을 유지합니다. 전체 런타임의 GMI는 동일한 모델, 도구(tools), 가드레일(guardrails) 및 인지 메모리(cognitive memory)를 중심으로 턴 루프(turn loop)를 실행합니다:

• 감성 → 메타 프롬프트(metaprompts). 페르소나가 감성 추적을 활성화하면, 모든 사용자 턴에 점수가 매겨집니다. 지속적인 좌절이나 혼란은 복구 메타 프롬프트를 작동시키고, 자기 성찰 메타 프롬프트는 증거(evidence)로부터 GMI의 무드와 작업 컨텍스트를 다시 읽어옵니다.
• 무드 가중치 메모리(Mood-weighted memory). 인지 메모리가 연결되면, 각 교환은 GMI의 현재 무드로 인코딩되고 감정적 일관성(emotional congruence)을 갖는 점수로 회상됩니다.
• 자기 수정 도구(Self-modification tools). selfImprovement.enabled가 활성화되면, 런타임은 adapt_personality, manage_skills, create_workflow, self_evaluate를 등록합니다. adapt_personality는 실행 중인 GMI의 특성을 범위 내에서 변경하며, 스토리지 어댑터(storage adapter)와 persistWithDecay가 구성되면 뮤테이션 스토어(mutation store)가 변경 사항을 기록합니다.
• 추론 흔적(reasoning trace). 기본적으로 지난 500개 결정에 대한 추론 흔적(reasoningTraceConfig는 페르소나 또는 런타임의 기본값에서 설정 가능)과 세션별 페르소나 오버레이가 제공됩니다.

import { AgentOS, AgentOSResponseChunkType, BUILT_IN_PERSONAS } from '@framers/agentos';

// AgentOS.create()는 기본적으로 ./personas에서 페르소나 파일을 읽습니다. 페르소나는
...}

`agent({ runtime: 'gmi' })`는 또한 `gmi()`로 내보내지며, 에이전트의 옵션으로부터 프로세스 내에서 GMI(Generative Memory Instance)를 구축하며, 별도의 `AgentOS` 런타임은 없습니다. 위 구성 요소들 중 이 GMI는 추론 과정 (reasoning trace), 메모리가 활성화된 경우 분위기 가중치 메모리 (mood-weighted memory), 그리고 다섯 가지 사전 설정 이벤트 메타프롬프트(좌절 복구, 혼란 명확화, 만족도 강화, 오류 복구 및 몰입 증진)를 사용한 감정 추적을 실행합니다. `'full'` 프로필은 인지 메모리 (cognitive memory), 감정 추적 및 이 다섯 가지 메타프롬프트를 활성화하며, 기본값인 `'light'`는 추론 과정을 유지하고 `memory`가 설정된 경우에만 메모리를 추가합니다. 자기 성찰 메타프롬프트(self-reflection metaprompt), 자체 수정 도구(self-modification tools), 페르소나 오버레이(persona overlays) 및 런타임의 가드레일, 검색 (retrieval) 및 채널은 이 경로에서 실행되지 않습니다. 이 튜터의 GMI는 이 경로의 모든 부분을 실행합니다: 

```ts
import { agent } from '@framers/agentos';

const tutor = agent({
...

일반 에이전트 대비 GMI가 추가하는 것 →

메모리 벤치마크 (Memory Benchmarks)

gpt-4o 리더, gpt-4o-2024-08-06 심사위원(judge), 전체 N=500, 부트스트랩 95% CI 및 개별 벤치마크 심사위원-FPR 프로브를 사용한 단일 CLI 재현.

• LongMemEval-S: 85.6% (정답당 $0.0090/correct, p50 3,558 ms): Mastra OM gpt-4o(84.23%)보다 +1.4 포인트 높고, Emergence.ai의 비공개 소스 86%보다는 0.4 포인트 낮습니다. gpt-4o에서 공개적으로 재현 가능한 가장 높은 오픈소스 수치입니다.
• LongMemEval-M: 70.2% (1.5M 토큰 더미, 500 세션): 재현 가능한 방법론을 가진 M 분야에서 65%를 초과하는 유일한 오픈소스 라이브러리입니다.

전체 리더보드 -> * 투명성 감사(Transparency audit) -> * LongMemEval 논문 (Wu et al., ICLR 2025)

AgentOS를 사용하는 이유 (Why AgentOS)

주요 기능 (Key Features)

6줄 만에 구현하는 멀티 에이전트 (Multi-Agent in 6 Lines)

import { agency } from '@framers/agentos';

const team = agency({
...

전략: sequential, parallel, debate, review-loop, hierarchical, graph. hierarchical + emergent: { enabled: true }를 사용하면 매니저가 런타임에 새로운 서브 에이전트를 제작합니다. 등록된 모든 에이전트는 자체 provider, model, apiKey, 그리고 effort를 설정할 수 있으며, parallel 에이전시는 합성하기 전에 제공업체 쿼럼(quorum: { minProviders: 2 })을 요구할 수 있습니다. 멀티 에이전트 문서 ->

생태계 (Ecosystem)