Pi Harness

Import

import { pi, createPi } from '@ai-sdk/harness-pi';

pi 는 기본 설정을 가진 createPi() 와 동일해요.

기본 사용법

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { pi } from '@ai-sdk/harness-pi';
import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';

const agent = new HarnessAgent({
  harness: pi,
  model: 'anthropic/claude-sonnet-4.6',
});

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  template: await agent.getSandboxTemplate(),
});
const session = await agent.createSession({ sandboxSession });

let exitCode = 0;
try {
  const result = await agent.stream({
    session,
    prompt: 'Check the test failures and fix the production code.',
  });

  for await (const part of result.stream) {
    if (part.type === 'text-delta') {
      process.stdout.write(part.text);
    }
  }
} catch (err) {
  exitCode = 1;
  console.error(err);
} finally {
  await session.destroy();
  await sandboxSession.destroy();
  process.exit(exitCode);
}

이 에이전트를 사용하려면 환경 변수에 Vercel Sandbox용 VERCEL_OIDC_TOKEN 과, Pi용으로 인증 섹션에 나열된 변수 중 하나가 포함되어야 해요.

어댑터 설정

createPi() 를 사용해 런타임을 설정하세요:

const harness = createPi({
  thinkingLevel: 'medium',
});

설정:

• auth: 인증 모드(auto, openai, anthropic, custom, ai-gateway) 또는 격리된 인증 환경.
• credentials: 애플리케이션 소유 Pi 자격 증명 저장소. 파일 기반 auth.json 저장소를 대체하고 지속적인 데이터베이스 기반 자격 증명을 지원해요.
• extensionFactories: 호스트 Node.js 프로세스에서 실행되는 신뢰할 수 있는 인라인 Pi 확장 팩토리.
• mcpServers: 서버 이름 키로 된 MCP 서버 정의.
• providers: 커스텀 모델을 위한 명시적 Pi 프로바이더 설정.
• reattachInProcess: 일시 중단된 턴이 현재 프로세스에서 라이브 Pi 세션을 재사용할 수 있는지 여부. 기본값은 true.
• thinkingLevel: Pi 사고 수준(off, minimal, low, medium, high, xhigh, 또는 max).

인라인 확장 (Inline Extensions)

각 harness 세션에 대해 신뢰할 수 있는 인라인 Pi 확장을 로드하려면 extensionFactories 를 사용하세요:

const harness = createPi({
  extensionFactories: [
    pi => {
      pi.on('agent_start', () => {
        console.log('Pi agent started');
      });
    },
  ],
});

턴 사이의 일상적인 리소스 새로고침은 활성 확장 런타임을 재사용하며 팩토리를 다시 초기화하지 않아요. 기본 Pi 세션이 재구축되면 팩토리가 새 Pi 런타임을 위해 다시 초기화돼요.

확장 팩토리는 호스트 Node.js 프로세스에서 호스트 환경에 접근하며 실행되므로, 신뢰하는 팩토리만 전달하세요. 이 설정은 명시적으로 제공한 팩토리만 활성화해요. 사용자, 프로젝트, 설정 기반 확장을 포함한 파일시스템 확장 발견은 비활성 상태로 유지돼요. 테마와 프롬프트 템플릿도 비활성 상태로 유지돼요.

세션 재부착 (Session Reattachment)

기본적으로 Pi는 들어오는 요청의 설정과 런타임 리소스가 호환될 때 같은 프로세스에서 효율적인 연속을 위해 일시 중단된 턴을 살려 둬요. 변경된 요청 범위 설정이나 sandbox 핸들은 지속된 수명 주기 상태에서 콜드 복원을 일으켜요.

상태 비저장 또는 멀티-레플리카 애플리케이션에서는 프로세스 내 재부착을 비활성화해 모든 연속이 현재 요청의 설정으로 지속된 수명 주기 상태를 복원하게 하세요:

const harness = createPi({
  reattachInProcess: false,
});

들어오는 완료된 resume-session 상태는 프로세스 내의 오래된 라이브 일시 중단 턴보다 항상 우선해요.

인증 (Authentication)

auth 설정은 Pi가 호스트 환경에서 읽는 자격 증명을 선택해요:

