taco-devs/termo-agent

Firecracker VM을 위한 서버리스 (Serverless) AI 에이전트 런타임 (runtime).

어떤 프레임워크든 가져오세요. 프로덕션 서버를 구축하세요. 어디든 배포하세요.

웹사이트 • 앱 실행 • Twitter • 빠른 시작 • 문서

termo-agent는 모든 AI 에이전트에게 고유한 격리된 머신을 제공하는 오픈 소스 서버리스 (serverless) 런타임 (runtime)입니다. Firecracker 마이크로VM (microVMs)을 위해 구축된 이 런타임은 모든 Python 에이전트 프레임워크를 자동 수면/깨우기 (auto-sleep/wake) 라이프사이클 (lifecycle), 지속 가능한 상태 (persistent state), 그리고 완전한 도구 생태계를 갖춘 프로덕션 HTTP 서버로 변환합니다.

이는 에이전트가 쉘 (shell) 액세스, 파일 시스템 (filesystems), 그리고 장기 메모리 (long-term memory)를 갖춘 지속 가능한 VM에서 실행되는 Termo의 기반이 됩니다.

컨테이너 (Containers)는 커널 (kernel)을 공유합니다. Firecracker VM은 공유하지 않습니다. 각 에이전트는 약 125ms 내에 부팅되고 5MB 미만의 메모리 오버헤드 (memory overhead)를 소비하는 VM 내에서 하드웨어 수준의 격리 (isolation)를 제공받습니다. 이는 다음을 의미합니다:

에이전트가 안전하게 쉘 (shell) 명령을 실행하고, 패키지를 설치하며, 파일을 수정할 수 있음— VM을 탈출할 수 없습니다.
자동 수면 / 자동 깨우기 (Auto-sleep / auto-wake)— VM은 유휴 상태일 때 디스크로 일시 중단(suspend)되며 HTTP 요청 시 재개(~500ms)됩니다.
지속 가능한 상태 (Persistent state)— 파일 시스템 (filesystem), 메모리 (memory), 그리고 세션 (sessions)이 수면 사이클 동안 유지됩니다.
콜드 스타트 (cold start) 비용 없음— 웜 (warm) VM은 즉시 재개되며, 콜드 (cold) VM은 1초 이내에 부팅됩니다.

SSE Streaming— 별도의 설정 없이 즉시 사용 가능한 실시간 토큰 스트리밍 (Real-time token streaming)
세션 관리 (Session Management)— 자동 히스토리를 통한 지속적인 대화
인증 미들웨어 (Auth Middleware)— 구성 가능한 공개 경로를 포함한 Bearer 토큰 인증
어댑터 패턴 (Adapter Pattern)— OpenAI Agents SDK, Claude SDK, LangChain, CrewAI 또는 자체 프레임워크를 플러그인 방식으로 연결
시맨틱 메모리 (Semantic Memory)— 임베딩 검색 (embedding search) 기능이 포함된 ChromaDB 기반의 장기 메모리
스킬 마켓플레이스 (Skills Marketplace)— 에이전트가 런타임 (runtime) 중에 스킬을 발견, 설치 및 로드 가능
에이전트 간 호출 (Agent-to-Agent Calls)— 에이전트가 형제 에이전트를 발견하고 서로에게 작업을 위임 가능
하위 작업 (Subtasks)— 부모-자식 메시지 스레딩 (message threading)을 통한 병렬 백그라운드 작업 실행
스케줄 관리 (Schedule Management)— 에이전트가 자체적인 cron 잡 (cron jobs)을 생성, 목록화 및 삭제 가능
능동적 메시징 (Proactive Messaging)— 에이전트가 프롬프트 (prompt) 없이도 대화에 메시지를 푸시 가능
하트비트 (Heartbeat)— 스케줄에 따라 실행되는 주기적인 자율 작업
Telegram 연동 (Telegram Integration)— 채팅별 직렬화 (serialization) 및 비밀 검증 (secret verification) 기능을 갖춘 웹훅 (Webhook) 핸들러
브라우저 도구 (Browser Tools)— JS 중심 사이트 탐색을 위한 선택적 Chrome + PinchTab 연동
추가 라우트 (Extra Routes)— 어댑터가 커스텀 HTTP 엔드포인트 (endpoints)를 선언 가능
제로 컨피그 배포 (Zero Config Deploy)— 단 한 번의 명령으로 설치하고, 단 한 번의 명령으로 실행

