Microsoft Agent Framework의 CodeAct를 사용하여 JavaScript를 실행해 보았다

서론

Microsoft Agent Framework의 CodeAct (Hyperlight)를 사용하면, AI 에이전트에게 샌드박스(Sandbox)화된 코드 실행 기능을 통합할 수 있습니다.

이번에는 아래의 확인을 목적으로, Microsoft.Agents.AI.Hyperlight를 .NET에서 테스트해 보았습니다.

• 로컬 LLM 환경에서 Hyperlight를 이용할 수 있는지 여부
• 모델이 JavaScript 코드를 생성하고, 실행 결과를 받아 최종 답변을 반환할 수 있는지 여부
• 요청(Request) / 응답(Response) / 도구(Tool) 실행 결과를 확인할 수 있는지 여부

CodeAct에 대하여

CodeAct는 에이전트가 코드를 작성하고 Tool Calling으로 실행하며, 그 실행 결과를 사용하여 태스크를 진행하는 개념입니다. 모델에게 "다음 도구를 1개만 선택하게 하는" 방식이 아니라, 제어 흐름(Control Flow), 데이터 변환(Data Transformation), 도구 오케스트레이션(Tool Orchestration)을 짧은 코드로 묶어 1회의 실행으로 다룰 수 있는 것이 특징입니다.

Microsoft Learn의 설명에 따르면, CodeAct는 특히 "작은 도구 호출을 여러 번 연결하면 모델 턴(Turn)이 늘어나 대기 시간과 토큰 소비가 늘어나는" 것과 같은 케이스에 적합하다고 되어 있으나, 계산 실행에도 적합하다고 생각합니다. 이번 샘플도 단순한 계산 태스크를 코드 실행으로 해결하고 있습니다.

Hyperlight에 대하여

Microsoft.Agents.AI.Hyperlight는 Microsoft Agent Framework에서 CodeAct를 기능으로 다루기 위한 패키지입니다. 단순히 "코드를 실행하는 도구를 추가하는" 것뿐만 아니라, Hyperlight의 VM으로 분리된 샌드박스를 토대로 에이전트에게 안전한 코드 실행 능력을 통합하기 위한 얇은 통합 레이어(Integration Layer) 역할을 합니다.

주요 역할은 다음과 같습니다.

• Hyperlight: 경량 VM 기반의 분리된 샌드박스. 게스트(Guest) 코드를 호스트(Host)로부터 격리하여 실행하는 토대
• Microsoft.Agents.AI.Hyperlight: 해당 샌드박스를 Microsoft Agent Framework에서 사용하기 쉽게 만드는 .NET용 통합 패키지

관계도를 그리면 다음과 같습니다.

이 패키지에는 주로 두 가지 진입점이 있습니다.

• HyperlightCodeActProvider: AIContextProvider로서 에이전트에 등록하는 방식. 각 호출에 execute_code 도구와 CodeAct용 가이던스(Guidance)를 삽입합니다.
• HyperlightExecuteCodeFunction: AIFunction으로서 단독으로 사용하는 방식. 샌드박스 구성이 고정되어 있어 수동으로 배선(Wiring)하고 싶을 때 적합합니다.

이번 확인에서는 HyperlightCodeActProvider를 사용하고 있습니다.

이 패키지로 할 수 있는 것은 단순한 JavaScript 실행만이 아닙니다. 문서에서는 다음과 같은 기능이 준비되어 있다고 설명합니다.

• 샌드박스 내에서 프로바이더가 소유한 도구를 call_tool(...)로 호출할 수 있음
• 필요할 때만 파일 마운트(File Mount)를 추가할 수 있음
• 필요할 때만 외부 통신 허용 대상을 설정할 수 있음
• CodeActApprovalMode로 승인 정책을 전환할 수 있음
• 실행마다 스냅샷(Snapshot) / 복구(Restore)를 수행하여, 매번 깨끗한 상태에서 게스트를 기동할 수 있음

또한, 다음과 같은 승인 기능도 있습니다.

• NeverRequire: 기본값. 통상적으로 승인 없이 진행되지만, ApprovalRequiredAIFunction으로 감싼 도구의 승인은 전파됩니다.
• AlwaysRequire: 항상 승인을 요구합니다.

