from scratch

[논문 리뷰] SMORES-EP, a Modular Robot with Parallel Self-assembly

imnewon — Fri, 5 Jun 2026 00:12:46 +0900

SMORES-EP, a Modular Robot with Parallel Self-assembly

Self-assembly of modular robotic systems enables the construction of complex robotic configurations to adapt to different tasks. This paper presents a framework for SMORES types of modular robots to efficiently self-assemble into tree topologies. These mod

arxiv.org

Abstract

EP 자석을 사용하는 SMORES 형태의 Modular Robot 제어에 관한 논문입니다. 따라서 글에서는 하드웨어 구조나 실험에 대한 설명은 최소화하고, 논문의 핵심 기여점인 제어 알고리즘 부문을 중심으로 얘기해볼까 합니다. 생략된 내용이 다소 많으므로 참고용으로만 보시기를 바랍니다.

Introduction

제한적 기능을 가진 단일 로봇(휴머노이드 등)에 비해,상황에 따라 조립과 분해가 가능한 모듈형 로봇(Modular Robot)은 무한한 잠재력을 가집니다. 복잡한 지형 극복, 물체 조작, 협력 이동 등 임무에 맞춰 로봇의 형태(Morphology)를 자유롭게 바꿀 수 있기 때문입니다. 그러나 모듈의 수가 늘어날수록 시스템의 제어 복잡도가 기하급수적으로 증가하고, 하드웨어적 제약 조건 하에서 충돌 없이 정밀하게 도킹(Docking)을 수행하는 것이 매우 어렵다는 한계가 있습니다.

본 논문은 이러한 한계를 극복하고, 여러 개의 모듈형 로봇이 트리 토폴로지(Tree Topology) 형태로 효율적이고 안정적인 병렬 자가 조립(Parallel Self-assembly)을 수행할 수 있는 상위단 제어 알고리즘을 제안합니다.

SMORES-EP는 SMORES(Self-assembly MOdular Robot for Extreme Shape-shifting)의 최신 버전으로, 이름 그대로 극단적인 형태 변형을 목표로 설계된 모듈러 로봇입니다. 각 모듈은 컴팩트한 크기(80mm 정육면체)에 4 DoF(자유도)를 가집니다.

LEFT, RIGHT, PAN, TILT 축으로 구성되며, LEFT와 RIGHT 축은 바퀴 역할을 하여 차동 구동(Differential Drive) 방식으로 평면을 이동할 수 있습니다. LEFT, RIGHT, TOP, BOTTOM 총 4개의 면에 결합용 커넥터가 있습니다. 커넥터로 EP Magnet이라는 굉장히 흥미로운 자석이 활용되는데, 일반 전자석은 계속 전류를 흘려야 하지만 EP Magnet은 짧은 전류 펄스만으로 ON/OFF 상태를 변경할 수 있습니다. 따라서 전력 소모가 매우 적은데 결합력은 최대 약 90N에 달합니다. 논문에 따르면 약 4mm 정도 떨어져 있어도 자동으로 끌어당겨 결합이 가능하다고 합니다.

논문의 전체 흐름은 크게 세 단계로 나뉩니다.
1. Root Module Search
2. Task Assignment
3. Docking Control

목표 topology가 주어지면,
1. 루트 모듈을 찾고
2. 각 실제 모듈에게 역할을 배정한 뒤
3. 충돌 없이 이동하여 결합합니다.

Modular Robot Topology Configuration

목표로 하는 그래프 G=(V, E)(G는 graph, V는 노드, E는 간선)가 주어지면, 알고리즘은 먼저 시스템의 중심이 될 루트 노드(τ)를 찾습니다. 논문에서는 트리의 균형을 최적화하기 위해 트리 센트로이드(Tree Centroid) 개념을 활용합니다. 특정 노드를 기준으로 한 하위 서브트리들의 모듈 수가 전체 모듈 수의 과반수(1/2) 이하가 되도록 하는 노드를 τ로 지정하는 방식입니다.

τ 기준 특정 방향에 결합된 모듈들이 전체 모듈의 과반수 이하일 경우 루트모듈임을 의미합니다.

다음을 충족시키는 τ를 구하는 것이 topology configuration의 핵심이자 Algorithm 1의 내용이라고 볼 수 있겠습니다.

(1/4이 아닌 1/2인 이유에 대해 의문을 가졌었는데, 이는 tree controid 개념을 참고하시면 됩니다.)

