저는 규모가 크면서도 에이전트 기반 소프트웨어 개발(agentic software development)과 직접적으로 연결된 코드베이스에서 ArchSteer를 테스트하고 싶었습니다. OpenAI의 Agents SDK for Python은 명백한 선택지였습니다. 이 프로젝트는 활발하게 운영되는 오픈 소스이며, 제가 이 분석을 수행했을 당시 GitHub 스타 수가 약 27,000개에 달했습니다.

질문은 간단했습니다: 설정 없는(zero-config) 아키텍처 패스가 이토록 큰 저장소에 대해 유용한 정보를 제공할 수 있을까?

가능합니다. 또한 몇 가지 틀리는 부분도 있습니다. 두 부분 모두 살펴볼 가치가 있습니다.

Credit: 이 기사의 아키텍처 모델, 컴포넌트 인벤토리(component inventory), 의존성 수(dependency counts), 그리고 보고서는 ArchSteer 0.10.0 배포판에 의해 생성되었습니다. 저는 출력을 검토하고 해석했으며, 저장소 분석은 ArchSteer가 수행했습니다.

실행 내용

저는 2026년 7월 30일에 커밋 974733e을 분석했습니다.

git clone --depth 1 https://github.com/openai/openai-agents-python.git
cd openai-agents-python
pipx install archsteer
...

마지막 명령은 읽기 전용(read-only)입니다. 이는 저장소를 정적으로 읽고 결과를 .archsteer/ 디렉토리에 작성합니다. SDK를 실행하거나, 모델을 호출하거나, 코드를 업로드하지 않습니다.

첫 번째 패스(pass)의 결과는 다음과 같습니다:

저장소 전체 결과	ArchSteer 출력
매핑된 컴포넌트 (Components mapped)	844
...
The unedited ArchSteer report for the OpenAI Agents SDK

위 보고서는 ArchSteer의 직접적인 출력 결과입니다. 제목에 붙은 이상한 접미사는 분석에 사용된 임시 디렉토리에서 비롯되었습니다.

런타임 패키지가 더 유용한 이야기를 들려줍니다

총 844개의 컴포넌트에는 테스트, 예제, 문서 스크립트 및 저장소 도구(repository tooling)가 포함되어 있습니다. 저는 생성된 모델을 실제 배포되는 런타임 패키지인 src/agents/로 좁혔습니다.

가장 유용한 발견은 소수의 오케스트레이션 (orchestration) 파일 주변으로 아키텍처 컨텍스트 (architectural context)가 모여드는 방식이었습니다.

openai_realtime.py가 62개의 임포트 엣지 (import edges)로 목록 1위를 차지했으며, 내부 런 루프 (run loop)가 56개로 그 뒤를 이었습니다. agent.py, 도구 실행 (tool execution), 그리고 런 상태 (run state)가 근소한 차이로 뒤따랐습니다.

이것이 해당 파일들의 설계가 잘못되었다는 뜻은 아닙니다. 그곳에서의 변경은 작은 어댑터 (adapter)를 변경할 때보다 더 많은 컨텍스트 (context)가 필요하다는 것을 의미합니다. 이 파일들은 모델 제공자 (model providers), 도구 (tools), 상태 (state), 트레이싱 (tracing), 가드레일 (guardrails), 스트리밍 (streaming), 그리고 핸드오프 (handoffs)가 만나는 지점에 위치합니다.

이는 인간 리뷰어에게 유용합니다. 코딩 에이전트 (coding agent)에게는 훨씬 더 유용합니다. 만약 에이전트가 런 루프 (run loop)를 건드린다면, ArchSteer는 에이전트가 근처의 패턴을 복사하기 시작하기 전에 어떤 경계 (boundaries)와 결정 (decisions)이 중요한지 알려줄 수 있습니다.

새로운 그래프는 컴포넌트의 이웃을 구체화합니다

ArchSteer 0.10.0에는 graph 명령어가 추가되었습니다. 전체 모델을 읽는 대신, 하나의 집중된 질문을 던질 수 있습니다:

archsteer graph src/agents/agent.py

agent.py에 대해 ArchSteer는 29개의 직접적인 로컬 의존성 (direct local dependencies)과 55개의 직접적인 의존자 (direct dependents)를 보고했습니다. 두 번째 숫자는 X-ray가 저장소 전체를 포괄하기 때문에 런타임 코드 (runtime code), 테스트 (tests), 그리고 예제 (examples)를 포함합니다.

