이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문
HTTP와 OpenAPI 호환성
상태: 활성 범위: 현재 상태 최종 검토: 2026-09-02 담당: ax-code sdk
AX Code에는 두 가지 통합 경로가 있습니다.
아래 JSR 패키지 이름은 릴리스 준비가 되었지만 아직 첫 공개 버전을 받지 않았습니다.
- 자사 TypeScript와 JavaScript 앱 통합에는
@defai-digital/ax-code-sdk을 사용합니다. - 자사 앱과 데스크톱 GUI 작업에는
@defai-digital/ax-code-sdk/headless또는@defai-digital/ax-code-sdk/grpc를 사용합니다. - 다른 언어나 호환 프로세스 경계가 필요하면
ax-code serve과 OpenAPI 계약을 사용합니다. - AX Code가 전송의 양쪽을 모두 소유하는 자사 데스크톱 GUI 작업에는 네이티브 SDK 전송을 사용합니다.
HTTP/OpenAPI 경로는 호환과 생성된 클라이언트를 위한 기반입니다. Python, Go, Java, Rust와 그 밖의 클라이언트가 같은 서버 API를 호출하게 하며, AX Code가 모든 언어의 완전한 공식 패키지를 유지하겠다고 약속하지는 않습니다. gRPC/네이티브 계약을 쓸 수 있을 때 자사 데스크톱 GUI 안의 선호되는 특권 브리지로 보지 마십시오. 더 이상 자사 JavaScript SDK 하위 경로로 노출되지도 않습니다.
경로를 고릅니다
| 필요 | 권장 경로 | 이유 |
|---|---|---|
| 같은 프로세스의 TypeScript나 JavaScript | 소스 작업 공간 createAgent() 어댑터 |
비공개 AX Code 런타임 소스 패키지를 의도적으로 해석할 수 있을 때만 사용 가능 |
| 자사 데스크톱/네이티브 GUI | @defai-digital/ax-code-sdk/grpc |
더 좁은 헤드리스 계약, 서버 스트리밍, 메타데이터와 기한에 유리하고 WebView 노출이 적음 |
| 로컬 백엔드가 있는 TypeScript나 JavaScript | @defai-digital/ax-code-sdk/headless |
전체 HTTP SDK 표면을 노출하지 않고 수명 주기와 이벤트 투영을 형식 있게 유지 |
| Python, Go, Java, Rust, 또는 다른 런타임 | packages/sdk/openapi.json에서 클라이언트 생성 |
언어마다 자사 패키지 유지보수를 더하지 않고 HTTP 계약을 재사용 |
| CI, 자동화, 일회성 스크립트 | ax-code serve에 대한 HTTP 호출 |
단순한 배포 모델과 쉬운 프로세스 격리 |
오늘 공식인 것
@defai-digital/ax-code-sdk는 자사 TypeScript와 JavaScript SDK입니다. 공개 앱 경계는headless과grpc입니다.@defai-digital/ax-code-sdk/grpc는 자사의 선택적 데스크톱/네이티브 헤드리스 전송 퍼사드입니다.@defai-digital/ax-code-sdk/headless은 로컬 백엔드 프로세스 경계를 위한 자사 TypeScript와 JavaScript 수명 주기/이벤트 SDK입니다.packages/sdk/openapi.json는 생성된 HTTP 클라이언트를 위한 OpenAPI 스냅샷입니다.- 생성된 JavaScript가 아닌 클라이언트는 HTTP 위의 통합으로 지원되지만, 패키지 담당자, 시험, 릴리스 워크플로가 없으면 자사 게시 패키지가 아닙니다.
기본 HTTP 흐름
서버를 시작합니다.
export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096@defai-digital/ax-code-sdk/headless 수명 주기 도우미는 일회용 Basic Auth 비밀번호를 만들고, 반환된 클라이언트를 일치하는 Authorization 헤더로 자동 연결합니다. 수동 ax-code serve 사용자는 AX_CODE_SERVER_PASSWORD을 명시적으로 설정하고 해당하는 Basic Auth 헤더를 보냅니다. /doc의 실시간 OpenAPI 문서와 모든 서버 엔드포인트는 루프백 전용입니다.
SDK가 관리하는 백엔드 도우미는 0.0.0.0 같은 네트워크 호스트 이름을 항상 거부합니다. 이전 allowNetworkBind 옵션은 소스 호환을 위해 남아 있지만 더 이상 로컬 전용 정책을 우회하지 않습니다. 데스크톱 GUI 셸은 @defai-digital/ax-code-sdk/grpc나 프로세스 안 SDK 경계를 선호해야 합니다.
HTTP 런타임 도우미는 더 이상 공개 JavaScript SDK 하위 경로가 아닙니다. @defai-digital/ax-code-sdk/headless, gRPC HTTP 폴백, 이전 AX Code 런타임 코드가 쓰기 때문에 패키지에는 생성된 클라이언트 내부가 아직 들어 있습니다. 외부 통합은 @defai-digital/ax-code-sdk에서 HTTP 런타임 값을 가져오지 말고, 헤드리스, gRPC, 또는 OpenAPI 스냅샷에서 생성한 클라이언트를 사용해야 합니다.
서버 건강을 확인합니다.
curl http://127.0.0.1:4096/global/health스냅샷을 JSON과 OpenAPI로 검증한 뒤 OpenAPI 스냅샷에서 클라이언트를 생성합니다.
openapi-python-client generate --path packages/sdk/openapi.jsonoapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.goopenapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java생성 가드레일
OpenAPI 문서를 언어 중립 계약으로 취급합니다. 작은 사용성 계층이 필요하지 않다면 개별 경로를 감싸는 큰 래퍼를 손으로 유지하지 마십시오.
AX Code 버전과 생성된 클라이언트 버전을 함께 고정합니다. 서버 경로 스키마가 바뀌면 클라이언트를 다시 생성하고, 명확한 호환 메모와 함께 릴리스합니다.
생성된 코드를 손으로 쓴 도우미와 분리합니다. 생성된 파일은 바꾸기 쉬워야 하고, 손으로 쓴 파일은 인증, 기본값, 재시도, 더 높은 수준의 편의 API만 담아야 합니다.
서비스 경계 동작을 유지합니다. JavaScript가 아닌 클라이언트는 HTTP 서버 경로를 사용하며, 프로세스 안의 createAgent(), JavaScript 사용자 정의 도구 실행, @defai-digital/ax-code-sdk/testing 유틸리티를 받지 않습니다.
생성된 클라이언트를 자사 상태로 올리기 전에 어려운 부분을 다룹니다.
- OpenAPI 검증이 CI에서 실행됩니다.
- 계약 시험이
ax-code serve을 시작하고 대표적인 경로를 호출합니다. - 클라이언트가 이벤트 API를 노출하면 스트리밍이나 SSE 동작을 시험합니다.
- 디렉터리 범위 헤더와 인증 동작을 문서화합니다.
- 게시, 버전 관리, 소유가 명시적입니다.
SDK 패키지에는 현재 스냅샷을 위한 가벼운 로컬 가드가 있습니다.
pnpm run check:openapiSDK 패키지 안에서 작업할 때는 패키지 수준 명령도 사용할 수 있습니다.
pnpm --dir packages/sdk/js run validate:openapi이것은 packages/sdk/openapi.json이 파싱 가능한 JSON인지, OpenAPI 3.x를 선언하는지, 생성된 클라이언트에 필요한 핵심 경로를 포함하는지 검증합니다.