iop/agent-roadmap/ROADMAP.md

IOP 로드맵

전체 목표

IOP(Inference Operations Platform)는 Control Plane - Edge - Node 계층 구조를 기반으로 모델 서빙과 CLI Agent/Automation 실행을 함께 운영하는 실행 오케스트레이션 플랫폼을 만든다. 내부 실행 모델은 adapter + target을 기준으로 하며, Edge가 로컬 실행 그룹의 상태와 라우팅을 소유하고 Control Plane은 Edge를 통해 시스템을 관찰하고 제어한다.

IOP는 NomadCode에 종속된 Agent Shell이 아니라, NomadCode와 외부 agent, 운영 CLI, client, 자동화 도구가 함께 소비할 수 있는 범용 추론/자동화 운영 엔진이다. 로드맵 전반에서 OpenAI-compatible API는 외부 클라이언트의 모델 기반 호출 표면으로, A2A API는 외부 agent의 agent-to-agent 작업 위임 표면으로, IOP native protocol은 운영 제어, logical session, background run, command, lifecycle event, remote terminal session 같은 IOP 고유 기능의 기준으로 둔다. OpenAI-compatible API는 현재 chat completions baseline을 넘어 Responses API 호환 표면까지 지원해야 한다. IOP의 외부 실행 호출 계약은 OpenAI-compatible API 방식을 기본 표면으로 채택하고, IOP 고유의 workspace, session, agent, approval, artifact, notification 의미는 별도 iop wrapper field가 아니라 metadata 또는 IOP native endpoint의 명시 필드로 전달한다. IOP native protocol은 proto-socket을 기본으로 하며, HTTP는 OpenAI-compatible/A2A/health/bootstrap처럼 필요한 경계에서만 사용한다. A2A는 표면으로 유지하되, NomadCode가 A2A를 도입하는 시점은 현재 확정하지 않는다. 현재 제1 active delivery는 NomadCode가 IOP를 실행 백엔드로 사용할 수 있도록 OpenAI-compatible Responses 요청의 metadata.workspace, task/source metadata, 내부 workspace-bound agent 실행 경로를 먼저 안정화하는 것이다.

모델 선택, 로컬/클라우드 라우팅, 모델별 profile, token/속도/품질 최적화, 모델 호출 로그와 품질 평가는 IOP 책임으로 둔다. 특히 로컬 모델을 우선 활용하되, cloud fallback과 품질 평가를 결합해 엔터프라이즈 모델 서비스에 가까운 운영 품질을 목표로 한다. RAG, context 구성/압축, web search, MCP 정책, tool policy, output validation, retry/fallback은 기본 모델 서빙과 부하 라우팅이 가능해진 뒤 확장한다.

Phase 흐름

위에서 아래로 진행된 순서와 예정 흐름을 나타낸다. 완료된 Phase도 로드맵에서 제거하지 않고, archive의 Phase 문서로 연결한다. 완료, 검토중, 진행중, 계획 순서로 두어 아래로 갈수록 미래 작업에 가까워지게 정렬한다.

• [완료] Edge-Node 실행 기반

  • 경로: agent-roadmap/archive/phase/edge-node-execution-foundation/PHASE.md
  • 요약: Edge-Node 소켓 실행 경로, Node adapter execution, CLI session, 최소 외부 입력 표면을 안정화한 단계다.

• [완료] Ollama 서빙 안정화 기반

  • 경로: agent-roadmap/archive/phase/serving-routing-optimization/PHASE.md
  • 요약: Edge OpenAI-compatible API에서 Node의 Ollama adapter를 호출하는 E2E 경로를 실제 Ollama endpoint와 split-host 환경에서 안정화했다. 추가 provider, 표준화, 후속 최적화 계층은 후속 Phase로 넘긴다.

• [완료] Control Plane과 Client 운영

  • 경로: agent-roadmap/archive/phase/control-plane-portal-ops/PHASE.md
  • 요약: 여러 Edge를 관찰하고 운영하는 중앙 제어면과 Flutter client 운영면을 구축하는 단계다.

• [진행중] Automation Runtime과 Bridge 확장

  • 경로: agent-roadmap/phase/automation-runtime-bridge/PHASE.md
  • 요약: Runtime과 Automation 실행 흐름을 공통화하고, NomadCode 지원을 위한 OpenAI-compatible workspace agent 실행 계약을 최우선으로 닫은 뒤 generic boundary 정리, bootstrap/enrollment, message boundary와 agentless remote terminal bridge를 분리해 확장하는 단계다.

