oto/agent-ops/rules/project/domain/agent/rules.md

domain	last_rule_review_commit	last_rule_updated_at
agent	67d7b6e411	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 등록/해제 로직에 섞지 않는다.