Pi Agent란 무엇인가

서론

기능만 본다면 Pi Agent는 쉽게 저평가될 수 있습니다. 터미널에서 실행되며, 파일을 읽고 수정하고, 명령을 실행하고, 세션을 저장하며, 모델을 전환할 수도 있습니다. 마치 또 다른 Claude Code나 Codex처럼 들립니다.

하지만 제가 생각하기에 Pi가 정말 흥미로운 점은 무엇을 더 했는지가 아니라 무엇을 덜 했는지에 있습니다. Pi는 AI 프로그래밍 도구의 가장 핵심적인 계층, 즉 모델, 컨텍스트, 도구, 세션, 확장을 유지하고 사용자 워크플로우를 미리 고정시키지 않으려 노력했습니다.

그래서 저는 Pi를 이렇게 이해하고 싶습니다.

Pi Agent는 "더 완벽한" AI 프로그래밍 제품이 아니라, 더 얇고 투명한 코딩 에이전트 하네스입니다.

이 판단은 기능 목록보다 더 중요합니다. 왜냐하면 Pi를 어떻게 학습해야 하는지를 결정하기 때문입니다. 명령어를 외우는 것보다 코딩 에이전트가 어떤 계층으로 구성되어 있는지 먼저 이해해야 합니다.

Pi의 위치를 올바르게 파악하기

AI 프로그래밍 도구는 일반적으로 모델, 하네스, 엔지니어링 환경의 세 가지 계층으로 크게 나눌 수 있습니다. 하지만 이 세 계층만으로는 너무 추상적입니다. Pi에서 정말 주목할 만한 점은 중간 계층인 하네스가 어떤 모듈로 다시 분해되는지입니다.

이 다이어그램에는 세 가지 중요한 포인트가 있습니다.

첫째, Pi는 단순히 "채팅 UI"만 있는 것이 아닙니다. CLI, 대화형 TUI, print/JSON, RPC, SDK는 모두 진입점일 뿐이며, 실제로 작업을 처리하는 것은 AgentSessionRuntime과 AgentSession입니다.

둘째, Pi는 모델에 요청하기 전에 리소스 로딩을 수행합니다. ResourceLoader는 AGENTS.md, CLAUDE.md, 스킬, 확장, 프롬프트 템플릿 등을 정리한 다음 SystemPrompt Builder에 전달하여 모델이 실제로 보는 컨텍스트를 구성합니다.

셋째, 모델이 도구를 호출할 때, 모델이 파일 시스템을 직접 제어하는 것이 아닙니다. AgentHarness와 AgentLoop는 도구 검증, 도구 실행, 결과 수신, 다음 라운드 계속을 담당합니다. Extensions, Tool Registry, SessionManager는 옆에서 기능을 확장하고 상태를 저장합니다.

따라서 Pi는 중간에 서 있지만, 이 "중간"이라는 말이 공허한 이야기가 아닙니다. 구체적으로 제어하는 것은 다음과 같습니다. 어떤 컨텍스트가 모델에 들어가는지, 어떤 도구를 호출할 수 있는지, 도구 결과가 세션으로 어떻게 돌아오는지, 어떤 기능이 확장으로 보완되는지.

이것이 바로 Pi를 소개하는 많은 글에서 minimal, transparent, extensible을 강조하는 이유입니다. 이들은 사실 같은 것을 말하고 있습니다. Pi는 에이전트의 핵심 실행 계층을 작게 만들고, 사용자가 볼 수 있고 수정할 수 있도록 노력합니다.

한 번의 작업 흐름

Pi의 한 번의 요청은 "모델에게 한 문장을 묻고, 모델이 한 문장을 답하는" 것이 아닙니다. 더 정확히 말하면, 그것은 분기가 있는 시간 순서입니다.

여기서 가장 중요한 것은 네 번째 단계와 다섯 번째 단계 사이의 왕복입니다. 모델은 파일 시스템을 직접 건드리지 않고, tool_call만 제안합니다. Pi는 이 호출을 받아 도구 이름과 매개변수를 검증하고, 존재할 수 있는 확장 훅을 트리거하며, 실제 작업을 실행한 다음 tool_result를 컨텍스트에 다시 넣습니다. 모델은 새로운 컨텍스트에 따라 다음 단계를 판단합니다.

