Pi Agent 사용해보기

터미널에서 가볍게 실행할 수 있는 오픈소스 AI 코딩 에이전트인 pi agent를 사용해봤습니다.

기존의 Cursor나 Devin 같은 상용 도구들과 달리, pi agent는 에이전트의 동작 방식을 직접 빌드하고 제어할 수 있는 미니멀한 도구입니다. 복잡한 UI 대신 터미널 환경을 선호하는 개발자에게 특히 적합합니다. 관련 상세 정보는 공식 웹사이트(홈페이지 링크)에서 확인하실 수 있습니다.

1. pi agent 주요 특징

미니멀한 기능: 기본 상태에서는 코드베이스 탐색과 수정을 위한 read, write, edit, bash 4가지 툴만 제공합니다.
모델 독립성: Claude, OpenAI, Gemini 외에도 로컬 vLLM 등을 통해 개인 모델을 연결할 수 있습니다.
자기 확장성: 에이전트 스스로 본인의 TypeScript 코드를 읽고 새로운 기능을 추가할 수 있습니다.

2. pi agent 설치 및 실행 방법

Node.js 환경에서 전역으로 설치하여 사용합니다. 터미널 명령어를 입력하면 간편하게 설치됩니다.

npm install -g @earendil-works/pi-coding-agent

설치 후 사용하고자 하는 LLM API 키를 지정하고 실행하면 즉시 세션이 시작됩니다.

export ANTHROPIC_API_KEY="본인_API_키" pi

3. 로컬 모델 연동 (Gemma-4 예시)

~/.pi/agent/models.json 파일을 생성해 로컬이나 원격 vLLM 모델을 등록할 수 있습니다. 네트워크 연결이 끊긴 오프라인 환경에서도 로컬 LLM을 사용해 작업을 수행할 수 있어 매우 유용합니다.

{
  "providers": {
    "local-vllm": {
      "baseUrl": "http://127.0.0.1:8000/v1",
      "api": "openai-completions",
      "apiKey": "none",
      "models": [
        {
          "id": "gemma-4-26B_q4_0-it.gguf"
        }
      ]
    }
  }
}

등록 후 실행할 때 모델명을 인자로 넘겨줍니다.

pi --model local-vllm/gemma-4-26B_q4_0-it.gguf

4. pi agent 커스텀 확장성 (TypeScript 및 스킬 추가)

이 도구의 핵심 매력은 내가 필요한 기능을 직접 붙여 쓸 수 있다는 점입니다. 크게 3가지 방식으로 확장하여 활용할 수 있습니다.

1) 커스텀 도구(Tool) 및 명령어 추가

~/.pi/agent/extensions/(글로벌) 또는 프로젝트 폴더 내 .pi/extensions/ 경로에 TypeScript 파일을 작성해 넣어두면 에이전트가 이를 자동으로 로드합니다.

타입 지정을 위해 @sinclair/typebox를 활용하며, LLM이 자동으로 파악해 실행할 수 있는 커스텀 도구나 사용자가 터미널에서 직접 호출할 수 있는 슬래시 커맨드를 만들 수 있습니다.

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "@sinclair/typebox";

export default function (pi: ExtensionAPI) {
  // LLM이 호출할 도구 등록
  pi.registerTool({
    name: "fetch_weather",
    description: "특정 도시의 날씨 정보를 조회합니다.",
    parameters: Type.Object({
      location: Type.String({ description: "도시 이름" }),
    }),
    execute: async (toolCallId, params) => {
      return { content: [{ type: "text", text: `${params.location} 날씨는 맑음` }] };
    },
  });

  // 사용자가 수동으로 입력할 슬래시 커맨드 등록
  pi.registerCommand({
    name: "weather_test",
    description: "날씨 조회를 수동 테스트합니다.",
    execute: async (args, ctx) => {
      ctx.ui.notify("날씨 정보를 호출합니다...", "info");
    }
  });
}

2) 패키지화된 스킬(Skills) 설치

자주 사용되는 툴킷이나 워크플로우 템플릿은 스킬(Skills) 단위로 설치하고 관리할 수 있습니다. CLI 명령어를 통해 GitHub에 올라온 오픈소스 스킬을 쉽게 추가할 수 있습니다.

npx skills add [깃허브_유저명]/[저장소_이름]

3) 커스텀 API 프로바이더 등록

회사 내부에서 사용하는 프록시 API나 특수 모델 서버가 있다면 프로바이더를 직접 등록해 모델을 추가할 수도 있습니다.

pi.registerProvider("my-company-llm", {
  name: "Internal LLM",
  baseUrl: "https://api.mycompany.com/v1",
  apiKey: "company-secret-key",
  api: "openai-completions",
  models: [{ id: "custom-model-v1" }]
});

이전 포스팅인 OpenClaw 보안봇 만들기 가이드나 다른 AI 에이전트 도구들과 비교하며 사용해 보시는 것을 추천해 드립니다.

공식 홈페이지: https://pi.dev/

이 글은 본인의 실제 경험과 학습을 기반으로 직접 작성하였으며, AI는 참고용으로만 활용하였습니다.