하이퍼라이트 CodeAct

Hyperlight는 에이전트 프레임워크의 CodeAct에 대해 현재 문서화된 백 엔드입니다. 격리된 샌드박스 런타임에 의해 지원되는 execute_code 도구를 노출하며, call_tool(...)을 통해 공급자 소유의 호스트 도구를 호출할 수 있습니다.

패턴 수준 개요는 CodeAct를 참조하세요.

하이퍼라이트 CodeAct가 왜

최신 에이전트는 종종 모델 자체보다 도구 호출 오버헤드에 의해 더 제한됩니다. 데이터를 읽고, 가벼운 계산을 수행하고, 결과를 어셈블하는 작업은 각 개별 단계가 간단한 경우에도 모델 체인인> 도구 -> 모델 -> 도구 상호 작용으로 쉽게 전환할 수 있습니다.

하이퍼라이트가 후원하는 CodeAct는 해당 루프를 중단합니다. 모델은 하나의 짧은 Python 프로그램을 작성하고, 샌드박스는 이를 한 번 실행하며, 공급자 소유의 도구는 call_tool(...)을 통해 샌드박스 내부에서 접근됩니다. 대표적인 도구가 많은 워크로드에서 이러한 전환은 실행을 격리하고 감사 가능한 상태로 유지하면서 대기 시간을 약 절반으로 줄이고 토큰 사용량을 60%초과할 수 있습니다.

Get started

곧 공개됩니다.

패키지 설치

pip install agent-framework-hyperlight --pre

agent-framework-hyperlight 는 별도로 agent-framework-core배송되므로 필요할 때만 샌드박스 런타임을 사용할 수 있습니다.

Note

패키지는 하이퍼라이트 샌드박스 구성 요소에 따라 달라집니다. 백엔드가 현재 플랫폼에 대해 아직 게시되지 않은 경우, execute_code는 샌드박스를 만들려고 할 때 실패합니다.

`HyperlightCodeActProvider` 사용

HyperlightCodeActProvider 는 각 실행에 대해 CodeAct를 자동으로 추가하려는 경우 권장되는 진입점입니다. 공급자 소유 도구를 직접 에이전트 도구 화면에서 벗어나게 하면서 실행 범위 CodeAct 명령과 execute_code 도구를 삽입합니다.

공급자에 등록된 도구는 call_tool(...)을/를 통해 샌드박스 내에서 사용할 수 있지만, 직접적인 에이전트 도구로는 노출되지 않습니다. 또한 공급자는 도구, 파일 탑재 및 아웃바운드 허용 목록 항목에 대한 CRUD 스타일 관리를 (예: add_tools(...), remove_tool(...)add_file_mounts(...)및add_allowed_domains(...)) 메서드를 통해 노출합니다.

승인 및 호스트 도구의 작동 방식

"에이전트 프레임워크 도구는 approval_mode을 사용하여 자동 호출할 수 있는지 아니면 사용자 승인 대기를 위해 일시 중지해야 하는지를 제어합니다."

도구를 HyperlightCodeActProvider 등록하고 직접 Agent(tools=...) 등록하는 경우의 주요 차이점은 Python 함수가 궁극적으로 실행되는 위치 가 아니라 도구가 호출되는 방식입니다.

등록된 HyperlightCodeActProvider(tools=...) 도구는 모델에서 직접 도구로 숨겨집니다. 모델은 call_tool("name", ...) 안에서 execute_code을 호출하는 코드를 작성하여 수행합니다.
Agent(tools=...)에 등록된 도구는 모델에 주요 도구로 인식되며, 각 직접 호출은 해당 도구의 고유 설정인 approval_mode을 존중합니다.

call_tool(...) 는 콜백을 호스트하는 브리지 백입니다. 도구의 샌드박스 내 재이미션이 아닙니다. 즉, 호스트 프로세스 자체에서 액세스할 수 있는 파일 시스템, 네트워크 및 자격 증명을 사용하여 공급자 소유 도구가 호스트 프로세스에서 계속 실행됩니다.

일반적인 원칙으로:

모델이 한 execute_code 턴 내에서 많은 호출을 작성할 수 있도록 공급자에 저렴하고 결정적이며 안전한 체인 도구를 배치합니다.
부작용이 있거나 승인 제어가 필요한 작업은 보통 approval_mode="always_require"를 사용하여 직접 에이전트 도구로 유지합니다. 이렇게 하면 각 호출이 개별적으로 표시되고 승인될 수 있습니다.

호스트 도구는 샌드박스 외부에서 실행되며, file_mounts 및 allowed_domains는 호스트 콜백 call_tool(...)의 뒤가 아니라 샌드박스 코드 자체를 제한합니다. 중요한 리소스에 대한 제어된 액세스가 필요한 경우 샌드박스 권한 확대보다 좁은 호스트 도구를 선호합니다.

Note

