---
name: create-agent
description: Создать AI-агента на базе aLLModel (allmodel.ru) — OpenAI-совместимый клиент, выбор модели из каталога, streaming, tool calling, обработка ошибок и биллинг.
metadata:
  version: 0.0.0
  homepage: https://allmodel.ru
---

# Создание AI-агента на базе aLLModel

Этот навык помогает собрать AI-агента с помощью aLLModel:

- OpenAI-совместимый клиент (npm-пакет `openai`);
- единый доступ к моделям разных провайдеров через один ключ и один баланс;
- выбор конкретной модели из каталога;
- необязательные streaming и tool calling;
- контроль расходов через ответ API (`usage` и `cost`).

## Предварительные требования

1. Зарегистрируйтесь на https://allmodel.ru и подтвердите email в профиле.
2. Пополните баланс (запросы списываются с кошелька).
3. Создайте API-ключ в личном кабинете: https://allmodel.ru/dashboard?tab=api-keys

Базовый URL API:

```text
https://allmodel.ru/api/v1
```

Аутентификация: заголовок `X-API-Key: <ключ>` или `Authorization: Bearer <ключ>`. Ключи начинаются с `sk_alm_`.

Правила безопасности:

- никогда не коммитьте API-ключи;
- используйте переменные окружения;
- продовые ключи держите только на серверной стороне.

## Выбор модели

Модели выбираются по имени из каталога:

```bash
curl https://allmodel.ru/api/v1/models
```

Ответ — OpenAI-совместимый список: `object: "list"`, `data[]` с полями `id` (имя модели), `name`, `displayName`. В запросе используйте значение `id`.

Конкретное имя модели зависит от текущего каталога — не зашивайте его жёстко, берите из ответа `/api/v1/models`.

## Минимальная настройка

### Шаг 1. Инициализация проекта

```bash
mkdir my-agent && cd my-agent
npm init -y
npm pkg set type="module"
```

### Шаг 2. Установка зависимостей

```bash
npm install openai
npm install -D typescript tsx @types/node
```

### Шаг 3. tsconfig.json

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["src"]
}
```

### Шаг 4. Скрипты

```json
{
  "scripts": {
    "start": "tsx src/agent.ts",
    "dev": "tsx watch src/agent.ts"
  }
}
```

## Структура файлов

```text
src/
├── client.ts
└── agent.ts
```

## Шаг 1. Клиент

Создайте `src/client.ts`:

```typescript
import OpenAI from "openai";

export const client = new OpenAI({
  baseURL: "https://allmodel.ru/api/v1",
  apiKey: process.env.ALLMODEL_API_KEY,
});
```

Ключ задаётся переменной окружения `ALLMODEL_API_KEY`.

## Шаг 2. Базовый agent loop

Создайте `src/agent.ts`:

```typescript
import { client } from "./client.js";

const MODEL = "gpt-4o";

const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
  { role: "system", content: "Ты — полезный ассистент." },
  { role: "user", content: "Привет! Расскажи, что ты умеешь." },
];

const completion = await client.chat.completions.create({
  model: MODEL,
  messages,
});

console.log(completion.choices[0].message.content);
```

Запуск:

```bash
ALLMODEL_API_KEY=sk_alm_... npm run start
```

## Шаг 3. Многошаговый диалог

Чтобы агент умел вести диалог, добавляйте ответ модели в `messages` и отправляйте снова:

```typescript
const reply = completion.choices[0].message;
messages.push(reply);
messages.push({ role: "user", content: "Продолжим." });
```

## Шаг 4. Streaming

```typescript
const stream = await client.chat.completions.create({
  model: MODEL,
  messages,
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
```

## Шаг 5. Tool calling

Передайте определения функций в `tools` и выполните их по `tool_calls`:

```typescript
const completion = await client.chat.completions.create({
  model: MODEL,
  messages,
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Текущая погода в городе",
        parameters: {
          type: "object",
          properties: {
            city: { type: "string" },
          },
          required: ["city"],
        },
      },
    },
  ],
});
```

Если модель запросила вызовы (`finish_reason: "tool_calls"`), выполните их, добавьте результаты в `messages` как сообщения с ролью `tool` и повторите запрос.

## Расходы

Ответ содержит `usage` (prompt/completion/total токены) и `cost` (стоимость запроса):

```json
{
  "usage": { "prompt_tokens": 42, "completion_tokens": 120, "total_tokens": 162 },
  "cost": { "prompt_cost": 0.01, "completion_cost": 0.02, "total_cost": 0.03, "currency": "RUB" }
}
```

## Ошибки

| Код | Причина | Что делать |
|---|---|---|
| 400 | Невалидный `model`, `messages` или системный промпт | Исправьте запрос, проверьте имя модели в каталоге |
| 401 | Неверный или истёкший API-ключ | Проверьте ключ и срок действия |
| 402 | Недостаточно средств на балансе | Пополните кошелёк в личном кабинете |
| 404 | Пользователь не найден | Проверьте ключ |
| 429 | Слишком много запросов | Добавьте ретраи с экспоненциальной задержкой |
| 500 | Ошибка всех источников | Повторите запрос позже |

## Каноническая документация

Для углублённой информации читайте напрямую:

- Полная документация одним файлом: https://allmodel.ru/llms-full.txt
- Индекс документации: https://allmodel.ru/llms.txt
- Обзор API: https://allmodel.ru/docs.md/api/obzor-api.md
- Обращения к моделям: https://allmodel.ru/docs.md/api/obrashcheniya-k-modelyam.md
- Аутентификация и ключи: https://allmodel.ru/docs.md/api/autentifikaciya.md