이 관점은 일반적인 복잡도 점수보다 더 실행 가능한 정보를 제공합니다. 왼쪽은 agent.py가 작동하기 위해 무엇이 필요한지를 보여줍니다. 오른쪽은 이를 변경했을 때의 영향 범위 (blast radius)를 보여줍니다. 에이전트가 이 파일을 수정하기 전에, 저는 에이전트가 이 양방향 이웃 관계를 컨텍스트로 확인하기를 원합니다.

그래프 수치는 앞서 본 임포트 엣지 (import-edge) 차트와 의도적으로 다릅니다. 해당 차트는 외부 임포트를 포함하여 파싱된 모든 임포트 엣지를 계산합니다. graph 명령은 저장소 내의 직접적인 컴포넌트들을 해석하여 양방향 의존성 방향을 모두 보여줍니다.

상태(State)와 도구 실행(tool execution)이 거버넌스의 경계선이다

가장 큰 런타임 파일들은 동일한 점을 뒷받침합니다:

• run_state.py — 3,820개의 매핑된 라인
• tool.py — 2,735개
• run_internal/tool_execution.py — 2,554개
• run_internal/turn_resolution.py — 2,500개

에이전트 프레임워크는 흔히 프롬프트 (prompts)와 핸드오프 (handoffs)의 관점에서 설명되곤 합니다. 하지만 엔지니어링의 무게 중심은 다른 곳에 있습니다: 지속 가능한 상태 (durable state), 도구 호출 소유권 (tool-call ownership), 중단 및 재개 (interruption and resumption), 프로바이더 변환 (provider translation), 에러 동작 (error behavior), 그리고 트레이싱 (tracing)입니다.

이러한 지점들이 바로 그럴듯한 패치가 좁은 테스트는 통과하면서도 아키텍처를 뒤흔들 수 있는 정확한 위치들입니다. 도구 결과가 잘못된 곳에 저장될 수 있습니다. 특정 프로바이더 전용 타입이 핵심 상태 (core state)로 유출될 수 있습니다. 새로운 실행 경로가 기존에 설정된 가드레일 (guardrail)을 건너뛸 수도 있습니다.

ArchSteer는 팀이 이러한 기대 사항들을 명시적인 규칙으로 바꿀 수 있는 방법을 제공합니다. 이러한 종류의 SDK의 경우, 유지 관리자들은 다음과 같은 규칙을 선택할 수 있습니다:

• 핵심 실행 상태 (core run state)는 구체적인 모델 프로바이더 (model provider)에 의존할 수 없다.
• 프로바이더 어댑터 (provider adapters)는 핵심 인터페이스 (core interfaces)에 의존할 수 있지만, 그 역은 불가능하다.
• 도구 실행 (tool execution)은 승인된 트레이싱 및 가드레일 경로를 반드시 거쳐야 한다.
• 세션 백엔드 (session backends)는 세션 추상화 (session abstraction) 뒤에 머물러야 한다.
• 샌드박스-프로바이더 통합 (sandbox-provider integrations)은 핵심 실행 루프 (core run loop)로 유출되지 않는다.

이 예시들은 저의 해석일 뿐, OpenAI 유지 관리자들이 선언한 규칙은 아닙니다. 중요한 점은 ArchSteer가 팀이 실제로 선택한 어떤 의도라도 검사할 수 있다는 것입니다.

첫 번째 지도는 유용했지만—분명히 불완전했습니다

이번 실행에서 나타난 솔직한 한계는 다음과 같습니다: ArchSteer는 model과 util만을 레이어(layer)로 추론했습니다. src/agents/ 내의 295개 컴포넌트 중 266개가 할당되지 않은 상태로 남았습니다.

SDK는 분명 그보다 더 풍부한 형태를 가지고 있습니다. 여기에는 핵심 에이전트 추상화 (agent abstractions), 오케스트레이션 (orchestration), 도구 (tools), 핸드오프 (handoffs), 가드레일 (guardrails), 프로바이더 (providers), 세션 (sessions), 트레이싱 (tracing), 실시간 동작 (realtime behavior), MCP 통합 (MCP integrations), 샌드박스 (sandboxes), 그리고 확장 기능 (extensions)이 포함되어 있습니다.

따라서 저는 이 2계층 다이어그램을 "OpenAI Agents SDK의 아키텍처"라고 제시하지는 않을 것입니다. 이는 이름과 코드 구조로부터 도출된 첫 번째 가설일 뿐입니다.

그럼에도 여전히 도움이 됩니다. 불완전한 지도에서 시작하는 것이 백지 상태에서 시작하는 것보다 훨씬 빠릅니다. 유지 관리자(maintainer)가 실제 경계를 한 번 정의하고 그 의도를 리포지토리(repository)와 함께 저장해 두면, ArchSteer가 코드를 그 기준에 따라 계속 비교하도록 할 수 있습니다.