pip install termo-agent
# OpenAI Agents SDK 지원 포함:
pip install 'termo-agent[openai]'
...

# 내장된 OpenAI Agents 어댑터로 실행:
termo-agent --adapter openai_agents --port 8080
# 커스텀 어댑터로 실행:
...

이제 에이전트가 전체 REST API와 함께 http://localhost:8080에서 라이브 상태가 되었습니다.

CLI는 작업 디렉토리에서 .env 파일을 자동으로 로드하므로, 해당 파일에 TERMO_TOKEN, TERMO_API_URL 및 기타 설정을 지정할 수 있습니다.

termo-agent는 Firecracker microVM을 지원하는 모든 플랫폼에서 실행됩니다:

플랫폼	방법
Termo	관리형 (Managed) — 에이전트를 생성하면 몇 초 안에 활성화됩니다
Sprites.dev	sprite create my-agent 실행 후 설치 및 서비스로 등록
Fly.io	termo-agent를 실행하는 Dockerfile과 함께 fly launch 실행
셀프 호스팅 (Self-hosted)	모든 Firecracker/Cloud Hypervisor 호스트 — termo-agent를 systemd 서비스로 실행

런타임 (Runtime)은 서버리스 생명주기 (serverless lifecycle)에 맞게 설계되었습니다: 깨어날 때 디스크에서 상태 (state)를 로드하고, 요청을 처리하며, 종료 시 상태를 깔끔하게 영속화 (persist) 합니다.

AgentAdapter 구현하기

어떤 에이전트 프레임워크라도 런타임에 연결하려면 AgentAdapter를 구현하세요. 단 5개의 메서드만 필요하며, 그 외의 모든 것은 합리적인 기본값 (defaults)을 가집니다:

from termo_agent import AgentAdapter, StreamEvent
class Adapter(AgentAdapter):
async def initialize(self, config_path=None):
...

메서드	목적
get_config() / update_config()	런타임 설정 (config) 읽기/쓰기
get_memory() / update_memory()	장기 메모리 (long-term memory) 읽기/쓰기
get_heartbeat() / update_heartbeat()	하트비트 (heartbeat) 설정
list_tools()	사용 가능한 도구 (tools) 노출
list_sessions()	모든 세션 목록 나열
extra_routes()	커스텀 HTTP 엔드포인트 (endpoints) 등록
public_route_prefixes()	인증을 건너뛰는 경로
is_public_request(path)	동적 인증 우회 로직
health()	커스텀 상태 확인 (health check) 데이터
restart()	커스텀 재시작 로직

어댑터 (Adapter)	프레임워크	설치 명령
platform_adapter	OpenAI Agents SDK + LiteLLM, 전체 도구 세트, 시맨틱 메모리 (semantic memory), 기술 (skills)	pip install 'termo-agent[openai]'
openai_agents	경량 OpenAI Agents SDK 래퍼 (wrapper)	pip install 'termo-agent[openai]'
claude_agents	훅 (hook) 시스템이 포함된 Claude SDK	pip install 'termo-agent[anthropic]'

어댑터는 추가적인 HTTP 엔드포인트를 선언하고 어떤 경로가 인증을 건너뛸지 구성할 수 있습니다:

class Adapter(AgentAdapter):
def extra_routes(self):
"""서버에 커스텀 엔드포인트를 등록합니다."""
...

platform_adapter는 에이전트를 자율 시스템 (autonomous system)으로 변환하는 전체 도구 세트를 제공합니다:

도구 (Tool)	설명 (Description)
execute_command(command)	VM 내에서 셸 명령 (shell commands) 실행
read_file(path) / write_file(path, content) / edit_file(...)	파일 시스템 (Filesystem) 작업
list_files(path)	디렉토리 목록 (Directory listing) 확인
web_search(query)	Exa를 통한 웹 검색
web_fetch(url)	URL로부터 콘텐츠를 가져오고 추출

도구 (Tool)	설명 (Description)
remember(content, category)	의미론적 임베딩 (semantic embedding) (ChromaDB + BGE-M3)을 사용하여 메모리 저장
recall(query, limit)	저장된 메모리 전체에 대한 의미론적 검색 (Semantic search)

