58일차 회고｜Handoff·State·CI/CD·AWS 배포｜AI 오케스트레이션 개발자 국비지원

 

오늘은 멀티 에이전트의 실행 흐름을 관리하는 방법에서 한 단계 더 나아가, 실제로 만든 서비스를 어떻게 AWS에 배포하고 자동으로 관리할 것인지를 학습했다.

특히 앞에서 배운 Handoff와 State가 에이전트 실행 자체를 관리하는 개념이었다면, 오늘은 그 실행 구조를 실제 개발 환경과 CI/CD까지 연결해 보면서 “코드가 만들어진 이후 어떻게 테스트되고 서버에서 실행되는가”를 이해하는 데 초점을 맞췄다.

---

오늘 배운 내용

오늘 학습은 크게 두 가지 흐름으로 이어졌다.

하나는 멀티 에이전트 시스템 내부의 실행 관리이고, 다른 하나는 프로젝트를 실제 서비스 형태로 개발하고 배포하기 위한 환경 구성이다.

멀티 에이전트 쪽에서는 Handoff, Handoff Contract, Guard, State, Trace의 관계를 다시 연결해서 이해했다.

• Handoff: 한 Agent에서 다음 Agent로 작업과 필요한 데이터를 전달
• Handoff Contract: 어떤 데이터를 전달해야 하는지 정의
• Validation: 데이터의 형식이나 구조가 올바른지 확인
• Guard: 데이터의 의미, 사용자 정보, 보안 문제 등을 확인
• State: 전체 실행 과정에서 현재 어떤 Agent가 실행 중이고 어디까지 진행됐는지 관리
• Trace / Run ID: 실행 기록을 추적하고 장애 상황을 확인

여기에 오늘은 AWS, Docker, GitHub Actions까지 연결하면서 이 실행 구조를 실제 프로젝트 운영 환경으로 확장했다.

---

Handoff와 State의 차이를 다시 이해했다

처음 멀티 에이전트 구조를 볼 때는 Agent 사이에 결과를 전달하면 그것만으로 전체 실행을 관리할 수 있을 것처럼 생각하기 쉬웠다.

하지만 Handoff는 기본적으로 “A Agent의 결과를 B Agent에게 어떻게 넘길 것인가”에 가까웠다.

반면 State는 전체 시스템 입장에서 현재 상황을 기록한다.

예를 들어 다음과 같은 실행이 있다고 생각할 수 있다.

Weather Agent 실행 → 성공 → Itinerary Agent 실행 → 실패

이때 Handoff만 생각하면 Weather Agent가 만든 결과를 Itinerary Agent에 전달하는 것까지는 알 수 있다.

하지만 실제 운영 환경에서는 다음과 같은 정보도 필요하다.

• 현재 어떤 Agent에서 멈췄는가?
• 앞 단계는 성공했는가?
• 오류가 발생한 단계는 어디인가?
• 다시 처음부터 실행해야 하는가?
• 실패한 단계부터 다시 실행할 수 있는가?

이런 정보를 관리하기 위해 State가 필요하다는 것을 이해했다.

또한 프로그램 내부의 State만으로 끝나는 것이 아니라 Redis나 DB 등에 Trace를 남기면 프로그램이 종료된 이후에도 실행 기록을 확인할 수 있다는 점까지 연결해서 배웠다.

---

AWS 보안 설정을 직접 확인했다

오후에는 AWS 인스턴스의 보안 그룹과 인바운드 규칙을 확인했다.

특히 포트를 열어둔다는 것이 무엇을 의미하는지를 실제 설정을 보면서 이해했다.

예를 들어 실습 환경에서는 여러 포트를 각각 다른 용도로 사용했다.

• 22 → SSH 접속
• 8501 → Streamlit 접속
• 5433 등 → PostgreSQL 접근
• 6379 → Redis
• 8000 → Backend 관련 접근

중요했던 것은 포트 번호 자체보다 어디에서 접속할 수 있도록 열어두었는가였다.

인바운드 규칙에서 0.0.0.0/0처럼 모든 IP에서 접근할 수 있도록 설정하면 인터넷 어디에서든 해당 포트로 접근할 수 있다.

따라서 필요한 경우가 아니라면 특정 IP만 허용하는 것이 안전하고, 실습이 끝난 뒤에는 불필요하게 외부에 열린 포트를 그대로 두지 않는 것이 중요하다는 설명을 들었다.

이번 내용을 통해 AWS 보안 설정은 단순히 “접속이 되게 만드는 설정”이 아니라 누가 어떤 경로로 서버에 접근할 수 있는지를 결정하는 설정이라는 점을 다시 확인했다.

---

Docker로 PostgreSQL과 Redis 실행

AWS 인스턴스에서 기존 Docker 환경을 정리한 뒤 PostgreSQL과 Redis 컨테이너를 다시 실행하는 과정도 진행했다.