무작위 v_0을 구해서 트리를 루팅한 뒤,

모든 h(v)가 1인 v(즉 leaf 위 노드)에 대해 자식 노드(leaf)의 CN을 합산(7열),

모든 h(v)가 1인 v의 부모 노드의 CN값을 구해 합산(8열)하여 상단 식을 충족시키는 v를 τ로 지정합니다.

해당 알고리즘은 Bottom-Up Dynamic Programming를 통해 O(|V|)의 시간복잡도로 계산될 수 있습니다.

동시에 동시에 물리적 세계(평면 위)에서도 무게중심과 가장 가까운 최적의 실제 모듈(m_τ)을 선택해야 합니다.

위 식과 같이 전체 모듈들의 기하학적 중심(o_c)과 개별 모듈의 현재 위치(o_i) 사이의 유클리드 거리가 가장 최소인 모듈이 물리적 루트 모듈(m_τ)이 됩니다. m_τ에 대한 모든 m_i의 상태는 rigid body transformation을 통해 표현됩니다.

Self-assembly Problem

이제 실제로 결합할 차례입니다. 결합의 목적은 SMORES-EP tree topology configuration G=(V,E) 를 실제로 형성하는 것입니다. 이때, 평면 위에 펼쳐질 수 있는 topology만이 실제 결합될 수 있습니다. (아무래도 사방에 결합돼있는 구조는 구현하기가 곤란합니다.)

따라서 평면 위에 펼쳐질 수 있는 target kinematic topology G = (V,E)는 다음 조건을 만족합니다.

G is a connected graph;
The Euclidean distance between two adjacent modules is w; (w는 모듈의 길이)
The center of every module occupies a unique location.

따라서 우리가 해결해야 할 문제는, 충돌 없이 목표 topology를 형성하기 위한 결합 동작을 찾아내는 것입니다.

Task Assignment

루트 모듈이 결정되면 가상의 목표 토폴로지 상의 노드들과 평면 위에 흩어져 있는 실제 모듈들을 1:1로 매핑해 주어야 합니다. 본 논문에서는 모든 모듈의 총 이동 거리를 최소화하는 방향으로 최적화 문제를 정의하고, 이를 Kuhn-Munkres (헝가리안) 알고리즘 등을 활용하여 해결합니다. 이 매핑 정보를 기반으로 각 모듈은 자신이 도달해야 할 최종 목표 위치와 결합해야 할 상대 모듈을 할당받게 됩니다.

Parallel Assembly Actions

매핑이 완료되면 루트 모듈을 중심으로 하는 그리드(Grid) 환경이 생성되며, Depth를 가진 모듈들이 병렬적으로 조립을 시작합니다. 도킹은 자가 조립에서 오차가 가장 발생하기 쉽고 실패 확률이 높은 단계이므로, 논문에서는 이를 Navigation →Pose Adjustment → Approach의 3단계 닫힌 루프 제어로 세분화했습니다.

Navigation: 모듈들은 다중 로봇 경로 플래너(Multi-vehicle Planner)를 통해 서로 충돌하지 않는 최적의 전역 경로를 생성한 뒤, 도킹 대상 모듈의 근처 그리드까지 이동합니다.

Pose Adjustment: 도킹 직전 단계로, 타겟 커넥터면과 자신의 커넥터면을 완벽히 정렬하는 핵심 과정입니다.
- TOP / BOTTOM Face 결합: 자체 DoF(자유도)를 활용하여 본인의 상태를 능동적으로 보정할 수 있습니다.
- LEFT / RIGHT Face 결합: 모듈 구조상 좌우 면은 지면과 평행하게 구동되는 바퀴 축과 연결되어 있어, 평면 이동 상태에서는 자유로운 각도 정렬이 어렵습니다. 따라서 이 경우에는 추가적인 부속품을 장착한 별도의 Helping Module이 투입됩니다. Helping Module이 도킹 대상 모듈을 위로 들어 올려(Lift) 공중에서 자유롭게 면을 정렬할 수 있도록 도운 후 목적지까지 배달해 줍니다.

Approach: 정렬이 완료되면 접근 후 결합합니다. 두 모듈의 거리가 영구전자석(EP)의 유효 거리(약 4mm) 이내로 들어오면 강한 자력에 의해 물리적으로 결합되며 도킹이 완료됩니다.

