73 lines
5.4 KiB
Markdown
73 lines
5.4 KiB
Markdown
---
|
|
domain: agent
|
|
last_rule_review_commit: 67d7b6e411b8a28d6d42cac550a29872a7ef6b7e
|
|
last_rule_updated_at: 2026-06-01
|
|
---
|
|
|
|
# agent
|
|
|
|
## 목적 / 책임
|
|
|
|
OTO Edge 서버에 CLI 기반 agent 노드를 등록하고, agent 실행에 필요한 config 파싱, Edge endpoint 해석, protobuf 등록 요청, bootstrap 스크립트를 담당한다.
|
|
파이프라인 실행 엔진이나 scheduler 등록 정책이 아니라 `oto agent run --config <path>` 실행 흐름과 Edge 연결 초기화가 이 도메인의 책임이다.
|
|
|
|
## 포함 경로
|
|
|
|
- `lib/cli/commands/command_agent.dart` — `agent run --config <path>` CLI 표면과 오류 출력
|
|
- `lib/oto/agent/` — agent config, runner, Edge 등록 client, generated protobuf 런타임 코드
|
|
- `assets/script/shell/oto_agent_bootstrap.sh` — Linux agent 다운로드, config 생성, background 실행 bootstrap
|
|
|
|
## 제외 경로
|
|
|
|
- `lib/cli/cli.dart` — 일반 CLI 출력/초기화 (`cli` 도메인)
|
|
- `lib/cli/commands/command_catalog.dart` — command catalog 출력 (`cli` 도메인)
|
|
- `lib/cli/commands/command_validate.dart` — pipeline YAML 검증 (`cli`/`core` 도메인)
|
|
- `lib/cli/commands/command_scheduler.dart` — scheduler 명령 진입 (`scheduler` 도메인)
|
|
- `lib/oto/application.dart` — pipeline build 오케스트레이션 (`core` 도메인)
|
|
- `lib/oto/pipeline/` — pipeline workflow 실행 (`pipeline` 도메인)
|
|
- `lib/oto/commands/` — pipeline에서 호출되는 커맨드 구현체 (`command` 도메인)
|
|
- `assets/script/`의 기타 build/package helper — CLI/배포 보조 asset (`cli` 도메인)
|
|
|
|
## 주요 구성 요소
|
|
|
|
- `CommandAgent` — `agent` CLI subcommand 파싱, config 로딩, runner 호출, exit code 처리
|
|
- `AgentConfig` / `AgentIdentityConfig` / `EdgeConnectionConfig` / `AgentRuntimeConfig` — agent bootstrap YAML 구조와 필수 필드 검증
|
|
- `AgentConfigException` — config 파일/필드/타입 오류 표현
|
|
- `AgentRunner` / `DefaultAgentRunner` — Edge 등록 workflow 실행과 결과 로그 출력
|
|
- `RegistrationException` — Edge 등록 거절 또는 연결 실패 표현
|
|
- `EdgeEndpoint` — Edge URL host/port 정규화와 기본 포트 결정
|
|
- `EdgeRegistrationClient` — `proto_socket` 기반 RegisterRequest 전송
|
|
- `RegistrationResult` — RegisterResponse accepted/rejected 결과 변환
|
|
- `_OtoIopClient` — agent iop protobuf message registry를 가진 proto_socket client
|
|
- `lib/oto/agent/iop/*.pb*.dart` — `iop/runtime.proto` generated protobuf 코드
|
|
- `lib/oto/agent/google/protobuf/*.pb*.dart` — `google/protobuf/struct.proto` generated protobuf 코드
|
|
- `oto_agent_bootstrap.sh` — agent config 파일 생성, 권한 설정, background 실행 bootstrap
|
|
|
|
## 유지할 패턴
|
|
|
|
- `CommandAgent`는 subcommand/argument 파싱과 출력만 담당하고, config 파싱은 `AgentConfig`, 등록 실행은 `AgentRunner`에 위임한다.
|
|
- `--config <path>`와 `--config=<path>` 형식을 모두 유지하고, 누락/알 수 없는 인자는 실행 전에 오류 처리한다.
|
|
- `AgentConfig`는 YAML root와 `agent`, `edge`, `runtime` section이 map인지 확인한 뒤 required string을 검증한다.
|
|
- agent config의 required field는 빈 문자열을 거부하고, optional `agent.alias`는 누락 시 `null`, 빈 문자열이면 빈 문자열로 보존한다.
|
|
- `EdgeEndpoint.parse()`는 scheme 없는 host도 허용하고, port가 없으면 https는 443, 그 외는 80을 기본값으로 둔다.
|
|
- Edge 등록 통신은 `EdgeRegistrationClient.register()`에서 열고 `finally`에서 client를 닫는다.
|
|
- RegisterResponse 변환은 `RegistrationResult.fromResponse()`에 모아 accepted/rejected와 runtime config 추출을 한 곳에서 처리한다.
|
|
- generated protobuf 파일은 직접 수정하지 않고 원본 proto와 생성 절차를 확인해 재생성한다.
|
|
- bootstrap 스크립트는 `--release-base-url`에 https만 허용하고, 생성한 config 파일은 `chmod 600`을 유지한다.
|
|
- agent 변경 후 `dart analyze`와 agent 관련 테스트(`test/oto_agent_*`, 필요 시 `test/oto_iop_connection_smoke_test.dart`)를 확인한다.
|
|
|
|
## 다른 도메인과의 경계
|
|
|
|
- **cli**: `bin/main.dart` 등록과 일반 출력/스타일은 cli 도메인이다. `CommandAgent` 내부의 agent subcommand 정책부터는 agent 도메인이다.
|
|
- **core/pipeline/command**: agent 등록은 pipeline build 실행과 별개다. agent 도메인에서 `Application.build()`, `Pipeline.pipelineInitialize()`, `Command.byType()`을 직접 호출하지 않는다.
|
|
- **scheduler**: scheduler는 YAML 파이프라인을 cron/interval로 실행한다. agent bootstrap의 background 실행과 scheduler 등록/로그 정책을 섞지 않는다.
|
|
- **framework**: `proto_socket`, `protobuf`, `fixnum` dependency 선언은 framework 도메인에서 관리하고, Edge protocol 사용 방식은 agent 도메인에서 관리한다.
|
|
- **sample**: agent config YAML은 pipeline sample YAML이 아니다. `assets/yaml/sample/**`에 agent bootstrap config를 섞지 않는다.
|
|
|
|
## 금지 사항
|
|
|
|
- agent 도메인에서 pipeline workflow나 command catalog를 직접 실행/해석하지 않는다.
|
|
- enrollment token, generated config, Edge 응답 중 민감 정보가 로그에 노출되도록 하지 않는다.
|
|
- generated protobuf 파일을 수동 편집하지 않는다.
|
|
- bootstrap 스크립트에서 사용자가 지정한 config/log/workspace 경로 외 임의의 프로젝트 파일을 수정하지 않는다.
|
|
- agent background 실행 정책을 scheduler 등록/해제 로직에 섞지 않는다.
|