여기서 기억해야 했던 부분은 컨테이너 내부 포트와 외부에서 접근하는 포트가 다를 수 있다는 것이었다.

예를 들어 PostgreSQL 컨테이너 내부에서는 기본적으로 5432 포트를 사용하지만, 노트북에서 접근할 때는 다른 포트로 매핑할 수 있다.

이 차이를 실제 환경에서 확인하면서 Docker Compose에서 작성한 포트 설정이 왜 필요한지도 다시 이해할 수 있었다.

또한 앞으로 프로젝트를 진행할 때 데이터베이스와 Redis는 각자의 로컬 컴퓨터에 설치하기보다 실습용 AWS 인스턴스에 구성된 환경을 활용하고, 애플리케이션에서는 해당 인스턴스의 IP를 사용하도록 .env를 구성하는 방향을 안내받았다.

---

GitHub Actions로 CI/CD 흐름 확인

오늘 가장 많은 내용을 다룬 부분은 CI/CD였다.

CI/CD는 코드를 수정할 때 테스트와 배포 과정을 자동화하는 방식이다.

오늘 확인한 전체 흐름은 다음과 같았다.

Git Push → GitHub Actions → CI → 테스트 → Docker 이미지 빌드 → CD → AWS 파일 복사 → Docker Compose 실행

CI 단계에서는 단순히 코드를 서버에 올리는 것이 아니라 먼저 프로젝트가 정상적으로 동작할 수 있는지를 확인한다.

실습에서는 다음과 같은 과정이 연결됐다.

1. 프로젝트 설정 확인
2. 테스트 실행
3. Docker 이미지 빌드
4. CI 성공
5. AWS 인스턴스로 파일 복사
6. Docker Compose 실행
7. 컨테이너 실행 확인
8. AWS IP와 포트로 서비스 접속

특히 테스트는 CI에서 중요한 첫 단계라는 점을 강조해서 들었다.

코드가 작성됐다는 이유만으로 바로 배포하는 것이 아니라 기능 테스트가 통과한 뒤 배포하는 구조가 필요하다는 것이다.

---

실제로 발생한 문제: AWS 인스턴스 IP 변경

오늘 실습에서 가장 기억에 남은 문제는 AWS 인스턴스를 껐다가 다시 실행하면서 발생한 IP 변경 문제였다.

기존 GitHub Actions 설정에는 이전 AWS 인스턴스의 IP가 등록되어 있었는데, 인스턴스를 다시 실행하면서 새로운 IP가 할당됐다.

결과적으로 GitHub Actions가 이전 IP로 파일을 복사하려고 하면서 배포 과정에서 문제가 발생했다.

이 과정을 통해 단순히 GitHub Actions의 YAML 파일만 이해하는 것과 실제 배포 환경을 이해하는 것은 다르다는 것을 느꼈다.

CI/CD가 정상적으로 동작하려면 최소한 다음 정보들이 서로 맞아야 한다.

• GitHub Repository
• GitHub Actions Workflow
• Environment
• AWS 인스턴스
• Host/IP
• SSH 인증 정보
• 배포 디렉터리
• Docker Compose

AWS 인스턴스의 IP 하나가 바뀌는 것만으로도 자동 배포가 실패할 수 있다는 것을 직접 확인한 것이었다.

---

GitHub Actions Environment도 이해하게 됐다

GitHub Actions에서는 production과 같은 Environment를 설정하고, 해당 Environment에 서버 접속 정보를 등록할 수 있었다.

여기서 중요한 것은 Environment 이름이 단순한 이름이 아니라 Workflow와 실제 배포 환경을 연결하는 역할을 한다는 것이었다.

Workflow에서는 특정 Environment를 지정하고, 해당 환경에 설정된 Host나 SSH 관련 정보를 이용해 AWS 서버에 배포하게 된다.

따라서 서버가 여러 개로 늘어난다면

• production
• staging
• development

등 여러 환경을 분리해 관리하는 것도 가능하다는 구조를 이해했다.

---

프로젝트 구조도 서비스별로 분리하기 시작했다

오늘 후반부에는 앞으로 진행할 프로젝트의 개발 환경을 Frontend / Backend / MCP Server로 분리하는 방향을 배웠다.

기존에는 하나의 프로젝트 안에서 여러 서비스가 함께 관리되는 구조였다면, 앞으로는 각각 독립적인 개발 환경을 갖도록 구성한다.

예를 들어,

project/
├── frontend/
├── backend/
└── mcp-server/

각 디렉터리마다 필요한 환경과 패키지를 독립적으로 관리하는 방식이다.

특히 .env도 하나로 공유하는 것이 아니라 각각의 서비스에 맞게 분리한다.

이렇게 하면 MCP Server 담당자가 자신의 환경을 수정하더라도 Frontend나 Backend의 개발 환경에 영향을 주는 일을 줄일 수 있다.

---

CI도 디렉터리 단위로 분리한다