이때, 평면 위의 루트 모듈은 바닥에 고정되어 있지 않기 때문에 모든 방향에서 동시에 도킹을 시도하면 위치가 틀어질 수 있습니다. 예외적으로 루트 모듈의 경우에는 LEFT Face와 RIGHT Face 결합을 우선적으로, TOP Face와 BOTTOM Face의 결합을 이후 진행합니다. 이러한 과정을 통해 결과적으로 주어진 topology를 구현해낼 수 있습니다.

Experiments

논문서 제안한 프레임워크의 실효성을 검증하기 위해 세 가지 실험을 수행합니다.

Task 1-Mobile Manipulator: 7개의 모듈이 조립되어 높은 곳의 물건을 집을 수 있는 형태를 구성합니다. (a)~(d)에서 병렬 조립을 보실 수 있습니다.

Task 2: Holonomic Vehicle: 9개의 모듈이 그리드 위에서 정밀한 타이밍으로 움직이며 충돌 없이 완벽한 이동 로봇 형태로 조립됩니다.

Task 3: RC Car: 7개의 모듈이 결합하여 무거운 물체를 밀 수 있는 구조를 만듭니다. (b)에서 앞서 언급한 Helping Module이 투입되어 LEFT/RIGHT 면 도킹을 성공적으로 보조하는 모습을 확인할 수 있습니다.

또한, 단순히 해체된 모듈들의 자가 조립뿐만 아니라, Walker(보행 로봇)형태에서 Mobile Manipulator 형태로 구조를 바꾸는 Self-reconfiguration 과정 역시 전체 분리 후 parallel assembly 알고리즘을 적용하여 시간을 단축시켰다고 합니다.

Conclusion

SMORES-EP 자체는 기존 연구의 연장선상에 가깝습니다. 오히려 핵심은

Tree Centroid 기반 Root Selection
Hungarian Algorithm 기반 Task Assignment
Depth 기반 Parallel Assembly
실제 하드웨어에서 동작 가능한 Docking Controller

를 하나의 파이프라인으로 통합했다는 점입니다. 물론 아직 VICON에 의존하고 있으며, 3차원 구조 생성이나 대규모 모듈 집단에 대한 검증은 부족합니다. 실제 야외 환경에서 사용하기까지는 갈 길이 멉니다. 그럼에도 불구하고 "모듈형 로봇을 실제로 빠르게 조립시키려면 무엇이 필요한가?"에 대한 상당히 현실적인 답을 제시한 논문이라고 생각합니다. 생략된 내용이 상당히 많으니 논문을 읽어보시기를 바랍니다.

[공부] Opencode Tool-call Engine 리버스 엔지니어링

imnewon — Fri, 22 May 2026 13:21:06 +0900

AI Agent의 핵심 중 하나는 tool-call입니다. 저는 현재 SLM을 end-point로 바꿔도 잘 돌아가는 local agent를 만드는 것을 목표로 연구하고 있으며, 오늘은 tool-call에 대해 정리해보려 합니다.

저는 조립은 분해의 역순이라는 말을 정말 좋아합니다. tool call engine을 공부하기 위해, 실제 agent인 opencode의 tool call과 관련된 부분을 분석한 후 이것을 재조립해볼 생각입니다. 그리고 이 글은 '분해'에 해당합니다. 여러분들도 함께 opencode를 뜯어보시기를 바라겠습니다. 중간에 뭔가 잘못됐음을 깨달아 opencode랑 llm 디렉토리의 구분이 없습니다.

https://github.com/anomalyco/opencode

GitHub - anomalyco/opencode: The open source coding agent.

The open source coding agent. Contribute to anomalyco/opencode development by creating an account on GitHub.

github.com

opencode의 대략적인 흐름은 다음과 같습니다.

[진입점]
packages/opencode/src/index.ts  (yargs CLI)
         ↓
packages/opencode/src/cli/cmd/run.ts  (RunCommand)
         ↓
cli/cmd/run/runtime.ts  →  runPromptQueue()  (직렬 큐)
         ↓
SDK client: session.prompt()
         ↓
[서버]
server/server.ts  →  HTTP API 라우터
         ↓
[세션]
session/prompt.ts  →  prompt()
         ↓
         loop()
         ↓
         runLoop()  ← 여기가 메인 while(true) 루프

