로컬 에이전트에 작업 맡기기

OS가 managed Linux Workspace에서 에이전트를 설치·기동하고, endue AI 또는 외부 클라이언트가 API로 작업을 맡겨요. OpenCode는 HTTP, Claude Code는 Agent SDK, OpenClaw와 Hermes는 ACP를 사용해요. 에이전트의 서버 포트를 외부에 공개하지 않아요.

준비

listLocalAgentCatalog로 고정 버전 카탈로그를 읽어요.
installLocalAgent에 slug를 전달해 설치해요. 가능한 값은 opencode, claude-code, openclaw, hermes예요. 반환된 명령과 설치 프로세스가 성공할 때까지 기다리세요.
모델 API 키를 Station Secret에 저장하고, 해당 Workspace의 use 권한과 Secret 참조 이름을 설정해요.
모델 ID와 호환 공급자의 HTTPS base_url을 정해요. Claude Code에서 URL을 생략하면 Anthropic API를 사용해요. Claude 계정 로그인 세션은 사용하지 않아요.

설치에는 네트워크와 저장 공간이 필요해요. 버전과 npm 잠금 파일, Hermes 소스·런타임 체크섬은 이미지에 고정돼요. 여러 에이전트를 실행할 Workspace는 메모리 4GB 이상을 권장해요.

세션 만들기

SDK 예시예요. REST와 MCP에서도 같은 작업 이름과 입력을 사용해요.

const created = await os.call('createLocalAgentSession', {
  workspace_id: ws,
  body: {
    slug: 'opencode',
    model: 'your-model-id',
    base_url: 'https://your-provider.example/v1',
    credential_name: 'MODEL_API_KEY',
    cwd: '.',
    permission: 'workspace_write',
  },
  idempotency_key: 'agent-session-1',
});

응답은 명령 봉투예요. 202면 getCommand로 완료를 기다린 뒤 getCommandOutput으로 출력을 읽어요. 명령 출력의 session_id를 저장하세요. 세션은 starting으로 시작해요. getLocalAgentSession으로 ready가 된 것을 확인한 다음 일을 맡겨요. failed이면 설치·Secret 권한·모델 설정을 확인하세요. 실제 Secret 값은 Workspace에서 일회용 Vault 토큰을 교환해 얻으며 명령 인자로 전달하지 않아요.

permission의 기본값은 read_only예요. 파일 편집·명령 실행을 맡길 때 workspace_write를 명시하세요. 작업 범위는 해당 Workspace이며, 네트워크는 managed Workspace의 정책을 따라요. cwd는 Workspace 내부 경로여야 해요.

작업·결과·취소

await os.call('promptLocalAgent', {
  workspace_id: ws, session_id: session,
  body: { prompt: '현재 프로젝트를 읽고 README의 설치 절차를 고쳐 줘.', timeout_ms: 300_000 },
});
const state = await os.call('getLocalAgentSession', {
  workspace_id: ws, session_id: session,
});

프롬프트는 즉시 실행 핸들을 돌려줘요. 세션의 run.status가 succeeded, failed, cancelled, timed_out 중 하나가 될 때까지 조회하세요. run.output은 최대 64KiB이며 잘리면 truncated: true예요. 완료 시간과 오류도 같은 결과에 들어 있어요. 세션당 한 작업만 실행하며 실행 중 추가 프롬프트는 session_busy로 거절해요.

cancelLocalAgentRun은 작업과 해당 에이전트 프로세스를 중단하고 세션을 닫아요. 새 작업은 새 세션에서 시작하세요. closeLocalAgentSession은 세션 프로세스와 임시 공급자 기록을 정리해요. 세션은 런타임당 최대 4개이며 최근 32개 상태만 보관해요. Workspace 또는 OS 런타임이 재시작되면 세션은 사라지지만 설치한 패키지는 볼륨에 남아요.

endue AI에서 사용

Workspace의 describe_tools에는 list_local_agents, install_local_agent, local_agent_create_session, local_agent_prompt, local_agent_get_session, local_agent_cancel, local_agent_close가 나와요. endue AI는 기존 Workspace 명령 경로로 호출하고 결과를 받으면 돼요. local_agent_create_session에 credential_name을 전달하면 OS가 일회용 토큰을 주입해요. 도구 호출에 credential_token을 넣지 마세요. 전용 세션 REST도 같은 Secret 권한 검사를 사용해요.

인증은 현재의 Station 키·OAuth·endue-ai-os 서비스 계정을 사용해요. 별도 에이전트 신원 체계나 디스플레이·VR 연동은 이 기능에 포함되지 않아요.