환경을 분리하는 것에서 끝나는 것이 아니라 CI/CD도 서비스별로 분리하는 방향을 배웠다.

예를 들어 MCP Server만 수정했다면 전체 프로젝트의 CI를 실행하는 것이 아니라 MCP Server에 대한 CI만 실행하도록 만드는 것이다.

마찬가지로 Frontend만 변경했다면 Frontend CI만 실행하고, Backend만 변경했다면 Backend CI만 실행하는 구조다.

최종적으로는 다음과 같은 형태를 목표로 한다.

MCP Server 변경
    ↓
MCP Server CI
    ↓
MCP Server 서버 배포

Frontend 변경
    ↓
Frontend CI
    ↓
Frontend 서버 배포

Backend 변경
    ↓
Backend CI
    ↓
Backend 서버 배포

오늘은 우선 각 디렉터리별 CI를 분리하는 것을 1차 목표로 잡았고, 이후에는 각각 다른 서버로 배포하는 구조까지 확장할 예정이다.

---

오늘 새롭게 이해한 점

오늘 가장 크게 달라진 부분은 멀티 에이전트 개발을 단순히 Agent와 Agent의 연결로만 보면 안 된다는 것이었다.

처음에는 Agent를 만들고 서로 결과를 전달하면 멀티 에이전트 시스템이 완성되는 것처럼 생각했다.

하지만 실제로 프로젝트를 운영하려면 그 뒤에 훨씬 많은 요소가 필요하다.

Agent 실행

→ Handoff

→ Contract / Guard

→ State

→ Trace

→ 테스트

→ Docker

→ CI/CD

→ AWS 배포

→ 서비스별 분리

까지 이어진다.

특히 오늘 AWS와 GitHub Actions를 직접 연결하면서 “코드를 작성하는 것”과 “작성한 코드를 지속적으로 테스트하고 실제 서버에서 실행하는 것”은 별개의 문제라는 점을 이해하게 됐다.

---

아직 부족한 부분

아직 CI/CD 전체 구조를 혼자 처음부터 설계할 수 있는 수준은 아니다.

특히 다음 부분은 더 복습해야 할 것 같다.

• GitHub Actions YAML 구조
• Environment와 Secrets의 관계
• SSH를 이용한 원격 배포 과정
• Docker Compose와 배포 서버의 관계
• AWS 보안 그룹과 포트 설정
• 서비스별 CI 분기 조건
• 여러 서버로 분리 배포하는 방법
• 배포 과정에서 발생하는 오류 추적

오늘처럼 IP가 변경되거나 설정값 하나가 달라졌을 때 어느 부분을 먼저 확인해야 하는지도 더 익숙해질 필요가 있다.

---

오늘의 회고

오늘은 멀티 에이전트의 내부 실행 흐름을 이해하는 것에서 한 단계 더 나아가, 실제 프로젝트를 개발하고 배포하는 전체 흐름을 연결해서 볼 수 있었던 날이었다.

특히 Handoff와 State를 배우면서 “Agent 간 데이터를 전달하는 것”과 “전체 실행 상태를 관리하는 것”이 다르다는 것을 이해했고, 이후 AWS와 CI/CD를 실습하면서 이러한 관리 개념이 실제 서비스 운영 환경과도 연결된다는 것을 알게 됐다.

또한 AWS 인스턴스의 IP가 변경되면서 CI/CD가 실패하는 과정을 직접 경험한 것도 의미가 있었다. 단순히 코드를 잘 작성하는 것뿐 아니라 서버, 환경 변수, 인증 정보, 네트워크, 배포 설정이 모두 맞물려 있어야 자동화된 개발 환경이 제대로 동작한다는 것을 확인했다.

앞으로는 Frontend, Backend, MCP Server를 각각 독립적인 개발 환경으로 분리하고, 변경된 영역만 CI가 실행되도록 만드는 과정까지 직접 구성해 보면서 지금까지 배운 내용을 실제 프로젝트 구조에 적용해 보는 것이 다음 목표다.

---

핵심 정리

• Handoff는 Agent 간 데이터와 작업을 전달한다.
• State는 전체 멀티 에이전트 실행 상태를 관리한다.
• Trace와 Run ID는 실행 과정을 추적하고 장애 상황을 확인하는 데 활용한다.
• AWS 보안 그룹에서는 필요한 포트만 제한적으로 열어야 한다.
• Docker를 이용해 PostgreSQL과 Redis 등의 실행 환경을 구성할 수 있다.
• CI는 테스트와 이미지 빌드 등을 통해 배포 전 상태를 검증한다.
• CD는 검증된 결과를 AWS 서버에 전달하고 실제 컨테이너를 실행한다.
• AWS 인스턴스 IP가 변경되면 자동 배포 설정도 함께 확인해야 한다.
• 앞으로는 Frontend / Backend / MCP Server를 독립적인 개발 환경과 CI/CD 구조로 분리한다.