그리고 아래는 tool-call의 흐름입니다. AI SDK가 streamText()로 스트림 받으면서 tool call을 감지하고, resolveTools()에서 wrapping한 execute()가 호출되는 구조입니다. 루프는 툴 결과를 히스토리에 누적해서 계속 LLM을 재호출하는 방식으로 돌아갑니다.

사용자 입력 (텍스트)
    ↓
[1] Session.prompt()           ← 세션에 메시지 등록
    ↓
[2] resolveTools()             ← 사용 가능한 도구 목록 수집
    ↓
[3] LLM.stream()               ← AI에 요청 전송 (HTTP)
    ↓
[4] ToolRuntime.stream()       ← 응답 스트리밍 + 도구 호출 감지
    ↓
[5] dispatch(tool, input)      ← 도구 실행
    ↓
[6] 결과 주입 → [3]으로 루프   ← 결과를 다음 AI 요청에 포함

이제 저희는 여기서 엔드포인트를 떼서 SLM에 갖다붙였을 때 동작하게 만들면 됩니다. 진입점과 서버, 기타 wrapping에 대해 전부 분석할 경우 머리가 터질테니 생략하고 tool call만 보겠습니다. 핵심은 tool call이 어떻게 작동하는가 입니다.

그 전에 구조부터 정리하고 가겠습니다. 현재 src를 하위에 두는 주요 패키지는 크게 두 개입니다. packages/llm packages/opencode

packages/llm은 AI SDK를 대체하기 위해 직접 구현 중인 자체 LLM 클라이언트 라이브러리입니다. Provider별 HTTP 프로토콜 처리, 스트리밍, tool execution 등을 직접 구현하고 있으며, 전체 구조는 Effect 기반으로 타입 안전하게 설계되어 있습니다. 또한 이 패키지는 앱 내부 전용 코드가 아니라, 외부에서도 @opencode-ai/llm 형태로 import해서 독립적으로 사용할 수 있도록 구성되어 있습니다.

반면 packages/opencode는 실제 애플리케이션 본체입니다. 현재 opencode는 아직 AI SDK 의 streamText()를 통해 LLM을 호출하고 있습니다. 여기서 중요한 포인트가 하나 있습니다. streamText()가 호출되는 순간부터 제어권이 AI SDK 내부로 넘어가기 때문에, 이후 데이터가 어떤 경로로 흐르고 어떤 형태로 변환되는지를 외부에서 정확히 추적하기가 어렵습니다.

따라서 이번 분석에서는 step 1~3까지는 packages/opencode, step 4~5부터는 packages/llm 기준으로 흐름을 따라갈 예정입니다.

왜 분리되어 있냐? packages/llm이 완성되면 packages/opencode의 AI SDK 의존성을 @opencode-ai/llm으로 교체할 계획인 것 같습니다. 지금은 마이그레이션 진행 중이라 둘이 공존하는 상태입니다.

STEP 1. 입력 처리(src/session/prompt.ts)

prompt.ts 코드는 opencode 프로젝트에서 AI 세션의 프롬프트 제어, Tool Call, Subtask 분기 등 핵심 오케스트레이션(Orchestration)을 담당하는 중추적인 백엔드 로직입니다. 사용자가 명령하면(코드가 PromptInput을 받으면) 아래 흐름으로 함수들이 호출됩니다.

export async function prompt(input: PromptInput) { 
  const userMessage = createUserMessage(input.text, input.attachments) 
  const tools = await resolveTools(input)
  await SessionProcessor.run(userMessage, tools)
}

createUserMessage는 유저가 보낸 parts(텍스트, 파일, 에이전트 멘션 등)를 실제 메시지로 변환합니다. MessageV2.User타입의 구조체를 만듭니다. 그냥 User의 Input을 받는 구조가 있군, 생각해두고 넘어갑니다. 이걸 어떻게 하지? 싶은 부분들은 대부분 TypeScript의 Effect 라이브러리가 해결해줍니다.

* Effect 라이브러리? 타입 안전성과 에러 핸들링을 함수형 프로그래밍 스타일로 엮어주는 라이브러리

STEP 2. ToolRegistry(src/tool/registry.ts)

