Skip to content

usage.md

Latest commit

 

History

History
388 lines (300 loc) · 9.96 KB

usage.md

File metadata and controls

388 lines (300 loc) · 9.96 KB

Примеры использования AI Agents CLI

🚀 Быстрый старт

1. Настройка окружения

# Установите переменные окружения
export API_KEY="your-api-key-here"
export PROJECT_ID="your-project-id"

# Или создайте .env файл
echo "API_KEY=your-api-key-here" > .env
echo "PROJECT_ID=your-project-id" >> .env

2. Проверка подключения

# Проверьте статус системы
./ai-agents-cli ci status

📋 Управление MCP серверами

Создание MCP сервера

# Простое создание
./ai-agents-cli mcp-servers create --name "my-database" --description "Database MCP server"

# Создание из конфигурации
./ai-agents-cli mcp-servers create --config database-config.json

Просмотр MCP серверов

# Список всех серверов
./ai-agents-cli mcp-servers list

# С ограничением
./ai-agents-cli mcp-servers list --limit 10 --offset 0

# Подробная информация
./ai-agents-cli mcp-servers get server-id-123

# В JSON формате
./ai-agents-cli mcp-servers get server-id-123 --output json

Управление состоянием

# Приостановка сервера
./ai-agents-cli mcp-servers suspend server-id-123

# Возобновление работы
./ai-agents-cli mcp-servers resume server-id-123

# История операций
./ai-agents-cli mcp-servers history server-id-123

Развертывание

# Развертывание из файла
./ai-agents-cli mcp-servers deploy mcp-servers.yaml

# Предварительный просмотр
./ai-agents-cli mcp-servers deploy --dry-run

# Указание конкретного файла
./ai-agents-cli mcp-servers deploy --file production-config.yaml

🤖 Управление агентами

Поиск в маркетплейсе

# Все доступные агенты
./ai-agents-cli agents marketplace

# Поиск по названию
./ai-agents-cli agents marketplace --name "assistant"

# Фильтрация по тегам
./ai-agents-cli agents marketplace --tags "ai,chat,support"

# Фильтрация по категориям
./ai-agents-cli agents marketplace --categories "customer-service,data-analysis"

# Комбинированный поиск
./ai-agents-cli agents marketplace \
  --name "support" \
  --tags "ai" \
  --categories "customer-service" \
  --types "AGENT_PREDEFINED_TYPE_FREE_TIER"

Управление агентами

# Список агентов
./ai-agents-cli agents list

# Информация об агенте
./ai-agents-cli agents get agent-id-123

# Управление состоянием
./ai-agents-cli agents suspend agent-id-123
./ai-agents-cli agents resume agent-id-123

🔧 CI/CD функции

Проверка статуса

# Общий статус системы
./ai-agents-cli ci status

# Статус конкретного ресурса
./ai-agents-cli ci status mcp-server server-id-123
./ai-agents-cli ci status agent agent-id-123
./ai-agents-cli ci status agent-system system-id-123

# Статус всех ресурсов определенного типа
./ai-agents-cli ci status mcp-servers
./ai-agents-cli ci status agents
./ai-agents-cli ci status agent-systems

Мониторинг логов

# Последние логи
./ai-agents-cli ci logs

# Логи конкретного ресурса
./ai-agents-cli ci logs mcp-server server-id-123

# Мониторинг в реальном времени
./ai-agents-cli ci logs --follow

# Последние 100 записей
./ai-agents-cli ci logs --tail 100

# Логи за определенный период
./ai-agents-cli ci logs --since "2024-01-01" --until "2024-01-31"

✅ Валидация конфигурации

Валидация файлов

# Валидация конкретного файла
./ai-agents-cli validate mcp-servers.yaml

# Валидация всех файлов в директории
./ai-agents-cli validate --dir ./configs

# Валидация с указанием файла
./ai-agents-cli validate --file production-config.json

🎨 Красивый вывод

CLI использует цветовую схему для лучшего восприятия:

  • 🟢 Зеленый - успешные операции, активные ресурсы
  • 🔴 Красный - ошибки, неактивные ресурсы
  • 🟡 Желтый - предупреждения, приостановленные ресурсы
  • 🔵 Синий - информация, заголовки
  • ⚪ Серый - нейтральная информация

📊 Примеры конфигураций

MCP серверы (mcp-servers.yaml)