call_tool(...) 통해 호출된 도구는 네이티브 Python 값(dict, list, 기본 개체 또는 사용자 지정 개체)을 게스트에 직접 반환합니다. A에 result_parser 구성된 모든 FunctionTool 구성은 LLM 연결 소비자를 위한 것이며 샌드박스 경로에서 실행되지 않습니다. 샌드박스 내 소비자에게 필요한 경우 도구 함수 자체 내에서 서식을 적용합니다.

직접 배선에 사용 `HyperlightExecuteCodeTool`

동일한 에이전트에서 직접 전용 도구와 execute_code를 함께 사용해야 하는 경우에는 공급자 대신 HyperlightExecuteCodeTool를 사용하세요. 고정 구성의 경우 CodeAct 지침을 한 번 빌드하고 도구를 직접 연결할 수 있습니다.

from agent_framework_hyperlight import HyperlightExecuteCodeTool

execute_code = HyperlightExecuteCodeTool(
    tools=[compute],
    approval_mode="never_require",
)

codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)

이 패턴은 CodeAct 화면이 고정되어 있고 모든 실행 시 공급자 수명 주기가 필요하지 않은 경우에 유용합니다. 독립형 HyperlightCodeActProvider 도구는 프롬프트 지침을 자동으로 삽입하지 않으므로, 에이전트 지침에 build_instructions(...) 출력을 직접 추가할 책임이 있습니다.

파일 및 아웃바운드 액세스 구성

하이퍼라이트는 생성된 아티팩트에 대해 읽기 전용 /input 트리와 쓰기 가능한 영역을 노출할 수 /output 있습니다.

workspace_root을(를) 사용하여 /input/에 작업 공간을 사용할 수 있게 하십시오.
특정 호스트 경로를 샌드박스에 매핑하는 데 사용합니다 file_mounts .
특정 대상 또는 메서드에 대해서만 아웃바운드 액세스를 사용하도록 설정하는 데 사용합니다 allowed_domains .

file_mounts은 약식 문자열, 명시적으로 지정된 (host_path, mount_path) 쌍, 또는 명명된 FileMount 튜플을 허용합니다. allowed_domains는 문자열 타깃, 명시적인 (target, method-or-methods) 쌍, 또는 명명된 튜플 AllowedDomain을(를) 허용합니다.

from agent_framework_hyperlight import HyperlightCodeActProvider

codeact = HyperlightCodeActProvider(
    tools=[compute],
    file_mounts=[
        "/host/data",
        ("/host/models", "/sandbox/models"),
    ],
    allowed_domains=[
        "api.github.com",
        ("internal.api.example.com", "GET"),
    ],
)

출력 지침

에서 execute_code텍스트를 표시하려면 코드를 으로 print(...)종료합니다. 하이퍼라이트는 마지막 식의 값을 자동으로 반환하지 않습니다.

파일 시스템 액세스가 활성화되면 더 큰 아티팩트를 /output/<filename>에 씁니다. 반환된 파일은 도구 결과에 첨부되지만 아래 /input 파일은 샌드박스 내에서 읽을 수 있습니다.

CodeAct 및 직접 도구 호출 비교

벤치마크 샘플은 동일한 클라이언트, 모델, 도구, 프롬프트 및 구조적 출력 스키마를 기존 도구 호출을 통해 한 번, 하이퍼라이트 지원 CodeAct를 통해 한 번씩 동일한 작업을 실행합니다. 유일한 차이점은 배선입니다. 직접 도구와 execute_code에 의해 지원되는 단일 HyperlightCodeActProvider 도구.

이 샘플에서 에이전트는 데이터를 반복적으로 조회하고 가벼운 계산을 수행하여 사용자 및 주문의 데이터 세트에서 총합계를 계산합니다. 이것이 바로 CodeAct가 오케스트레이션 오버헤드를 제거할 수 있는 다단계 워크플로의 종류입니다. 전체 샘플은 두 실행 모두에 대해 경과된 시간과 토큰 사용량을 인쇄하므로 사용자 고유의 환경에서 실행 셰이프를 비교할 수 있습니다.

현재 제한 사항

이 패키지는 여전히 알파이며 몇 가지 제약 조건을 계획할 가치가 있습니다.

플랫폼 지원은 게시된 하이퍼라이트 백 엔드 패키지를 따릅니다. 현재 지원되는 Linux 및 Windows 환경을 의미합니다. 지원되지 않는 플랫폼은 샌드박스를 만들 때 실패합니다.
현재 통합은 Python 게스트 코드를 실행합니다. .NET 설명서는 곧 제공될 예정입니다.
메모리 내 인터프리터 상태는 별도의 execute_code 호출에서 유지되지 않습니다. 호출에서 데이터가 유지되어야 하는 경우 마운트된 파일 및 /output 아티팩트 사용
승인은 동일한 코드 블록 내의 개별 execute_code이 아닌 전체 call_tool(...) 호출에 적용됩니다.
모델에서 격리된 직접 도구 호출을 선택하지 않고 해당 계약에 대한 코드를 작성하기 때문에 도구 설명, 매개 변수 주석 및 반환 셰이프가 더 중요합니다.

다음 단계

범위

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-22

하이퍼라이트 CodeAct