---
id: guide-agents
title: "Путеводитель для агента"
kind: guide
---

# Путеводитель для агента {#guide-agents}

Человекочитаемый компаньон к машинным точкам входа `/llms.txt` и `/docs/agents`
(они отдаются сервером как обычный текст). Здесь — ориентиры и ссылки в канон.

## Аутентификация и формат

- Каждый запрос — заголовок `Authorization: Bearer tak_...` (токен заводится в
  профиле, «Токены API» — [создать токен](../domains/auth/api/create-token.md#auth-create-token)).
  Токен действует **как его владелец**, под его ролью.
- Scope токена: `read` (только `GET`) или `read_write` (`GET` + мутации).
- Формат: cookie-клиент получает JSON; токен с `Accept: text/markdown` (или
  `?format=md`) — Markdown-зеркало ресурса. У ресурсов есть `ETag` →
  `If-None-Match` → `304`. Подробнее — [Конвенции](../shared/conventions.md#conventions).
- **site-admin**-операции недоступны никакому токену на любом scope.

## Кто я и что вижу

- [`GET /api/users/me`](../domains/auth/api/users-me.md#auth-users-me) — кто владелец токена и его активная организация.
- [Контекст «где я»](../domains/auth/api/agent-context.md#auth-agent-context) — активная организация, последний проект и вид (удобная точка входа в сессию).
- [Список проектов](../domains/projects/api/list-projects.md#projects-list-projects) ·
  [проект](../domains/projects/api/get-project.md#projects-get-project) ·
  [граф](../domains/projects/api/get-project-graph.md#projects-get-project-graph)
  (`view=summary|full`, `diff_from`, ETag).

## Что можно делать с проектом

С токеном `read_write` (под своей ролью) доступны те же действия, что в UI:
[создать](../domains/projects/api/create-project.md#projects-create-project),
[сгенерировать граф (SSE)](../domains/projects/api/generate-graph.md#projects-generate-graph),
[обновить](../domains/projects/api/update-project.md#projects-update-project),
[удалить](../domains/projects/api/delete-project.md#projects-delete-project) /
[восстановить](../domains/projects/api/restore-project.md#projects-restore-project),
[передать в организацию](../domains/projects/api/transfer-project.md#projects-transfer-project),
[сменить владельца](../domains/projects/api/transfer-owner.md#projects-transfer-owner),
[share-ссылка](../domains/projects/api/share-project.md#projects-share-project).

Действие, на которое у вашей роли нет права (не тот tier / чужой спейс / чужая
организация) → `403` с причиной.

## Что менялось (ленты изменений)

Хронику правок ресурса (кто, что, когда — сгруппировано по операциям) отдают
ленты изменений: [проекта](../domains/projects/api/project-activity.md#projects-project-activity) ·
[коллекции](../domains/collections/api/collection-activity.md#collections-collection-activity) ·
[спейса](../domains/spaces/api/space-activity.md#spaces-space-activity)
(`limit`, `depth`; Markdown-зеркало). Право видеть ленту не слабее чтения самого
ресурса; гостю/share-ссылке лента недоступна.

## Дизайн-документ проекта

У проекта есть пояснительный документ по блокам: читать [целиком](../domains/design-doc/api/get-doc-content.md#design-doc-get-doc-content) или [по блоку](../domains/design-doc/api/get-block-content.md#design-doc-get-block-content) (с Markdown-зеркалом и ETag), генерировать потоком (SSE) [блок](../domains/design-doc/api/generate-block.md#design-doc-generate-block) или [весь документ](../domains/design-doc/api/generate-all.md#design-doc-generate-all), [править](../domains/design-doc/api/update-block-content.md#design-doc-update-block-content) и [откатывать версии](../domains/design-doc/api/restore-block-version.md#design-doc-restore-block-version). Полный список — домен [Дизайн-документ](../domains/design-doc/index.md#design-doc-index).

## Коллекции (токен org-admin)

Коллекции — шаблоны, по которым строятся проекты. Под токеном org-admin доступны
чтение и управление: [список](../domains/collections/api/list-collections.md#collections-list-collections) ·
[получить](../domains/collections/api/get-collection.md#collections-get-collection) ·
[создать](../domains/collections/api/create-collection.md#collections-create-collection) ·
[(пере)генерация](../domains/collections/api/regenerate.md#collections-regenerate) (modes + SSE) ·
содержимое ([блоки](../domains/collections/api/create-block.md#collections-create-block),
[слои](../domains/collections/api/create-layer.md#collections-create-layer),
[специальности](../domains/collections/api/create-specialty.md#collections-create-specialty),
[связи](../domains/collections/api/create-edge.md#collections-create-edge)) ·
[промпты](../domains/collections/api/get-prompts.md#collections-get-prompts). Полный
список — [домен Коллекции](../domains/collections/index.md#collections-index).
Межорганизационный доступ к коллекции (grant/revoke) — site-admin only, токену недоступно.

## Спейсы (рабочие пространства)

Спейс — пространство команды по коллекции с оверлеем (свои правки поверх шаблона).
Под токеном доступны чтение ([список](../domains/spaces/api/list-spaces.md#spaces-list-spaces) ·
[спейс](../domains/spaces/api/get-space.md#spaces-get-space) с Markdown-зеркалом и ETag ·
[блоки](../domains/spaces/api/list-blocks.md#spaces-list-blocks) /
[слои](../domains/spaces/api/list-layers.md#spaces-list-layers) /
[специальности](../domains/spaces/api/list-specialties.md#spaces-list-specialties) /
[связи](../domains/spaces/api/list-edges.md#spaces-list-edges)) и — под ролью менеджера
спейса или org-admin — управление оверлеем (переопределить / снять / удалить / вернуть),
участниками и наблюдателями. Полный список — домен [Спейсы](../domains/spaces/index.md#spaces-index).

---

Human view: https://docs.vnimanie.ai/specbuilder/v1/guides/agents/