# Что такое Pi agent

_Для Вани Светашева_

## Коротко

**Pi agent** — это инструмент для работы с языковыми моделями из командной строки. Но точнее называть его не «моделью» и не отдельным искусственным интеллектом, а **agent harness** — оболочкой и средой исполнения для агента.

Модель отвечает за рассуждение и генерацию текста. Pi организует вокруг неё рабочий процесс: принимает задачу, показывает модели доступные инструменты, выполняет вызовы этих инструментов, возвращает результаты модели и продолжает цикл до получения результата.

Упрощённая схема:

```text
пользователь → Pi (harness) → языковая модель
                    ↑              ↓
                 результаты ← инструменты
```

## Что такое агент вообще

В разговорной речи «агентом» часто называют саму модель. Это не совсем точно.

**Языковая модель** умеет обрабатывать контекст и предсказывать следующий фрагмент текста. Сама по себе она обычно не может прочитать файл на компьютере, выполнить команду, открыть сайт или изменить код.

**Агент** — это связка из нескольких частей:

1. **Модель** — принимает решения и формулирует действия.
2. **Harness / runtime** — программа, которая ведёт диалог с моделью и исполняет её действия.
3. **Инструменты** — например, чтение файлов, shell-команды, поиск, браузер и API.
4. **Контекст и состояние** — текущая задача, история диалога, файлы проекта и, при необходимости, память.
5. **Ограничения и подтверждения** — правила, определяющие, что агенту разрешено делать.

Поэтому агент — это не «магическая модель, которая умеет всё», а **модель, помещённая в цикл восприятия, планирования и действия**.

Типичный цикл выглядит так:

```text
1. Получить задачу.
2. Посмотреть доступный контекст.
3. Решить, какое действие нужно выполнить.
4. Вызвать инструмент.
5. Получить результат.
6. Проанализировать результат.
7. Повторять, пока задача не решена.
```

Именно harness отвечает за то, чтобы вызов инструмента действительно произошёл, а его результат попал обратно в контекст модели.

## Что именно делает Pi

Pi — это минималистичная, расширяемая среда для coding и general-purpose agents. Она умеет:

- вести интерактивные сессии в терминале;
- работать с файлами и каталогами;
- выполнять shell-команды;
- редактировать и создавать файлы;
- хранить историю сессий;
- подключать extensions, skills и дополнительные инструменты;
- запрашивать подтверждение перед потенциально опасными действиями;
- работать с разными провайдерами моделей.

При этом Pi не навязывает одну «правильную» модель и не является закрытым чат-ботом. Его роль — предоставить удобную и контролируемую среду, в которой модель может действовать.

## Важное различие: Pi — не модель

Pi не является моделью вроде GPT, Claude, Gemini или Llama. Он — **клиент и harness** для таких моделей.

К Pi можно подключать разные модели, если доступен соответствующий провайдер или API. Например:

- модели OpenAI;
- модели Anthropic;
- модели Google;
- модели через OpenRouter;
- локальные модели через Ollama;
- другие модели через OpenAI-compatible API;
- в принципе — любую модель, для которой можно написать адаптер провайдера.

Из этого следуют две полезные вещи:

- смена модели не требует менять весь агентский workflow;
- одна и та же модель может вести себя совершенно по-разному в разных harnesses, потому что инструменты, контекст, права и цикл исполнения задаются окружением.

## Пример

Допустим, пользователь просит:

> Найди в проекте все места, где используется старый URL, замени его на новый и запусти тесты.

Обычный чат с моделью может только предложить команды. Pi agent может:

1. прочитать структуру проекта;
2. найти упоминания URL;
3. показать или внести изменения;
4. запустить тесты;
5. изучить ошибки;
6. исправить код;
7. повторно запустить тесты;
8. сообщить, что было сделано.

Модель в этом примере принимает решения, а Pi предоставляет ей инструменты и исполняет выбранные действия.

## Инструменты и skills

Инструмент — это конкретная операция, которую harness может выполнить по запросу модели. Примеры:

- `read` — прочитать файл;
- `bash` — выполнить команду;
- `edit` — изменить существующий файл;
- `write` — создать файл;
- браузерный инструмент — открыть страницу, нажать кнопку, заполнить форму;
- поиск по прошлым сессиям — найти старое обсуждение и прочитать его.

**Skill** — это обычно инструкция и набор практик для определённого типа задач. Например, skill может объяснять агенту, как пользоваться браузером, Anki или почтовым клиентом. Skill не превращает модель в другую модель: он даёт ей специализированный способ работы.

**Extension** — программное расширение Pi, которое может добавлять инструменты, команды, хуки и автоматизацию.

## Почему это называют harness

Слово *harness* буквально означает «упряжь» или «обвязка». В инженерном смысле это программа, которая окружает модель и подключает её к реальному миру.

Harness обычно решает задачи, которые не должна решать сама модель:

- управление API-вызовами;
- сборка и сокращение контекста;
- хранение сессий;
- исполнение tool calls;
- обработка ошибок и повторов;
- права доступа;
- подтверждение опасных операций;
- подключение внешних сервисов;
- отображение процесса работы пользователю.

Поэтому полезно разделять три уровня:

```text
модель       — думает и генерирует решения
harness      — организует цикл и связывает модель с системой
агент        — модель + harness + инструменты + контекст
```

В реальных системах границы между этими понятиями иногда размыты, но такая схема хорошо объясняет архитектуру.

## Чем Pi отличается от обычного чата

В обычном чате модель в основном выдаёт текст. В Pi основной результат может быть не текстовым, а практическим:

- изменённый файл;
- выполненная команда;
- найденная информация;
- созданный документ;
- отправленное письмо;
- результат тестов;
- собранный проект.

При этом пользователь может видеть ход работы и контролировать опасные действия. Pi не обязан делать вид, что всё уже выполнено: он может честно показать вызов инструмента, ошибку, повторную попытку и итог.

## Краткое резюме

- **LLM** — языковая модель, которая анализирует контекст и генерирует решения.
- **Harness** — программа-обвязка, которая даёт модели инструменты, выполняет её действия и поддерживает цикл работы.
- **Agent** — система из модели, harness, инструментов, контекста и ограничений.
- **Pi agent** — open-ended agent harness для терминала и программных задач.
- Pi не привязан к одной модели: к нему можно подключать разные облачные и локальные модели через провайдеров и API.
- Сила агента определяется не только моделью, но и качеством harness, инструментов, контекста и прав доступа.

Иными словами: **Pi — это не «ещё одна модель», а рабочая среда, которая позволяет разным моделям действовать как агентам.**