Strands 엔진
Libre WebUI에는 오픈 소스
Strands Agents 하네스
(@strands-agents/sdk 1.19.0 기반의 @strands-agents/harness 0.1.1)로 만든
에이전트 엔진이 내장되어 있습니다. 엔진은 Libre WebUI 백엔드 프로세스 안에서
실행되므로 별도의 데몬을 설치할 필요가 없습니다. SDK는 엔진을 처음 사용할 때
로드되며, Strands를 끈 서버에서는 전혀 로드되지 않습니다.
엔진은 Libre WebUI가 이미 제공하는 모델을 구동합니다.
- Ollama가 활성화된 경우 Ollama 모델
- 활성화된 채팅 또는 완성 제공자 플러그인의 모델
모든 모델 호출은 채팅이 사용하는 것과 같은 Ollama 및 플러그인 서비스를 거칩니다. 별도의 제공자 구성도, 별도의 API 키도 없습니다. 제공자 자격 증명과 Ollama 스위치는 그대로 적용됩니다.
엔진은 세 곳에서 사용할 수 있습니다.
- 영구 에이전트 세션을 위한 Strands 페이지
- 모델 선택기의 Strands 항목을 통한 채팅
- 작성기 엔진 컨트롤의 Strands 옵션을 통한 Work
접근 권한
관리자는 설정 → 사용자 관리 → 접근 및 정책 → Strands 엔진에서 엔진을 사용할 수 있는 사람을 선택합니다.
| 모드 | 설정에 표시되는 레이블 | Strands를 사용할 수 있는 사람 |
|---|---|---|
disabled | 꺼짐 | 관리자를 포함해 아무도 없음(기본값) |
admins | 관리자 | 활성 관리자 |
all-users | 모든 사용자 | 모든 활성 계정 |
변경 사항은 다시 시작하지 않아도 다음 요청부터 적용됩니다.
배포 수준에서 모드를 고정하려면 LIBRE_STRANDS_ACCESS를 설정합니다.
LIBRE_STRANDS_ACCESS=admins # or disabled, all-users
모드를 고정하면 사용자 관리의 컨트롤이 잠깁니다. disabled, admins,
all-users 이외의 값은 저장된 설정으로 돌아가지 않고 엔진을 꺼진 상태로
잠급니다.
서버는 모든 REST 요청, WebSocket 채팅, Work 실행의 모든 모델 호출에서 모드를
적용합니다. 모드를 읽을 수 없으면 접근이 거부됩니다. 접근 권한이 없는
계정에는 Strands 페이지, Strands 채팅 항목, Strands Work 엔진이 표시되지 않으며
API는 403으로 응답합니다.
Strands 페이지
사이드바에서 Strands(/strands)를 엽니다.
- 세션은 다시 시작한 뒤에도 유지되며 계정당 최대 200개까지 만들 수 있습니다. 새 세션의 이름은 첫 메시지로 정해집니다.
- 세션마다 모델을 선택합니다. 기본 모델은 기본 채팅 모델을 사용합니다.
- 답변은 생성되는 대로 스트리밍되며, 모델의 추론과 도구 호출마다 카드가 함께 표시됩니다.
- 중지는 실행 중인 턴을 취소합니다. 세션은 한 번에 하나의 턴만 실행합니다.
- 세션을 삭제하면 기록과 작업 공간이 함께 제거됩니다.
채팅
모델 선택기에서 Strands를 선택합니다. 에이전트 CLI 모델 옆의 에이전트 그룹에 표시됩니다.
- Strands(
strands)는 엔진 기본값, 즉 기본 채팅 모델을 사용합니다. - Strands · 모델 (제공자)(
strands:<route>)는 대화에 모델 하나와 해당 제공자를 고정합니다.
채팅의 Strands는 Strands 접근 권한에만 의존합니다. 에이전트 CLI 모델 토글이 필요하지 않으며, 그 토글이 꺼져 있어도 표시됩니다. 채팅에서 에이전트는 계정마다 하나씩 있는 개인 작업 공간에서 Strands 페이지와 같은 파일 도구를 사용하며, 답변은 텍스트와 추론으로 전달됩니다. 에이전트 그룹과, Strands 항목을 제목 및 사고 요약용 작업 모델로 사용하는 방법은 설치된 코딩 에이전트를 참고하세요.
Work
Work 작성기의 엔진 컨트롤에서 Libre WebUI 또는 Strands를 선택하고, 모델은 따로 고릅니다. Strands를 선택하면 Strands 에이전트가 각 단계를 계획하고, Work는 에이전트가 요청한 도구를 Work의 일반 승인 정책에 따라 Work 샌드박스에서 실행합니다. 대화 기록, 승인, 도구 실행, 실행 기록은 계속 Work가 기준이 되며, Work 안에서 Strands 에이전트는 자체 도구를 하나도 실행하지 않습니다.
기반 제공자 모델은 도구 호출을 지원해야 합니다. Work는 실행을 시작하기 전에 이를 확인하고, 도구 지원을 알리지 않는 모델은 거부합니다.
이전 릴리스에서 dsh: 모델 접두사로 저장된 Work 실행은 Strands 실행으로
열립니다. 엔진 선택이 채팅에서 넘어온 모델과 어떻게 맞물리는지는
Work: Strands 엔진을 참고하세요.
보안 모델
Strands 페이지와 채팅에서 에이전트는 의도적으로 작게 제한한 도구 세트만 사용합니다.
- 작업 공간의 파일을 다루는
read,write,edit - 여러 단계 작업을 계획하는 하네스
todos플러그인
셸, 웹 가져오기, 메모리, 스킬은 없으며 AGENTS.md 파일도 지침에 주입되지
않습니다.
각 세션에는 개인 작업 공간 디렉터리가 있으며, 에이전트에게는 /workspace로
보입니다. 모든 경로는 심볼릭 링크를 따라간 뒤에 확인되며 반드시 그 디렉터리
안에 있어야 하므로, 작업 공간 안의 링크로 디스크의 다른 부분에 접근할 수
없습니다. 샌드박스는 명령 실행을 거부합니다.
| 항목 | 한도 |
|---|---|
| 계정당 세션 | 200 |
| 프롬프트 길이 | 32,000자 |
| 메시지당 에이전트 턴 | 24 |
| 파일 읽기 또는 쓰기 | 호출당 2 MB |
| 세션 제목 | 120자 |
턴 한도에 도달한 턴은 중지되고 그 사실을 알려 줍니다. 턴 하나가 제공자에게 여러 번 모델 호출을 할 수 있으므로, 제공자 예산을 소비하는 다른 모델 접근 권한과 마찬가지로 신중하게 권한을 부여하세요.
저장소
Strands 데이터는 애플리케이션 데이터베이스가 아니라 <DATA_DIR>/strands/
아래에 저장됩니다. 계정마다 자체 디렉터리
<DATA_DIR>/strands/users/<account-hash>/가 있으며 다음을 포함합니다.
registry.json: 계정의 세션 목록sessions/: 에이전트가 컨텍스트로 사용하는 Strands 세션 스냅샷transcripts/: Strands 페이지에 표시되는 세션별 대화 기록workspaces/: 각 세션의 개인 작업 공간chat-workspace/: 채팅 턴에서 사용하는 작업 공간
세션이 중요하다면 백업에 <DATA_DIR>/strands/를 포함하세요.
사용량
제공자 사용량(/usage)은 Strands 호출을 에이전트 섹션의 Strands
에이전트에 귀속합니다. 에이전트 사용량을
참고하세요.
API
/api/strands/access는 관리자만 사용할 수 있으며, 그 밖의 모든 경로에는
Strands 접근 권한이 있는 인증된 계정이 필요합니다.
| 메서드 | 경로 | 용도 |
|---|---|---|
GET | /api/strands/access | 접근 모드와 LIBRE_STRANDS_ACCESS로 고정되었는지 여부 읽기(관리자) |
PUT | /api/strands/access | mode를 disabled, admins, all-users 중 하나로 설정(관리자, 고정 시 409) |
GET | /api/strands/health | 엔진 가용성과 하네스 및 SDK 버전 |
GET | /api/strands/models | 이 계정에서 엔진이 구동할 수 있는 모델 |
GET | /api/strands/sessions | 세션 목록 |
POST | /api/strands/sessions | 세션 만들기(선택 사항: title, model) |
GET | /api/strands/sessions/:sessionId | 세션, 대화 기록, 턴 실행 여부 읽기 |
PATCH | /api/strands/sessions/:sessionId | 세션 제목 또는 모델 변경 |
DELETE | /api/strands/sessions/:sessionId | 대화 기록 및 작업 공간과 함께 세션 삭제 |
POST | /api/strands/sessions/:sessionId/messages | { "text": "..." }를 보내고 턴을 NDJSON으로 스트리밍 |
POST | /api/strands/sessions/:sessionId/cancel | 실행 중인 턴 중지 |
메시지 스트림은 한 줄에 JSON 이벤트 하나를 씁니다. 이벤트는 turn-start,
text, reasoning, tool-start, tool-result, done(중지 이유와, 제공자가
보고하는 경우 토큰 사용량 포함), error입니다. 연결을 닫으면 턴이 취소됩니다.
턴이 실행 중일 때 메시지를 보내면 409가 반환됩니다.
구성
| 변수 | 기본값 | 용도 |
|---|---|---|
LIBRE_STRANDS_ACCESS | 미설정(관리자 설정, admins) | disabled, admins, all-users 중 하나로 고정. 그 밖의 값은 엔진을 꺼진 상태로 잠금 |
문제 해결
Strands 엔진 문제를 참고하세요.