registry.ts에서는 AI가 사용할 수 있는 도구(tool)들을 모읍니다. 시스템 내부 registry에 등록된 툴들과, 외부 MCP 툴들을 파싱하고 현재 AI 모델이 이해할 수 있는 jsonSchema로 변환합니다. 이후 모델 종류와 설정(flag)에 따라 어떤 툴을 실제로 사용할 수 있을지 결정해 최종 Tool Registry를 구성합니다. (아래는 마찬가지로 요약 코드로, 실제와는 다릅니다.)

* MCP(Model Context Protocol): 대규모 언어 모델(LLM)이 데이터베이스, 파일 시스템, 외부 API 등 다양한 외부 도구와 안전하게 연결될 수 있도록 돕는 AI-외부 시스템 연결 표준 프로토콜. 슬랙이나 노션 같은 거
* Schema: AI 모델이 외부 도구(Tools), 데이터베이스, API와 상호작용하기 위한 '사용 설명서'이자 '데이터 규격'. ChatGPT API 생각해보면, 특정 틀에 맞춰 넣지 않으면 말귀를 못 알아듣습니다. 그 '특정 틀'이 schema에 해당합니다.

async function resolveTools(input) {
  const tools = {}

  // 1. 내장 도구 등록
  tools["read"]   = ReadTool      // 파일 읽기
  tools["write"]  = WriteTool     // 파일 쓰기
  tools["shell"]  = ShellTool     // 쉘 명령 실행
  tools["glob"]   = GlobTool      // 파일 패턴 검색
  tools["grep"]   = GrepTool      // 텍스트 검색

  // 2. 플러그인 도구 추가
  for (const plugin of loadedPlugins) {
    Object.assign(tools, plugin.tools)
  }

  // 3. MCP 도구 추가 (외부 서버 도구)
  const mcpTools = await loadMCPTools()
  Object.assign(tools, mcpTools)

  return tools
}

tool이 생긴 모습은 src/tool.ts에서 볼 수 있습니다. 대충 아래처럼 생겼습니다. description이 매우 중요합니다. AI가 이 description을 읽고 "어떤 도구를 언제 쓸지"를 스스로 결정합니다.

interface Tool<T, S> {
  description: string          // AI에게 보여주는 설명
  parameters: Schema<T>        // 입력 타입 정의 (JSON Schema)
  success: Schema<S>           // 출력 타입 정의
  execute?: (params: T) => Promise<S>  // 실제 실행 함수
}

STEP 3. LLM 요청 전송(src/session/llm.ts)

위는 선언과 정리를 하는 부분이고, 이제 슬슬 세션이 시작됩니다. 마찬가지로, 아래는 요약 코드입니다.

async function run(input: StreamInput) {
  const result = await streamText({
    model: languageModel,          // Anthropic / OpenAI / Gemini 등
    system: systemPrompt,          // AI의 역할 설명
    messages: conversationHistory, // 이전 대화 전체
    tools: toolDefinitions,        // 사용 가능한 도구 목록
    toolChoice: "auto",            // AI가 알아서 도구 선택
    maxTokens: 8192,
  })
  
  return result.stream  // 스트림 반환 (토큰 하나씩 오는 것)
}

우리는 AI의 응답을 한 번에 받는 것이 아니라, 토큰(단어 조각) 단위로 실시간으로 받습니다. 이게 스트리밍입니다. 터미널에서 AI가 타이핑하듯 출력되는 이유입니다.

opencode는 Anthropic, OpenAI, Google 등 다양한 provider를 지원합니다. 각 provider마다 API 형식이 다르기 때문에, 프로토콜 계층으로 추상화합니다 src/route/client.ts에 있습니다.

LLMClient.stream()
    ↓
Route 선택 (모델 이름으로 매핑)
    ↓
Protocol.body.from() → 제공자별 JSON 포맷 변환
    ↓
HTTP 요청 전송
    ↓
Protocol.stream.event() → 제공자별 응답을 통일된 LLMEvent로 변환

STEP 4. Tool-Call 감지 (src/tool-runtime.ts)

여기가 핵심입니다. AI의 응답 스트림을 읽으면서 도구 호출 명령을 감지합니다. AI는 일반 텍스트 응답 대신 아래와 같은 구조화된 메시지를 반환합니다. 이게 tool call입니다.

{
  "type": "tool_use",
  "id": "call_abc123",
  "name": "read",
  "input": {
    "path": "/Users/kywn/opencode/README.md"
  }
}

tool-runtime.ts는 아래처럼 굴러갑니다.