이번에는 동작 확인을 우선하여 NeverRequire를 사용했지만, 실제 운용에서는 AlwaysRequire도 검토 대상이 될 것이라고 생각합니다.

동작 이미지

동작 확인 환경

• 프레임워크: net10.0

• 사용 패키지:

  • Microsoft.Agents.AI 1.6.1
  • Microsoft.Agents.AI.Hyperlight 1.6.1-preview.260514.1
  • Microsoft.Agents.AI.OpenAI 1.6.1

• 엔드포인트 (Endpoint): LM Studio

• 모델 (Model): openai/gpt-oss-20b (이번 LM Studio 설정에서는 컨텍스트 길이 14000)

샘플의 전체 모습

주요 코드

Hyperlight를 AI 에이전트 (AI Agent)로 등록하기

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hyperlight;
using Microsoft.Extensions.AI;
...

포인트는 CreateForJavaScript()입니다.
이를 통해 Hyperlight 측이 JavaScript 실행을 위한 CodeAct 프로바이더 (Provider)로서 동작합니다.

이번에는 검증을 우선하여 승인은 NeverRequire로 설정했습니다.

실행 결과

이번에는 간단한 계산 시나리오로 CodeAct의 기본 동작을 확인합니다.

계산 시나리오: 1부터 10까지의 합계

입력:

JavaScript 코드 실행을 사용하여, 1부터 10까지의 합계를 계산하고 결과만 반환해 주세요.

기대되는 흐름은 다음과 같습니다.

• 첫 번째 응답에서 finishReason: "tool_calls"가 반환됨
• execute_code가 호출됨
• 도구 실행 결과로서 stdout: "55"가 반환됨
• 재질의 후, 최종 응답은 55가 됨

실행 로그 트레이스 (Trace)

다음은 각 단계에서 실제로 관측된 트레이스입니다.

(contents 내부만 보여줍니다.)

단계 1. 첫 번째 지시

첫 번째 ChatLog Request에서는, role: user 메시지에 사용자 지시가 포함되어 모델 (Model)에 전달됩니다.

[
{
"$type": "text",
...

단계 2. 이번 실행에서 생성된 코드

첫 번째 ChatLog Response에서는, 모델이 즉시 답하지 않고 execute_code의 함수 호출 (Function Call)을 반환합니다. 여기서 에이전트 (Agent) 측은 finishReason: "tool_calls"를 받고 샌드박스 (Sandbox) 실행으로 진행합니다. 다음은 이 실행에서 관측된 코드 예시입니다.

[
{
"$type": "functionCall",
...

단계 3. 코드의 실행 결과

Hyperlight 샌드박스 (Sandbox)가 코드를 실행하면, 그 결과는 role: tool 메시지에 functionResult로서 돌아옵니다. 이 값이 다음 호출에 도구 메시지 (Tool Message)로서 전달됩니다.

[
{
"$type": "functionResult",
...

단계 4. 최종 답변

도구 실행 결과를 받은 후의 두 번째 ChatLog Response에서는, 모델이 최종 텍스트 답변을 반환합니다. 이번에는 finishReason: "stop"으로, 55만을 반환하고 종료되었습니다.

[
{
"$type": "text",
...

요약

Microsoft.Agents.AI.Hyperlight를 사용하면, 간단하게 JavaScript 실행 기능이 포함된 AI 에이전트 (AI Agent)를 구축할 수 있었습니다. 또한, 실행해 보니 JavaScript 코드 생성부터 실행 요청, 그리고 결과 수신까지 모델 (Model)과 샌드박스 (Sandbox)가 연동되어 동작하는 모습도 확인할 수 있었습니다.

컨텍스트 (Context) 소비가 어느 정도 있으므로, 실제로 도입할 경우에는 멀티 에이전트 (Multi-Agent) 구성으로 하여 코드 실행이 필요한 부분만 Hyperlight 에이전트에게 맡기는 것이 현실적이라고 생각합니다.

소스

샘플 코드

using Microsoft.Agents.AI.Hyperlight;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
...