이것이 코딩 에이전트와 일반 챗봇의 차이입니다. 챗봇은 주로 텍스트 내에서 작업을 완료합니다. 코딩 에이전트는 엔지니어링 시스템에 진입해야 하므로 도구, 컨텍스트 및 상태를 관리하는 하네스가 반드시 필요합니다.

Pi의 기본 도구는 매우 적습니다.

grep, find, ls와 같은 읽기 전용 도구도 활성화하거나 제한할 수 있습니다. 이 도구 세트는 절제되어 보이지만, 이미 프로그래밍 폐쇄 루프를 형성했습니다. 코드 읽기, 코드 수정, 테스트 실행, 오류에 따라 계속 수정.

이러한 설계 뒤에 있는 질문은 "Pi가 더 많은 것을 할 것인가"가 아니라 "더 많은 것이 기본적으로 핵심에 포함되어야 하는가"입니다. Pi의 답변은 명확합니다. 반드시 그렇지는 않습니다.

왜 많은 기능을 서둘러 내장하지 않는가

많은 AI 프로그래밍 제품은 계획 모드, 할 일, 서브 에이전트, MCP, 권한 팝업, 백그라운드 작업, 브라우저 도구 등을 제품에 내장합니다. 이렇게 하면 빠르게 시작할 수 있지만, 대가가 따릅니다. 모델이 실제로 어떤 컨텍스트를 받았는지 알기 어렵고, 제품 워크플로우를 자신의 워크플로우로 변경하기 어렵습니다.

Pi의 경로는 그 반대입니다. 핵심을 매우 작게 유지하고 워크플로우를 외부에 배치합니다.

이것은 "기능 부족"이 아니라 제품의 절충점입니다. 핵심은 에이전트 루프만 관리하고, 구체적인 워크플로우는 사용자와 팀이 직접 조합하도록 맡깁니다.

예를 들어, Pi는 기본적으로 DeepSearch를 내장하지 않습니다. 하지만 이것이 심층 검색을 할 수 없다는 의미는 아닙니다. Pi의 사고방식에 더 부합하는 방법은 확장 기능을 작성하는 것입니다. deep_search 도구를 등록하고, Tavily, Exa, Brave Search 또는 회사 내부 검색을 연결한 다음, 모델이 필요할 때 이를 호출하도록 하는 것입니다.

이것은 "검색 버튼"을 제품에 하드코딩하는 것과는 다릅니다. 전자는 에이전트의 기능을 확장하는 것이고, 후자는 제품이 워크플로우를 대신 결정하는 것입니다.

중요: 자신의 워크플로우를 확장하는 방법

Pi를 단순히 "경험하는 것"이 아니라 실제로 사용하려면 자신의 워크플로우를 확장하는 것이 중요합니다.

여기서 혼동하기 쉬운 점은 Pi가 "플러그인"이라는 한 가지 확장 방식만 있는 것이 아니라는 것입니다. Pi는 프로젝트 규칙, 작업 방법, 실제 도구, 공유 가능한 패키지의 네 가지 계층 진입점을 제공합니다. 먼저 자신이 어떤 종류의 것을 정착시키고 싶은지 판단해야 합니다.

제 이해는 다음과 같습니다. Skill은 작업 매뉴얼이고, Extension은 실행 가능한 플러그인이며, Package는 배포 컨테이너입니다.

예를 들어, 현재 이 블로그 워크플로우는 다음과 같이 분해할 수 있습니다.

이것은 단순히 "플러그인 설치"라고 말하는 것보다 더 정확합니다. 왜냐하면 많은 워크플로우는 코드를 작성할 필요 없이 좋은 규칙이나 Skill만 있으면 되기 때문입니다. 하지만 에이전트가 외부 검색, 데이터베이스 조회, CI 호출, 위험한 명령 가로채기 등 실제로 새로운 기능을 갖기를 원한다면 Extension을 작성해야 합니다.

Extension: 진정한 플러그인 계층

Pi의 Extension은 TypeScript 모듈입니다. 몇 가지 유형의 작업을 수행할 수 있습니다.

Extension은 전역적으로 또는 프로젝트 내에 배치할 수 있습니다.

~/.pi/agent/extensions/      # 전역 확장, 모든 프로젝트에서 사용 가능
.pi/extensions/              # 프로젝트 확장, 현재 프로젝트에서만 사용