• [진행중] 추론 서버 provider 확장

  • 경로: agent-roadmap/phase/inference-provider-extension/PHASE.md
  • 요약: NomadCode workspace 실행 계약이 닫힌 뒤 Ollama 경로 안정화 결과와 Node 단일 통로 멀티 타겟 서빙 기반을 기준선으로 삼아, provider 공통 상태 확인과 capacity queue 기반을 먼저 정리한 뒤 Lemonade를 우선 provider로 올리고 이후 vLLM/SGLang 같은 추가 provider의 adapter/config/target/model 매핑 표준선을 정리하는 단계다.

• [계획] 지식과 도구 최적화 확장

  • 경로: agent-roadmap/phase/knowledge-tool-optimization-extension/PHASE.md
  • 요약: Ollama serving 경로, 추가 provider 경로, 운영 기반이 안정화된 뒤 RAG, context 구성/압축, web search, MCP/tool policy, output validation, retry/fallback을 IOP 추론 최적화 계층으로 확장하는 단계다.

로딩 정책

• 일반 작업에서는 agent-roadmap/ROADMAP.md를 매번 읽지 않는다.
• 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 agent-roadmap/current.md를 먼저 읽는다.
• current.md는 현재 작업 위치가 아니라 활성 Phase와 활성 Milestone 후보 목록이다.
• current.md에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다.
• current.md의 활성 Phase는 실제 활성 Phase 문서 경로를 가리킨다.
• current.md의 활성 Milestone은 실제 활성 Phase 하위의 Milestone 문서 경로를 가리킨다.
• current.md는 agent-roadmap/archive/** 경로를 활성 항목으로 포함하지 않는다.
• 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Phase와 Milestone 문서를 같은 세션에서 1회 읽는다.
• 활성 Phase 또는 Milestone 밖의 작업이면 이 문서의 Phase 흐름을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다.
• 이 문서는 로드맵 생성/갱신, Phase 전환, Phase 추가/수정, 전체 구조 변경 요청이 있을 때만 읽는다.
• 상세 작업은 각 Milestone 문서의 기능으로 관리한다. 검증이 필요한 기능만 같은 Task 안에 검증:으로 통합한다.
• 모든 기능 Task와 Task 안에 명시된 검증이 충족된 Milestone은 먼저 [검토중]으로 두고, 사용자 완료 확인과 archive 승인을 받은 뒤 [완료]로 전환한다.
• 완료된 Phase는 archive Phase 문서 경로로 이동하고, 하위 Milestone도 같은 archive Phase scaffold 아래에 둔다.
• 진행중 Phase 안에서 완료된 Milestone은 활성 Phase 문서에 짧은 링크를 남기고, 상세 문서는 해당 archive Phase 하위 milestones/ 경로로 이동한다.
• archive PHASE.md는 Phase 자체가 완료 또는 폐기될 때만 만들며, 진행중 Phase의 완료 Milestone만 archive된 경우 archive Phase 디렉터리에 milestones/만 있을 수 있다.
• agent-roadmap/archive/**는 일반 작업에서 읽지 않는다. 과거 완료 내용, 완료 근거, 복원, 비교가 필요한 경우에만 ROADMAP.md 또는 PHASE.md의 archive 링크를 따라가서 읽는다.
• 아카이브된 Phase/Milestone 문서는 최신 템플릿이나 스킬 규약에 맞춰 재포맷하지 않는다.
• 선택된 Milestone의 구현 잠금 섹션이 없거나 상태가 잠금이면 코드 구현, agent-task 구현 계획 생성, 세부 API/파일 구조 확정을 시작하기 전에 현재 요청에 직접 영향을 주는 결정 필요 항목만 확인한다.
• 현재 요청과 직접 관련 없는 미정 항목은 잠금 상태로 남겨도 되며, 기존 구조/도메인 rule/플랫폼 관례로 정할 수 있는 작업은 표준선으로 기록하고 진행할 수 있다.
• Milestone 전체에서 사용자만 결정할 항목이 더 이상 없고 에이전트가 표준선에 따라 실행하면 되는 상태라면 구현 잠금 상태를 해제로 둔다.