async function* stream(llmStream, tools, stopWhen) {
  while (true) {
    const state = await accumulate(llmStream)  // 이벤트 수집
    
    yield state.events  // 텍스트, 추론 등 중간 이벤트 출력
    
    if (state.finishReason === "tool_calls") {
      // 도구 호출이 있으면 병렬 실행
      const results = await Promise.all(
        state.toolCalls.map(call => dispatch(tools, call))
      )
      
      // 결과를 다음 AI 요청에 포함
      llmStream = followUpRequest(state, results)
      
    } else {
      break  // 텍스트 응답이면 루프 종료
    }
    
    if (stopWhen(state)) break
  }
}

accumulate()는 아래와 같은 이벤트들을 실행합니다.

"text-delta"        → 텍스트 조각 (화면에 실시간 출력)
"reasoning-delta"   → 추론 과정 (Claude extended thinking)
"tool-call"         → 도구 호출 요청 ← 오늘의 핵심
"finish-step"       → 이 단계 완료
"finish"            → 전체 완료

STEP 5. Tool 실행 (src/tool-runtime.ts)

아무래도 누가 불렀으면 대답을 해야겠죠... accmulate에서 tool-call이 감지되면 dispatch() 함수가 실행합니다. 이건 짧아서 진짜 코드 넣었습니다.

const dispatch = (tools: Tools, call: ToolCallPart): Effect.Effect<ToolResultValue> => {
  const tool = tools[call.name]
  if (!tool) return Effect.succeed({ type: "error" as const, value: `Unknown tool: ${call.name}` })
  // tool이 아닌데 실행되면 곤란합니다.
  if (!tool.execute)
    return Effect.succeed({ type: "error" as const, value: `Tool has no execute handler: ${call.name}` })
    // tool이 빈손으로 나오면 아무래도 곤란하죠
  return decodeAndExecute(tool, call.input).pipe(
  // 실행합니다.
    Effect.catchTag("LLM.ToolFailure", (failure) =>
      Effect.succeed({ type: "error" as const, value: failure.message } satisfies ToolResultValue),
    ),
  )
}

const decodeAndExecute = (tool: AnyTool, input: unknown): Effect.Effect<ToolResultValue, ToolFailure> =>
  tool._decode(input).pipe(
    Effect.mapError((error) => new ToolFailure({ message: `Invalid tool input: ${error.message}` })),
    // schema와 input이 다르면 곤란합니다.
    Effect.flatMap((decoded) => tool.execute!(decoded)),
    // 아니면 실행이 됩니다.
    Effect.flatMap((value) =>
      tool._encode(value).pipe(
      // 출력 validation 검증하는 부분입니다.
        Effect.mapError(
          (error) =>
            new ToolFailure({
              message: `Tool returned an invalid value for its success schema: ${error.message}`,
            }),
        ),
      ),
    ),
    Effect.map((encoded): ToolResultValue => ({ type: "json", value: encoded })),
  )

오류 잡는 부분에 특별한 건 없고, 출력 validation도 검증하는 게 인상적입니다. 프롬프트 엔지니어링과 harness의 본질적인 차이는 '본인의 오류를 본인이 잡아낼 수 있는가'의 여부라는 말을 들었는데 이런 부분을 말씀하신 것 같습니다. (이걸 차치하고서라도 schema 맞추고 validation하는 게 tool call의 핵심입니다.) 여러모로 편리하지만 짜야할 사람 입장에서는 고려할 게 많다고 볼 수 있습니다. 특히 더 문제가 많은 SLM은 여러 번 확인하는 게 필수적입니다. Effect가 다 해주는 것 같긴 합니다.

STEP 5. 루프 실행 (src/tool-runtime.ts)

tool-runtime.ts을 잘 살펴보시면 재귀인 걸 알 수 있습니다. (아무래도 루프니까요) 루프에 갇혀서 조건이 충족되기 전까지 계속 tool call을 한다고 보시면 되겠습니다.

const loop = (request: LLMRequest, step: number): Stream.Stream<LLMEvent, LLMError> =>
    Stream.unwrap(
      Effect.gen(function* () {
        const state: StepState = { assistantContent: [], toolCalls: [], finishReason: undefined }

        const modelStream = options
          .stream(request)
          .pipe(Stream.tap((event) => Effect.sync(() => accumulate(state, event))))

        const continuation = Stream.unwrap(
          Effect.gen(function* () {
            if (state.finishReason !== "tool-calls" || state.toolCalls.length === 0) return Stream.empty
            .
            .
            .
            return resultStream.pipe(Stream.concat(loop(followUpRequest(request, state, dispatched), step + 1)))
          	// loop 안에 loop
          }),
          
        )

        return modelStream.pipe(Stream.concat(continuation))
      }),
    )