• auto (기본값): 사용 가능하면 AI Gateway 자격 증명을 사용하고, 그다음 환경에서 발견된 모든 프로바이더 자격 증명으로 폴백.
• openai: OPENAI_API_KEY 와 선택적 OPENAI_BASE_URL 사용.
• anthropic: ANTHROPIC_API_KEY 와 선택적 ANTHROPIC_AUTH_TOKEN 및 ANTHROPIC_BASE_URL 사용.
• custom: 환경 변수를 통해 설정된 모든 프로바이더를 등록.
• ai-gateway: AI_GATEWAY_API_KEY 또는 VERCEL_OIDC_TOKEN 과 선택적 AI_GATEWAY_BASE_URL 사용.

적용 가능한 자격 증명 환경 변수가 설정되지 않았고 AI Gateway 인증이 선택되지 않았다면, 어댑터는 호스트 시스템에서 네이티브 구독을 해석하려 시도해요.

const harness = createPi({ auth: 'ai-gateway' });

process.env 를 읽지 않고 프로그래밍 방식으로 해석된 자격 증명을 사용하려면 인증 환경을 전달하세요:

const harness = createPi({
  auth: {
    MISTRAL_API_KEY: await resolveMistralToken(),
    MISTRAL_BASE_URL: 'https://api.mistral.ai',
  },
});

제공된 레코드는 인증 발견을 위해 호스트 환경을 대체해요. Pi는 그 레코드에서 프로바이더 API 키와 base URL을 파싱해요.

환경 변수나 파일 밖에서 관리되는 자격 증명의 경우 애플리케이션 소유 자격 증명 저장소를 주입하세요. Pi는 이 인터페이스를 통해 자격 증명 읽기, 새로고침, 업데이트를 수행해요:

import { createPi, type PiCredentialStore } from '@ai-sdk/harness-pi';

declare const credentials: PiCredentialStore;

const harness = createPi({
  credentials,
  reattachInProcess: false,
});

credentials 는 Pi의 auth.json 저장소를 대체해요. 요청 범위 또는 멀티-레플리카 배포에서는 reattachInProcess: false 와 함께 사용해 각 연속이 현재 요청에서 모델 런타임을 구성하게 하세요.

custom 과 함께 표준 프로바이더는 OPENAI_API_KEY, OPENAI_BASE_URL, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL 같은 환경 변수를 사용해요. 다른 프로바이더는 <PREFIX>_API_KEY 와 일치하는 <PREFIX>_BASE_URL 쌍을 사용해요.

인증 변수는 프로바이더의 API 프로토콜이나 모델을 식별하지 않아요. 커스텀 모델을 사용할 때는 그 메타데이터를 명시적으로 등록하세요:

const harness = createPi({
  auth: {
    MYPROVIDER_API_KEY: await resolveMyProviderToken(),
    MYPROVIDER_BASE_URL: 'https://api.example.com/v1',
  },
  providers: {
    myprovider: {
      api: 'openai-completions',
      models: [
        {
          id: 'my-custom-model',
          name: 'My Custom Model',
          reasoning: false,
          input: ['text'],
          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
          contextWindow: 128_000,
          maxTokens: 16_384,
        },
      ],
    },
  },
});

Sandbox

Pi는 sandbox 세션이 필요하지만 노출된 포트는 요구하지 않아요. Vercel 네트워크 세션이나 로컬 just-bash 세션을 만들 수 있어요:

const sandboxSession = await createVercelNetworkSandboxSession({
  runtime: 'node24',
  template: await agent.getSandboxTemplate(),
});

내장 Tool (Built-in Tools)

어댑터는 agent.tools 를 통해 다음 일반 Pi 내장 기능을 노출해요:

• read
• write
• edit
• bash
• grep
• glob
• ls

다른 Pi 내장 기능이 일반 tool 형태에 맞지 않으면 agent.tools 에도 나타날 수 있어요.

Pi는 permissionMode 가 allow-reads 또는 allow-edits 일 때 내장 tool 승인 요청을 지원해요.

알려진 제한 사항

Pi는 구조화된 출력을 지원하지 않아요. HarnessAgent 에 output 을 제공하면 턴이 HarnessCapabilityUnsupportedError 를 던져요.

관련

• HarnessAgent
• Harness tools
• Harness 어댑터

더 알아보기 (Learn more)

• Claude Code
• Codex
• Pi
• OpenCode
• Deep Agents
• Agent Client Protocol
• Grok Build
• Cline
• Cursor
• fx
• GitHub Copilot

전체 사이트맵