임시 확장을 테스트하려면 다음을 사용할 수 있습니다.

pi -e ./my-extension.ts

자동 검색 디렉토리에 배치한 후 Pi에서 다음을 사용할 수 있습니다.

/reload

확장, 스킬, 프롬프트 및 컨텍스트 파일을 다시 로드합니다.

이것이 제가 Pi에서 가장 가치 있다고 생각하는 부분입니다. 단순히 "모델이 코드 작성을 돕도록 하는 것"이 아니라, 모델을 위해 제어 가능한 작업 환경을 설계하는 것입니다. Extension은 모델이 어떤 기능을 호출할 수 있는지 결정하고, hooks는 어떤 동작을 가로채야 하는지 결정하며, commands는 자신의 워크플로우가 어떻게 트리거되는지 결정합니다.

Skill: 모든 것을 플러그인으로 작성하지 마세요

어떤 기능이 주로 "어떻게 하는지"에 관한 것이고, "실제 API를 호출하거나 프로그램을 실행하는 것"이 아니라면, Skill로 작성하는 것이 더 적합합니다.

Skill의 구조는 일반적으로 다음과 같습니다.

my-skill/
  SKILL.md
  scripts/
  templates/
  references/

Pi는 시작할 때 전체 스킬을 컨텍스트에 모두 넣지 않습니다. 먼저 스킬의 이름과 설명을 로드합니다. 작업이 일치하면 모델이 전체 SKILL.md를 읽도록 합니다. 이를 점진적 공개라고 합니다. 장점은 복잡한 방법론을 저장할 수 있지만, 매번 컨텍스트를 오염시킬 필요가 없다는 것입니다.

예를 들어 "좋은 글쓰기", "공식 계정에 게시", "브라우저 QA 수행" 등은 Skill에 더 가깝습니다. 이들의 가치는 주로 단계, 판단 기준 및 참조 자료에 있으며, LLM이 호출할 수 있는 도구를 등록할 필요는 없습니다.

Package: 자신의 워크플로우를 패키징하기

안정적인 기능 세트가 있다면 Pi Package로 만드는 것을 고려할 수 있습니다.

Package에는 다음이 포함될 수 있습니다.

설치 방법은 다음과 같습니다.

pi install npm:@scope/my-pi-package
pi install git:github.com/user/repo@v1
pi install ./relative/path/to/package
pi list
pi remove npm:@scope/my-pi-package
pi update --extensions

기본 설치는 개인 설정에 기록됩니다. 팀 프로젝트에서 공유하고 싶다면 프로젝트 수준 설정을 사용하여 .pi/settings.json에 패키지를 기록할 수 있습니다. 이렇게 하면 다른 사람이 프로젝트에 진입하여 Pi를 시작할 때 누락된 패키지를 자동으로 보완할 수 있습니다.

하지만 여기서도 매우 신중해야 합니다. Package, Extension, Skill은 모두 에이전트의 동작에 영향을 미칠 수 있습니다. 타사 패키지는 브라우저 플러그인과 같은 낮은 권한의 장식이 아니며, 코드를 실행할 수도 있고 모델이 명령을 실행하도록 지시할 수도 있습니다. 설치 전에 소스 코드를 확인해야 합니다.

따라서 저는 Pi 확장을 이 순서대로 학습할 것입니다.

1. 먼저 AGENTS.md를 사용하여 프로젝트 규칙을 명확히 작성합니다.
2. 다음으로 반복되는 방법을 Skill로 만듭니다.
3. 실제 도구 기능이 필요할 때 Extension을 작성합니다.
4. 여러 프로젝트에서 재사용할 때 마지막으로 Package로 만듭니다.

이렇게 학습하는 것이 더 안정적입니다. 처음부터 플러그인을 작성하는 것이 아니라, 먼저 워크플로우를 "규칙, 방법, 도구, 배포"의 네 가지 유형으로 분해한 다음, 각 유형을 Pi의 어떤 계층에 배치할지 결정합니다.

소스 코드에서 무엇을 볼 수 있는가

Pi 소스 코드를 볼 때, 각 함수를 따라가는 것보다 몇몇 파일이 각각 어떤 설계 계층을 나타내는지 보는 것이 가장 도움이 되었습니다.

