Использование VibeOS как библиотеки Python

VibeOS — это не только CLI-инструмент. Вы можете импортировать AIAgent напрямую и использовать его программно в своих скриптах Python, веб-приложениях или пайплайнах автоматизации. Это руководство покажет вам, как это сделать.

Установка

Установите VibeOS напрямую из репозитория:

pip install git+https://github.com/Linx72/VibeOS.git

Или с помощью uv:

uv pip install git+https://github.com/Linx72/VibeOS.git

Вы также можете зафиксировать его в вашем requirements.txt:

vibeos-agent @ git+https://github.com/Linx72/VibeOS.git

подсказка

Те же переменные окружения, что используются CLI, требуются и при использовании VibeOS как библиотеки. Как минимум, установите OPENROUTER_API_KEY (или OPENAI_API_KEY / ANTHROPIC_API_KEY, если используете прямой доступ к провайдеру).

Базовое использование

Самый простой способ использовать VibeOS — метод chat(): передайте сообщение и получите строку в ответ:

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,
)
response = agent.chat("Какая столица Франции?")
print(response)

chat() внутренне обрабатывает полный цикл диалога — вызовы инструментов, повторные попытки и всё остальное — и возвращает только итоговый текстовый ответ.

предупреждение

Всегда устанавливайте quiet_mode=True при встраивании VibeOS в ваш собственный код. Без этого агент будет выводить спиннеры CLI, индикаторы прогресса и другой терминальный вывод, который засорит вывод вашего приложения.

Полный контроль над диалогом

Для большего контроля над диалогом используйте run_conversation() напрямую. Он возвращает словарь с полным ответом, историей сообщений и метаданными:

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,
)

result = agent.run_conversation(
    user_message="Найди информацию о новых возможностях Python 3.13",
    task_id="my-task-1",
)

print(result["final_response"])
print(f"Сообщений обменяно: {len(result['messages'])}")

Возвращаемый словарь содержит:

final_response — Итоговый текстовый ответ агента
messages — Полная история сообщений (системные, пользовательские, ассистента, вызовы инструментов)

(task_id, который вы передаёте, сохраняется в экземпляре агента для изоляции VM, но не возвращается обратно в словаре результата.)

Вы также можете передать собственное системное сообщение, которое переопределит эфемерный системный промпт для этого вызова:

result = agent.run_conversation(
    user_message="Объясни быструю сортировку",
    system_message="Ты — репетитор по информатике. Используй простые аналогии.",
)

Настройка инструментов

Управляйте тем, к каким наборам инструментов имеет доступ агент, с помощью enabled_toolsets или disabled_toolsets:

# Включить только веб-инструменты (просмотр, поиск)
agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    enabled_toolsets=["web"],
    quiet_mode=True,
)

# Включить всё, кроме доступа к терминалу
agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    disabled_toolsets=["terminal"],
    quiet_mode=True,
)

подсказка

Используйте enabled_toolsets, когда вам нужен минимальный, ограниченный агент (например, только веб-поиск для исследовательского бота). Используйте disabled_toolsets, когда вам нужно большинство возможностей, но требуется ограничить определённые (например, без доступа к терминалу в общей среде).

Многоходовые диалоги

Поддерживайте состояние диалога на протяжении нескольких шагов, передавая историю сообщений обратно:

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,
)

# Первый шаг
result1 = agent.run_conversation("Меня зовут Алиса")
history = result1["messages"]

# Второй шаг — агент помнит контекст
result2 = agent.run_conversation(
    "Как меня зовут?",
    conversation_history=history,
)
print(result2["final_response"])  # "Тебя зовут Алиса."

Параметр conversation_history принимает список messages из предыдущего результата. Агент копирует его внутренне, поэтому ваш исходный список никогда не изменяется.

Сохранение траекторий

Включите сохранение траекторий, чтобы записывать диалоги в формате ShareGPT — полезно для генерации обучающих данных или отладки:

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    save_trajectories=True,
    quiet_mode=True,
)

agent.chat("Напиши функцию Python для сортировки списка")
# Сохраняется в trajectory_samples.jsonl в формате ShareGPT

Каждый диалог добавляется как отдельная строка JSONL, что упрощает сбор наборов данных из автоматических запусков.

Пользовательские системные промпты

Используйте ephemeral_system_prompt, чтобы задать собственный системный промпт, который направляет поведение агента, но не сохраняется в файлы траекторий (сохраняя ваши обучающие данные чистыми):

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    ephemeral_system_prompt="Ты — эксперт по SQL. Отвечай только на вопросы о базах данных.",
    quiet_mode=True,
)

response = agent.chat("Как написать JOIN-запрос?")
print(response)

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

Пакетная обработка

Для параллельного выполнения множества промптов VibeOS включает batch_runner.py. Он управляет конкурентными экземплярами AIAgent с правильной изоляцией ресурсов:

python batch_runner.py --input prompts.jsonl --output results.jsonl

Каждый промпт получает свой собственный task_id и изолированную среду. Если вам нужна собственная логика пакетной обработки, вы можете создать её, используя AIAgent напрямую:

import concurrent.futures
from run_agent import AIAgent

prompts = [
    "Объясни рекурсию",
    "Что такое хеш-таблица?",
    "Как работает сборка мусора?",
]