.
.
.
const followUpRequest = (
  request: LLMRequest,
  state: StepState,
  dispatched: ReadonlyArray<readonly [ToolCallPart, ToolResultValue]>,
) =>
  LLMRequest.update(request, {
    messages: [
      ...request.messages,
      Message.assistant(state.assistantContent),
      ...dispatched.map(([call, result]) => Message.tool({ id: call.id, name: call.name, result })),
    ],
  })

architecture적으로 보면 아래 같은 감성입니다.

LLM stream
   ↓
tool-call 감지
   ↓
dispatch
   ↓
tool-result 생성
   ↓
followUpRequest
   ↓
다시 LLM 호출 (재귀)

권한이나 보안 시스템은 스킵하겠습니다.

STEP 6. SLM

tool call의 주된 루프는 이 정도고, 코드 내에 흥미로운 부분이 있습니다. opencode 내부에 SLM 맞춤 코드가 존재합니다. src/session/llm.ts(line 134) small 플래그가 있으면 경량 설정을 적용한다든가,

const base = input.small
        ? ProviderTransform.smallOptions(input.model)
        : ProviderTransform.options({
            model: input.model,
            sessionID: input.sessionID,
            providerOptions: item.options,
          })

src/provider/transform.ts(line 1186) SLM에서는 store: false로 response 저장을 안 하고, resoningEffort를 낮추거나 없애죠. gemini는 thinkingConfig라고 돼있는데 그냥 resoning과 같다 봐도 무방합니다. provider마다 이름이 다 다르지만 골자는 같습니다.

export function smallOptions(model: Provider.Model) {
  if (
    model.providerID === "openai" ||
    model.api.npm === "@ai-sdk/openai" ||
    model.api.npm === "@ai-sdk/github-copilot"
  ) {
    if (model.api.id.includes("gpt-5")) {
      if (model.api.id.includes("-chat")) {
        if (gpt5Version(model.api.id) === undefined) return { store: false }
        return { store: false, reasoningEffort: "medium" }
      }
      if (model.api.id.includes("search-api")) return { store: false }
      if (model.api.id.includes("5.") || model.api.id.includes("5-mini")) {
        return { store: false, reasoningEffort: "low" }
      }
      return { store: false, reasoningEffort: "minimal" }
    }
    return { store: false }
  }
  if (model.providerID === "google") {
    // gemini-3 uses thinkingLevel, gemini-2.5 uses thinkingBudget
    return { thinkingConfig: googleSmallThinkingConfig(model.api.id) }
  }
  if (model.providerID === "openrouter" || model.providerID === "llmgateway") {
    if (model.api.id.includes("google")) {
      return { reasoning: { enabled: false } }
    }
    return { reasoningEffort: "minimal" }
  }

  if (model.providerID === "venice") {
    return { veniceParameters: { disableThinking: true } }
  }

  return {}
}

지금까지 Opencode의 코드를 통해 데이터가 흐르는 방향과 Tool-call이 움직이는 루프를 분해해 봤습니다. 굉장히 복잡하다고 생각했는데, 굉장히 복잡하다는 생각이 듭니다. 모든 코드에 대해 완전히 이해한 것은 아니지만 대략적인 흐름과 매커니즘을 이해한 데에 의의를 두기로 합니다. 틀린 내용이 있다면 지적해주세요.

대형 모델 대신 로컬 SLM을 엔드포인트로 쓸 때는 모델 체급이 작아지는 만큼 코드가 더 똑똑해져야 합니다. 툴 스키마 매칭 상태를 칼같이 감시하고, 컨텍스트 용량을 아끼기 위해 불필요한 Reasoning 설정을 깎아내는 처절한 최적화가 필요합니다. 뼈대를 완벽히 분해했으니, 다음 [조립편]에는(글을 쓸 수 있을지 모르겠으나,) 로컬 환경에서도 가볍고 기민하게 돌아가는 우리만의 'Local SLM Tool-Call Engine'을 직접 구현해 보겠습니다.