이러한 구성 요소들이 합쳐져 Pi의 심장을 이룹니다. 먼저 컨텍스트와 도구를 조립한 다음 요청을 모델에 전달합니다. 모델이 도구를 호출해야 하면 Pi가 도구를 실행합니다. 결과가 돌아오면 루프가 계속됩니다.

따라서 Pi의 "극도로 간결함"은 빈말이 아닙니다. 소스 코드 구조 자체도 이 아이디어를 표현하고 있습니다. 에이전트 루프, 하네스, 코딩 도구, 리소스 로딩, 확장 시스템을 분리하여 각 계층이 비교적 명확합니다.

Pi의 경계

Pi는 자유도가 높지만, 자유도가 안전을 의미하지는 않습니다.

Pi 패키지와 확장은 코드를 실행할 수 있습니다. 스킬도 모델이 스크립트를 실행하도록 지시할 수 있습니다. bash는 실제 시스템에 접근할 수 있습니다. 공식 문서와 보안 분석 모두 타사 패키지, 확장, 스킬은 스스로 검토해야 한다고 경고합니다.

저는 Pi의 경계를 세 가지로 이해합니다.

1. 샌드박스가 아닙니다: 자연스러운 격리 환경으로 생각하지 마십시오. 위험한 프로젝트는 컨테이너, 임시 디렉토리 또는 깨끗한 작업 트리에 넣는 것이 가장 좋습니다.
2. 권한을 대신 판단하지 않습니다: Pi의 핵심 철학은 수많은 팝업으로 위험을 관리하는 것이 아니라, 사용자가 도구, 컨텍스트 및 확장을 제어하도록 하는 것입니다.
3. 엔지니어링 경계를 이해하는 사람에게 적합합니다: 에이전트가 언제 명령을 실행하도록 할지, 언제 읽기 전용 도구만 제공할지, 언제 git 체크포인트를 먼저 만들지 알아야 합니다.

이것이 Pi와 일부 더 제품화된 에이전트의 차이점입니다. 제품화된 도구는 더 많은 보안 및 상호 작용 세부 사항을 포장합니다. Pi는 더 직접적인 제어권을 제공하며, 동시에 더 많은 책임을 사용자에게 돌려줍니다.

Pi를 어떻게 학습해야 하는가

Pi를 학습할 때 "어떤 명령어가 있는가"부터 시작하는 것은 권장하지 않습니다. 명령어는 금방 찾아볼 수 있으며, 정말 배워야 할 것은 다음 질문들입니다.

이미 Claude Code나 Codex를 사용해 본 적이 있다면, Pi를 "분해해서 보는" 기회로 삼을 수 있습니다. 모델이 코드를 작성하도록 하는 것은 같지만, 왜 어떤 도구는 블랙박스 제품 같고, 어떤 도구는 개조 가능한 런타임 같은가?

이 질문은 "Pi가 특정 도구를 대체할 수 있는가"보다 더 가치 있는 질문입니다.

마지막으로

Pi Agent의 가장 가치 있는 점은 AI 프로그래밍 도구의 중간 계층을 노출했다는 것입니다.

Pi는 코딩 에이전트의 능력이 모델뿐만 아니라 하네스의 설계에서도 비롯된다는 것을 상기시켜 줍니다. 모델은 생각하는 것을 담당하고, 하네스는 모델이 실제 엔지니어링 환경에서 행동하도록 합니다. 컨텍스트가 어떻게 들어오고, 도구가 어떻게 나가고, 결과가 어떻게 돌아오고, 확장이 어떻게 삽입되는지, 이러한 세부 사항들이 에이전트가 신뢰할 수 있고 투명하며 제어 가능한지 여부를 공동으로 결정합니다.

따라서 저는 Pi를 단순히 "Claude Code의 대체품"으로 보지 않을 것입니다. Pi는 개발자가 연구하고 개조하기에 적합한 에이전트 런타임에 가깝습니다. Pi를 직접 사용하여 코드를 작성할 수도 있고, Pi를 통해 자신의 에이전트 워크플로우를 설계하는 방법을 배울 수도 있습니다.

다음 실전 글에서는 이 아이디어를 계속 이어갈 것입니다. 일반적인 튜토리얼을 작성하는 대신, Pi Extension을 사용하여 deep_search 도구를 만들고 외부 검색 기능을 에이전트 루프에 연결하는 방법을 살펴보겠습니다.

추가 자료