카테고리: identity, preference, fact, project, user_profile |

도구 (Tool)	설명 (Description)
search_skills(query)	스킬 마켓플레이스 (skill marketplace) 검색
install_skill(slug)	스킬 설치
load_skill(slug)	컨텍스트 (context)에 스킬 지침 (instructions) 로드
uninstall_skill(slug)	설치된 스킬 제거

도구 (Tool)	설명 (Description)
list_agents()	동일한 사용자가 소유한 형제 에이전트 (sibling agents) 탐색
call_agent(agent_slug, message)	다른 에이전트에게 메시지를 보내고 응답 받기
launch_task(title, instructions)	병렬 서브태스크 (parallel subtask) 생성 (부모-자식 메시지 스레딩)

도구 (Tool)	설명 (Description)
create_schedule(cron, prompt, name)	에이전트를 트리거하는 cron 작업 생성
list_schedules()	활성화된 예약된 작업 목록 표시
delete_schedule(schedule_id)	예약된 작업 제거
send_message_to_conversation(conversation_id, message)	프롬프트 없이 대화에 메시지 전송

설정에서 browser_enabled: true로 활성화 가능. PinchTab 기반:

도구 (Tool)	설명 (Description)
browse(url)	URL로 이동하여 페이지 텍스트 반환 (~800 토큰). JS 렌더링된 콘텐츠 지원.
browse_observe()	안정적인 참조(e0, e1...)와 함께 현재 페이지의 상호작용 요소 가져오기
browse_act(ref, action, value)	참조(ref)를 통해 요소 클릭, 타이핑, 채우기, 누르기 또는 스크롤

설정에서 telegram 채널을 추가하여 활성화 가능. 채팅별 잠금(per-chat locking) 및 웹훅 비밀 검증(webhook secret verification) 기반:

| 도구 (Tool) | 설명 |\n|---|---|\n| send_telegram_message(type, text, ...) | 사용자의 Telegram 채팅으로 텍스트, 사진, 문서, 스티커 또는 위치 정보를 전송 |\n\n모든 termo-agent 서버는 동일한 API를 노출합니다:\n\n| 메서드 (Method) | 경로 (Path) | 설명 |\n|---|---|---|\n| GET | /health | 상태 확인 (Health check) (공개) |\n| POST | /api/send | 메시지 전송 (stream: true 설정 시 SSE 사용) |\n| GET | /api/sessions/{key}/history | 세션 기록 (Session history) |\n| GET | /api/sessions | 모든 세션 목록 |\n| GET | /api/config | 에이전트 설정 (Agent config) 가져오기 |\n| PATCH | /api/config | 런타임 중 설정 업데이트 |\n| POST | /api/update | 플랫폼으로부터 설정 핫 리로드 (Hot-reload) |\n| GET | /api/tools | 사용 가능한 도구 목록 |\n| GET | /api/memory | 에이전트 메모리 (Agent memory) 가져오기 |\n| PATCH | /api/memory | 메모리 업데이트 |\n| POST | /api/memory/search | 의미론적 메모리 검색 (Semantic memory search) |\n| GET | /api/heartbeat | 하트비트 (Heartbeat) 설정 가져오기 |\n| PATCH | /api/heartbeat | 하트비트 업데이트 |\n| POST | /api/restart | 에이전트 재시작 |\n\n\ncurl -N -X POST http://localhost:8080/api/send \\n-H "Authorization: Bearer my-token" \\n-H "Content-Type: application/json" \\n...\n\n\n\ndata: {\"type\": \"token\", \"content\": \"Hello\"}\ndata: {\"type\": \"token\", \"content\": \" there!\"}\ndata: {\"type\": \"tool_start\", \"name\": \"web_search\", \"input\": {\"query\": \"latest news\"}}\n...\n\n\n\n┌──────────────────────────────────────────────────────┐\n│ Firecracker microVM │\n│ \n...\n\n\n기여(Contributions)를 환영합니다! 이슈(Issue)를 생성하거나 PR(Pull Request)을 보내주세요.\n\n\ngit clone https://github.com/taco-devs/termo-agent.git\ncd termo-agent\npip install -e '.[dev]'\n...\n\n\nMIT © Tanic Labs