데이터 저장소(data-store) 탐지 또한 노이즈를 생성했습니다. 리포지토리 전역 보고서에는 60개의 저장소 유사 신호가 나타났지만, 이 목록에는 실제 영속성 (persistence) 개념이 SQL 토큰, 변수 이름, 예제 코드와 뒤섞여 있었습니다. 이것이 SDK가 60개의 데이터베이스를 사용한다는 의미는 아닙니다.

저는 파일 수준의 증거가 가시적으로 보이는 점이 마음에 듭니다. 잘못된 양성 (false positive) 결과가 확신에 찬 점수 뒤로 사라지는 대신, 직접 검사하고 수정할 수 있기 때문입니다.

이것이 지금 중요한 이유

코딩 에이전트 (coding agents)는 로컬 일관성 (local consistency) 측면에서 매우 뛰어납니다. 이들은 수정 사항 주변의 파일들을 읽고 보이는 것을 모방합니다.

하지만 리포지토리에 서로 충돌하는 두 가지 패턴이 포함되어 있을 때 문제가 발생합니다. 절반쯤 완료된 마이그레이션 (migration)은 종종 새로운 방식보다 기존 방식의 예시를 더 많이 포함하고 있습니다. 슬라이드 덱에 있는 아키텍처 다이어그램은 에이전트가 작업 컨텍스트 (working context)에 진입하지 못한다면 아무런 도움이 되지 않습니다.

위험한 결과는 명백하게 망가진 코드가 아닙니다. 컴파일도 잘 되고 테스트도 통과하지만, 의도한 아키텍처를 조금씩 어긋나게 만드는 코드입니다.

ArchSteer는 일회성 다이어그램이 아닌 제어 루프 (control loop)를 통해 이 문제를 해결합니다:

"check" 단계는 래칫 (ratchet) 방식을 사용합니다. 팀은 이미 알려진 위반 사항을 기준점 (baseline)으로 설정하고, 순수하게 새로 발생하는 드리프트 (drift)만을 차단할 수 있습니다. 기존의 기술 부채 (debt)는 계속 가시적으로 남아있지만, 도구가 유용해지기 전에 대규모의 일시적인 정리 (big-bang cleanup)를 강요하지는 않습니다.

이 부분이 제가 에이전트 중심 개발 (agentic development)과 가장 관련이 깊다고 생각하는 ArchSteer의 특징입니다. 동일한 모델이 네 가지 순간 (moments)에 기여합니다:

이 실행이 증명하는 것 — 그리고 증명하지 못하는 것

단 한 번의 정적 엑스레이 (static X-ray)만으로는 해당 SDK가 안전한지, 신뢰할 수 있는지, 혹은 "잘 설계된 아키텍처 (well architected)"인지 알려줄 수 없습니다. Python은 동적 (dynamic)입니다. 설정 (configuration), 의존성 주입 (dependency injection), 생성된 코드 (generated code), 그리고 런타임 동작 (runtime behavior)은 어떤 정적 도구로부터도 경계 사례 (edges)를 숨길 수 있습니다.

또한 저는 유지 관리자가 작성한 의도 (maintainer-authored intent)를 적용하지 않았으므로, 여기에는 의미 있는 준수 점수 (conformance score)가 존재하지 않습니다.

이 실행이 증명한 것은 더 실용적입니다: ArchSteer는 단 한 번의 명령으로 크고 활발한 저장소 (repository)를 검사 가능한 아키텍처 데이터셋으로 변환했습니다. 아키텍처 컨텍스트 (architectural context)가 집중된 파일들을 식별하고, 향후 변경 사항을 위한 기준점 (baseline)을 생성했으며, 자동 추론 (automatic inference)의 공백을 명확하게 드러냈습니다.

이는 에이전트 중심의 개발 프로세스에서 아키텍처 작업을 시작하기 위한 신뢰할 수 있는 출발점입니다.

동일한 엑스레이 시도하기

ArchSteer는 로컬 우선 (local-first) 방식이며, 오픈 소스이고, MIT 라이선스를 따릅니다:

pipx install archsteer
cd your-repository
archsteer xray
...

가장 좋은 첫 번째 질문은 "완벽한 다이어그램을 얻었는가?"가 아닙니다. 바로 이것입니다:

ArchSteer가 보여준 것 중, 코딩 에이전트가 다음 편집을 수행하기 전에 반드시 알아야 할 것은 무엇인가?

동일한 로컬 X-레이를 실행해 보세요: ArchSteer 시작하기 · 원래 사례 연구