mcp-servers:
  - name: "database-mcp"
    description: "MCP сервер для работы с PostgreSQL базой данных"
    instanceTypeId: "58a24a3d-b126-47a5-a39c-30a8aeaa4721"
    imageSource:
      arImageUri: "cr.cloud.ru/prod/mcp/database-mcp:latest"
    exposedPorts:
      - 5432
    options:
      connection_pool_size: 20
      query_timeout: 60
    environmentOptions:
      rawEnvs:
        LOG_LEVEL: "INFO"
      secretEnvs:
        db_password:
          id: "123e4567-e89b-12d3-a456-426614174000"
          version: 1
    scaling:
      minScale: 2
      maxScale: 10
    integrationOptions:
      authOptions:
        isEnabled: true
        type: "AUTHENTICATION_TYPE_BASIC"
      logging:
        isEnabledLogging: true

Агенты (agents.yaml)

agents:
  - name: "customer-support-agent"
    description: "AI агент для поддержки клиентов"
    instanceTypeId: "58a24a3d-b126-47a5-a39c-30a8aeaa4721"
    imageSource:
      arImageUri: "cr.cloud.ru/prod/agents/customer-support:latest"
    options:
      systemPrompt: "Ты - профессиональный агент поддержки клиентов"
      llm:
        foundationModels:
          modelName: "gpt-4o"
      env:
        rawEnvs:
          OPENAI_API_KEY: "${OPENAI_API_KEY}"
      scaling:
        minScale: 1
        maxScale: 10
    integrationOptions:
      authOptions:
        isEnabled: true
        type: "AUTHENTICATION_TYPE_API_KEY"
      logging:
        isEnabledLogging: true
    mcpServers:
      - "database-mcp"
      - "ticket-system-mcp"

🔄 CI/CD интеграция

GitHub Actions

name: Deploy AI Agents
on:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Validate configuration
        run: ./ai-agents-cli validate
        env:
          API_KEY: ${{ secrets.API_KEY }}
          PROJECT_ID: ${{ secrets.PROJECT_ID }}

  deploy:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy MCP servers
        run: ./ai-agents-cli mcp-servers deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
          PROJECT_ID: ${{ secrets.PROJECT_ID }}
      - name: Deploy agents
        run: ./ai-agents-cli agents deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}
          PROJECT_ID: ${{ secrets.PROJECT_ID }}

  verify:
    needs: deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check deployment status
        run: ./ai-agents-cli ci status
        env:
          API_KEY: ${{ secrets.API_KEY }}
          PROJECT_ID: ${{ secrets.PROJECT_ID }}

GitLab CI

stages:
  - validate
  - deploy
  - verify

validate:
  stage: validate
  script:
    - ./ai-agents-cli validate
  only:
    - main

deploy:
  stage: deploy
  script:
    - ./ai-agents-cli mcp-servers deploy
    - ./ai-agents-cli agents deploy
  only:
    - main

verify:
  stage: verify
  script:
    - ./ai-agents-cli ci status
  only:
    - main

🐛 Отладка

Включение детального логирования

# Детальные логи
./ai-agents-cli --verbose mcp-servers list

# Логи в JSON формате
./ai-agents-cli mcp-servers get server-id --output json

Проверка подключения

# Проверка статуса API
./ai-agents-cli ci status

# Проверка конкретного ресурса
./ai-agents-cli mcp-servers get server-id

📝 Лучшие практики

  1. Всегда валидируйте конфигурацию перед развертыванием
  2. Используйте dry-run для предварительного просмотра
  3. Мониторьте логи после развертывания
  4. Используйте переменные окружения для секретов
  5. Версионируйте конфигурации в Git
  6. Настройте CI/CD для автоматического развертывания

🆘 Решение проблем

Частые ошибки

# Ошибка аутентификации
Error: API_KEY environment variable is required
# Решение: Установите переменную API_KEY

# Ошибка проекта
Error: PROJECT_ID environment variable is required  
# Решение: Установите переменную PROJECT_ID

# Ошибка валидации
Error: Configuration validation failed
# Решение: Проверьте синтаксис конфигурационного файла

Получение помощи

# Общая справка
./ai-agents-cli --help

# Справка по команде
./ai-agents-cli mcp-servers --help
./ai-agents-cli agents --help
./ai-agents-cli ci --help

AI Agents CLI - ваш надежный помощник в управлении AI агентами! 🚀