def process_prompt(prompt):
    # Создаём свежий экземпляр агента для каждой задачи для потокобезопасности
    agent = AIAgent(
        model="anthropic/claude-sonnet-4",
        quiet_mode=True,
        skip_memory=True,
    )
    return agent.chat(prompt)

with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    results = list(executor.map(process_prompt, prompts))

for prompt, result in zip(prompts, results):
    print(f"В: {prompt}\nО: {result}\n")

предупреждение

Всегда создавайте новый экземпляр AIAgent для каждого потока или задачи. Агент поддерживает внутреннее состояние (историю диалога, сессии инструментов, счётчики итераций), которое не является потокобезопасным для совместного использования.

Примеры интеграции

Конечная точка FastAPI

from fastapi import FastAPI
from pydantic import BaseModel
from run_agent import AIAgent

app = FastAPI()

class ChatRequest(BaseModel):
    message: str
    model: str = "anthropic/claude-sonnet-4"

@app.post("/chat")
async def chat(request: ChatRequest):
    agent = AIAgent(
        model=request.model,
        quiet_mode=True,
        skip_context_files=True,
        skip_memory=True,
    )
    response = agent.chat(request.message)
    return {"response": response}

Discord-бот

import discord
from run_agent import AIAgent

client = discord.Client(intents=discord.Intents.default())

@client.event
async def on_message(message):
    if message.author == client.user:
        return
    if message.content.startswith("!vibeos "):
        query = message.content[8:]
        agent = AIAgent(
            model="anthropic/claude-sonnet-4",
            quiet_mode=True,
            skip_context_files=True,
            skip_memory=True,
            platform="discord",
        )
        response = agent.chat(query)
        await message.channel.send(response[:2000])

client.run("YOUR_DISCORD_TOKEN")

Шаг пайплайна CI/CD

#!/usr/bin/env python3
"""Шаг CI: авто-ревью PR-диффа."""
import subprocess
from run_agent import AIAgent

diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()

agent = AIAgent(
    model="anthropic/claude-sonnet-4",
    quiet_mode=True,
    skip_context_files=True,
    skip_memory=True,
    disabled_toolsets=["terminal", "browser"],
)

review = agent.chat(
    f"Проверь этот PR-дифф на наличие багов, проблем безопасности и стиля:\n\n{diff}"
)
print(review)

Ключевые параметры конструктора

Параметр	Тип	По умолчанию	Описание
`model`	`str`	`""`	Модель в формате OpenRouter (по умолчанию пусто; разрешается из вашей конфигурации vibeos во время выполнения)
`quiet_mode`	`bool`	`False`	Подавлять вывод CLI
`enabled_toolsets`	`List[str]`	`None`	Белый список конкретных наборов инструментов
`disabled_toolsets`	`List[str]`	`None`	Чёрный список конкретных наборов инструментов
`save_trajectories`	`bool`	`False`	Сохранять диалоги в JSONL
`ephemeral_system_prompt`	`str`	`None`	Пользовательский системный промпт (не сохраняется в траекториях)
`max_iterations`	`int`	`90`	Максимальное количество итераций вызова инструментов на диалог
`skip_context_files`	`bool`	`False`	Пропустить загрузку файлов AGENTS.md
`skip_memory`	`bool`	`False`	Отключить чтение/запись постоянной памяти
`api_key`	`str`	`None`	API-ключ (использует переменные окружения, если не указан)
`base_url`	`str`	`None`	Пользовательский URL конечной точки API
`platform`	`str`	`None`	Подсказка платформы (`"discord"`, `"telegram"` и т.д.)

Важные замечания

подсказка

Установите skip_context_files=True, если вы не хотите, чтобы файлы AGENTS.md из рабочего каталога загружались в системный промпт.
Установите skip_memory=True, чтобы предотвратить чтение или запись агентом постоянной памяти — рекомендуется для конечных точек API без состояния.
Параметр platform (например, "discord", "telegram") внедряет подсказки форматирования, специфичные для платформы, чтобы агент адаптировал стиль вывода.

предупреждение

Потокобезопасность: Создавайте один AIAgent на поток или задачу. Никогда не используйте один экземпляр в конкурентных вызовах.
Очистка ресурсов: Агент автоматически очищает ресурсы (сессии терминала, экземпляры браузера) после завершения диалога. Если вы работаете в долгоживущем процессе, убедитесь, что каждый диалог завершается нормально.
Лимиты итераций: Значение по умолчанию max_iterations=90 является щедрым. Для простых случаев использования «вопрос-ответ» рассмотрите возможность его уменьшения (например, max_iterations=10), чтобы предотвратить бесконечные циклы вызова инструментов и контролировать расходы.

Установка​

Базовое использование​

Полный контроль над диалогом​

Настройка инструментов​

Многоходовые диалоги​

Сохранение траекторий​

Пользовательские системные промпты​

Пакетная обработка​

Примеры интеграции​

Конечная точка FastAPI​

Discord-бот​

Шаг пайплайна CI/CD​

Ключевые параметры конструктора​

Важные замечания​

Установка

Базовое использование

Полный контроль над диалогом

Настройка инструментов

Многоходовые диалоги

Сохранение траекторий

Пользовательские системные промпты

Пакетная обработка

Примеры интеграции

Конечная точка FastAPI

Discord-бот

Шаг пайплайна CI/CD

Ключевые параметры конструктора

Важные замечания