talonicdev/talonic-mcp

Задаёт вопрос на естественном языке по документам рабочего пространства и получает ответ с цитатами и проверкой (markdown). Агент Talonic строит план по структурированной плоскости полей, выполняет SQL-запросы только для чтения по извлечённым ячейкам, читает текст документов и обосновывает каждое ключевое утверждение ссылкой на исходный фрагмент. Расходует кредиты. КОГДА ИСПОЛЬЗОВАТЬ: пользователь задаёт открытый вопрос о своих документах ('какие поставщики выставили нам счёт дважды в мае?'), хочет получить сводку по документам, или ответ требует рассуждений по нескольким полям. НЕ ДЛЯ: чтения значений известного поля (talonic_field_values, бесплатно) или фильтрации документов по известному значению (talonic_filter, бесплатно); поиска, в каком поле хранится понятие (talonic_find_data). АРГУМЕНТЫ: question; необязательный scope { document_ids[], schema_id, pipeline_id, data_product_id, document_type, source_id, tags[], ingested_after, ingested_before } (объединяются по И), conversation_id (продолжить ветку), output_format { instruction, template }, wait_seconds (0–55, по умолчанию 45). ВОЗВРАЩАЕТ: { ask_id, status ('completed'|'processing'|'error'), conversation_id, answer (markdown), citations[] { quote, document_id, kind, filename, app_url }, verification { verdict, checks_total, checks_unsupported, correction }, usage { tokens, credits_charged }, tool_calls, artifacts[], waited_ms }. Если status всё ещё 'processing' после ожидания, вызовите talonic_get_answer с ask_id.

Захватывает доступную задачу Agent-stage или повторно захватывает её после истечения срока аренды. КОГДА ИСПОЛЬЗОВАТЬ: когда готовы обработать задачу. Сохраните возвращённые execution_epoch и lease_expires_at. НЕ ДЛЯ: простого просмотра работы (используйте talonic_get_agent_task) или продления активной аренды (используйте talonic_heartbeat_agent_task). Конфликтующий активный захват возвращает HTTP 409. Успешный захват возвращает полезную нагрузку задачи: input_snapshot, instructions и output_contract, в записях которых указаны правила Spec для каждого поля (description) и разрешённые коды (enumValues). Сверьте документы с этими правилами.

Забирает доступную задачу решения (или перезабирает ту, у которой истёк срок аренды) и получает пакет решения: метаданные задачи с новым execution_epoch, output_contract, precedents и дескриптор пакета { package_kind, record_count, page_size, first_cursor, documents }. КОГДА ИСПОЛЬЗОВАТЬ: когда вы готовы решить задачу из списка. Отдельного get нет: сам захват И ЕСТЬ получение полезной нагрузки. Сохраните execution_epoch и lease_expires_at, затем читайте записи через talonic_read_decision_package, начиная с first_cursor (null означает, что в пакете нет записей). НЕ ПОДХОДИТ ДЛЯ: продления активной аренды (talonic_heartbeat_decision_task) или возврата решения (talonic_submit_decision_task). Конфликтующий активный захват возвращает HTTP 409. АВТОРИЗАЦИЯ: ключу tlnc_ нужен грант 'decide' для приложения; сессии OAuth-коннектора нужен scope apps:decide (согласованный при подключении) и активная роль в рабочем пространстве senior_member или выше. Код 403 (decide_grant_required, insufficient_scope, insufficient_tier) называет, чего не хватает: скажите об этом пользователю и не повторяйте попытку.

Извлекает структурированный JSON с проверкой по схеме из документа: PDF, скана, изображения, DOCX, письма или фото. Возвращает запрошенные поля с оценкой уверенности по каждому полю. КОГДА ИСПОЛЬЗОВАТЬ: пользователь просит извлечь данные из документа, превратить PDF в JSON, вытащить поля из файла или распарсить скан / форму / выписку / чек / отчёт, для типовых (счёт, договор) или необычных типов документов. НЕ ДЛЯ: полного простого текста (используйте talonic_to_markdown) · поиска документов (используйте talonic_search / talonic_filter). ПО ИМЕНИ: если пользователь называет файл, сначала вызовите talonic_search, чтобы получить его document_id, затем вызывайте этот инструмент. АРГУМЕНТЫ: задайте нужные поля через инлайн-schema (JSON Schema, например {type:'object',properties:{vendor_name:{type:'string'}}}) ИЛИ сохранённый schema_id, но не оба сразу. Ещё не знаете поля? Поставьте auto_schema:true, чтобы Talonic сам их нашёл (open capture) и вернул предложенную схему, которую вы потом доработаете. Укажите РОВНО ОДИН источник документа: document_id (дешевле всего, документ из рабочего пространства), file_url (публичный URL) или file_data+filename (только небольшие локальные файлы). СТОИМОСТЬ: каждый вызов тратит кредиты; talonic_get_balance показывает остаток баланса. ВОЗВРАЩАЕТ: data (сам JSON), confidence.overall и confidence.fields (считайте <0.7 как «нужна проверка»), метаданные документа, extraction_id.

Сообщает, что заявленную задачу решения решить нельзя: создаёт Human Review с вашей причиной И применяет объявленную приложением резервную политику (правила решают, удержать на проверку или завалить запуск). КОГДА ИСПОЛЬЗОВАТЬ: пакет неполный или противоречивый, и ни один заявитель не смог по нему решить. Это завершает задачу (статус 'failed'). НЕ ИСПОЛЬЗОВАТЬ ДЛЯ: временных возвратов (talonic_release_decision_task) или решения, которое вы можете принять с низкой уверенностью (отправьте его с указанным confidence). АРГУМЕНТЫ: task_id, execution_epoch, reason (до 2 000 символов). Устаревший epoch - HTTP 409. АВТОРИЗАЦИЯ: ключу tlnc_ нужен грант 'decide' для каждого приложения; сессии OAuth-коннектора нужен scope apps:decide (согласованный при подключении) и активная роль в рабочем пространстве senior_member или выше. Код 403 (decide_grant_required, insufficient_scope, insufficient_tier) называет то, чего не хватает - сообщите об этом пользователю, не повторяйте попытку.

Читает ТЕКУЩИЕ ЗНАЧЕНИЯ поля по всем документам с указанием источника - по одной строке на каждое связанное вхождение: идентификатор документа + имя файла + тип, значение, уверенность, исходное имя, под которым оно было захвачено, дословный исходный текст и диапазон разрешения, который его связал. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь спрашивает «какие все X есть в моих документах», нужно свести в таблицу или агрегировать одно понятие по всему корпусу или нужны доказательства (исходный текст + документ), стоящие за значением. НЕ ДЛЯ: многополевых построчных запросов по документам (talonic_filter) или полного набора полей одного документа (talonic_get_document). АРГУМЕНТЫ: ровно один из field_id или name; опционально document_id (один документ), value (фильтр по вхождению без учёта регистра), limit (максимум 100), cursor. ВОЗВРАЩАЕТ: { field_id, canonical_name, concept_ids, data[] из { occurrence_id, document_id, document_filename, value, confidence, provenance{ raw_field_name, source_text, resolved_by, needs_confirmation, via_redirect }, links }, pagination }. Строки отфильтрованы по Sources-IAM для вызывающего.

Находит документы по значениям извлечённых полей с помощью составляемых условий (например, «счета, где total > 1000»). ИСПОЛЬЗУЙ, КОГДА: нужны условия на основе значений извлечённых полей — сравнения чисел/дат/текста или проверки наличия. НЕ ДЛЯ: полнотекстового / смыслового поиска (используй talonic_search) · поиска одного документа по id (используй talonic_get_document). АРГУМЕНТЫ: conditions[] (AND-логика). Каждый = РОВНО ОДИН из field (каноническое имя) или field_id (UUID), operator и обычно value. Операторы: eq, neq, gt, gte, lt, lte, between (требует value И value_to), contains, is_empty / is_not_empty (без value). value/value_to — string|number|boolean в соответствии с типом поля (для дат — ISO YYYY-MM-DD). ТЕКСТОВЫЕ ФИЛЬТРЫ: для eq/contains/is_not_empty по текстовому полю просто ПОПРОБУЙ естественное имя поля ('currency', 'vendor_name') — имена разрешаются на сервере, и неразрешённое поле попадает в warnings[], а не в ошибку. НЕ блокируйся на предварительном определении поля; search-first требуется только для числовых операторов. ЧИСЛОВАЯ ЗАЩИТА: gt/gte/lt/lte/between работают только если dataType поля равен 'number'. Сначала вызови talonic_search и проверь dataType; числовая операция над строковым полем возвращает ноль совпадений. Если в ответе есть warnings[], покажи их пользователю — не делай повторных попыток молча. ВОЗВРАЩАЕТ: data[] (подходящие документы со значениями полей), total, warnings[].

Находит РЕАЛЬНЫЕ данные, стоящие за понятием на естественном языке, до выполнения любых запросов: семантический и лексический поиск, который сопоставляет фразу ('объём платежей за транзакцию', 'контрагент', 'Vertragslaufzeit') с полями реестра, значениями, документами и текстовыми фрагментами, которые её содержат, даже если поле записано под другим именем. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь спрашивает о понятии, а вы не уверены, в каком поле оно хранится, когда talonic_list_fields / talonic_search вернули пустые или неоднозначные результаты, или когда ответ может находиться в тексте документа, а не в записанной ячейке. НЕ ДЛЯ: чтения значений известного поля (talonic_field_values) или фильтрации по известному полю (talonic_filter). АРГУМЕНТЫ: query (понятие, словами пользователя), необязательный top_k (1–25, по умолчанию 10), document_ids (жёсткая область поиска). ВОЗВРАЩАЕТ: ранжированные уровни - ПОЛЯ (canonical_name, идентификаторы полей/ключи, зрелость/уровень, occurrence_count, примеры значений с их документами), ЗНАЧЕНИЯ, ДОКУМЕНТЫ и ФРАГМЕНТЫ - каждый элемент готовый указатель для следующего вызова. Только чтение, без затрат LLM.

Получает неизменяемый снимок входных данных, инструкции и объявленный контракт вывода для одной задачи этапа агента. Это раскрытие проверяется. ИСПОЛЬЗУЙТЕ, КОГДА: осматриваете задачу из списка перед принятием решения, обрабатывать ли её. НЕ ДЛЯ: получения задачи (используйте talonic_claim_agent_task) или возврата результатов (используйте talonic_submit_agent_task). АРГУМЕНТЫ: task_id. ВОЗВРАЩАЕТ: metadata, input_snapshot, output_contract, instructions и timeout_fallthrough.

Опрашивает запрос, запущенный talonic_ask, который всё ещё обрабатывался, когда ожидание завершилось. ИСПОЛЬЗУЙТЕ, КОГДА: talonic_ask вернул статус 'processing' с ask_id, опрашивайте каждые несколько секунд, пока не появится 'completed' или 'error'. НЕ ДЛЯ: задать новый вопрос (talonic_ask). АРГУМЕНТЫ: ask_id. ВОЗВРАЩАЕТ: ту же обёртку ответа, что и talonic_ask (answer, citations[], verification, usage), или { status: 'processing', poll_hint }.

Читает баланс кредитов Talonic рабочего пространства, его стоимость в евро, тариф, расход за 30 дней и прогнозируемый остаток работы. ИСПОЛЬЗУЙТЕ КОГДА: пользователь спрашивает о кредитах/бюджете, или перед большой пакетной обработкой, когда нужно подтвердить наличие запаса. НЕ ДЛЯ: стоимости одного вызова извлечения (она возвращается в ответе talonic_extract). АРГУМЕНТЫ: нет. ВОЗВРАЩАЕТ: balance_credits, balance_eur, tier, burn_rate_30d_credits, projected_runway_days (-1 = недавнего использования нет), tier_resets_at.

Извлекает метаданные и статус обработки одного документа из рабочего пространства. ИСПОЛЬЗУЙТЕ, КОГДА: «расскажи о документе X» или для опроса статуса после talonic_request_upload, пока файл не будет готов. НЕ ДЛЯ: полного текста (используйте talonic_to_markdown) · извлечённых полей (используйте talonic_extract). ПО ИМЕНИ: если пользователь называет файл, сначала вызовите talonic_search, чтобы получить его document_id, затем вызовите этот инструмент. АРГУМЕНТЫ: document_id. ВОЗВРАЩАЕТ: filename, pages, type_detected, language и status. Жизненный цикл статуса: pending_upload -> uploading -> queued -> extracting -> completed. Дождитесь completed перед вызовом talonic_extract для только что загруженного документа. Конечные статусы ошибок: ocr_failed, extraction_failed, error — прекратите опрос и сообщите об ошибке пользователю, если появится любой из них. Чтобы прочитать текст документа, вызовите talonic_to_markdown с этим id.

Получает КОНЦЕПТ-КАРТУ для одного поля Field Registry: что оно означает (курируемое описание + инструкция по извлечению), его синонимы и алиасы, зрелость, где оно встречается (количество документов/вхождений, первое/последнее появление, распределение по типам документов), распределение значений (основные значения с количеством, количество уникальных значений, примеры), использование в схемах и связи идентичности (superseded_by, absorbed concepts). ИСПОЛЬЗУЙ, КОГДА: нужно решить, подходит ли поле для вопроса, нужны примеры значений или форма значений перед написанием фильтра, или есть ИМЯ поля от пользователя и нужна актуальная концепция за ним. НЕ ДЛЯ: перечисления множества полей (talonic_list_fields) или чтения всех значений (talonic_field_values). АРГУМЕНТЫ: ровно один из field_id или name. Имена разрешаются через каноническое имя → свёртку написания → объединение алиасов → синонимы (затем регистронезависимые запасные варианты) и доводятся до актуальной концепции; ответ показывает, какая ветка сработала. include_history: true добавляет журнал курирования (объединения, переименования, изменения зрелости). ВОЗВРАЩАЕТ: карту { id, canonical_name, maturity, data_type, definition, identity, occurrence, values, usage, links } плюс resolution, если указано имя, и history, если оно запрошено.

Читает машиночитаемый каталог цен на кредиты Talonic: фиксированные ставки за единицу, чтобы вы могли предсказать расходы ДО запуска чего-либо. ИСПОЛЬЗУЙТЕ КОГДА: оцениваете стоимость запланированной задачи по извлечению/структурированию/сопоставлению или отвечаете на вопрос о цене. Публичный - работает без траты кредитов. НЕ ДЛЯ: текущего баланса рабочего пространства (используйте talonic_get_balance) или того, что оно уже потратило (используйте talonic_get_usage). АРГУМЕНТЫ: нет. ВОЗВРАЩАЕТ: currency, credits_per_eur, multipliers (например, batch 0.5x) и units[] - каждый { unit, label, credits, eur, free }.

Опрашивает прогон Spec, запущенный talonic_run_spec: нормализованный статус, прогресс на уровне документов и, для пайплайнов, прогресс по фазам. КОГДА ИСПОЛЬЗОВАТЬ: ждёте завершения прогона - опрашивайте каждые 5-10 с; останавливайтесь при completed или failed. НЕ ДЛЯ: чтения структурированных строк (talonic_get_run_results) или запуска прогона (talonic_run_spec). АРГУМЕНТЫ: ровно один из pipeline_id (run_kind 'pipeline') или run_id (run_kind 'run'), из RunEnvelope. ВОЗВРАЩАЕТ: { run_kind, run_id, pipeline_id, spec_id, status, raw_status, input_count?, progress { total_documents, completed_documents, error_documents, phases?[] }, documents?[], error_message?, created_at, updated_at }.

Читает структурированные строки запуска Spec: одна строка на документ, поля Spec в виде чистых значений (ячейки held/pending-review сериализуются в null), плюс определения столбцов. КОГДА ИСПОЛЬЗОВАТЬ: talonic_get_run сообщает completed (частичные строки тоже можно читать, пока идёт processing). НЕ ДЛЯ: прогресса (talonic_get_run) или provenance по полям для одного значения (здесь include: ['provenance'] или talonic_field_values). АРГУМЕНТЫ: ровно один из pipeline_id (run_kind 'pipeline', необязательно с run_id из обёртки, чтобы ограничить этой отправкой) или только run_id (run_kind 'run'); необязательные document_id (один документ), include (['cells','provenance'] - более тяжёлая нагрузка), limit (1–200, по умолчанию 50), cursor. ВОЗВРАЩАЕТ: { run_kind, status, columns[] из { field_key, display_name, data_type }, data[] из { document_id, filename, record_id, status ('complete'|'partial'|'error'|'processing'), completed_at, fields { field_key: value }, cells?, provenance? }, pagination, pending_review_count, links }.

Получает структуру одной Spec: идентичность и состояние версии, схему, на которую она материализуется, nodes[] (rail в том виде, как он задан автором, в порядке редактирования) и phases[] (скомпилированный план выполнения, в порядке запуска - точка проверки валидации разворачивается в одну фазу на каждый gate, поэтому эти два списка различаются намеренно), а также fields[] (поле Spec ↔ поле схемы). КОГДА ИСПОЛЬЗОВАТЬ: нужно объяснить, что сделает запуск, убедиться, что Spec опубликована (version не null), перед talonic_run_spec, или сопоставить имена полей с ключами. НЕ ДЛЯ: перечисления Spec (talonic_list_specs) или старта запуска (talonic_run_spec). АРГУМЕНТЫ: spec_id (UUID из talonic_list_specs); необязательный include_versions (добавляет versions[] - опубликованные версии, сначала самые новые, каждая { version, content_hash, created_at, is_materialized }). ВОЗВРАЩАЕТ: объект Spec { id, name, description, schema_id, version, materialized_version, materialized_at, field_count, node_count, schema, nodes[], phases[], fields[], links } плюс необязательный versions[].

Читает потребление кредитов по функциям рабочего пространства за скользящее окно: куда на самом деле ушли кредиты. ИСПОЛЬЗОВАТЬ КОГДА: пользователь спрашивает, на что он потратил кредиты, или вы хотите увидеть, какая функция (извлечение, структурирование, интеллектуальные операции) доминирует в затратах. НЕ ДЛЯ: остатка на балансе (используйте talonic_get_balance) или тарифов за единицу (используйте talonic_get_pricing). ПАРАМЕТРЫ: days (необязательный, по умолчанию 30, ограничение 1-365). ВОЗВРАЩАЕТ: period_days, total_credits и by_function[] - каждый { operation_type, operations, credits }, сначала наибольшие затраты.

Продлевает аренду на закреплённую задачу этапа агента. КОГДА ИСПОЛЬЗОВАТЬ: обработка может продолжаться после lease_expires_at; отправьте сердцебиение до истечения срока, используя значение epoch из закрепления. НЕ ДЛЯ: получения задачи (используйте talonic_claim_agent_task) или отправки завершённых результатов (используйте talonic_submit_agent_task). АРГУМЕНТЫ: task_id и execution_epoch. Устаревшие или чужие закрепления возвращают HTTP 409.

Продлевает срок аренды на взятую в работу задачу принятия решения, никогда не позднее её sla_deadline_at. ИСПОЛЬЗУЙТЕ, КОГДА: принятие решения может продлиться дольше, чем lease_expires_at; отправьте heartbeat до истечения срока, используя epoch из claim. НЕ ДЛЯ: получения задачи (talonic_claim_decision_task) или завершения (talonic_submit_decision_task / talonic_release_decision_task / talonic_fail_decision_task). АРГУМЕНТЫ: task_id и execution_epoch. Устаревший или чужой epoch возвращает HTTP 409: остановитесь, отбросьте работу и запросите список заново. АВТОРИЗАЦИЯ: ключу tlnc_ нужно разрешение 'decide' для конкретного приложения; сессии OAuth connector требуется scope apps:decide (согласованный при подключении) и активная роль в рабочем пространстве senior_member или выше. Ошибка 403 (decide_grant_required, insufficient_scope, insufficient_tier) указывает, чего не хватает: сообщите пользователю, не повторяйте попытку.

Вызывает ОДИН именованный инструмент из реестра инструментов агента платформы напрямую, без модели в цикле - аргументы выбирает вызывающая сторона. Так внешний агент использует поиск и происхождение данных Talonic, сам управляя потоком управления (например, query_data для SQL SELECT только для чтения по извлечённым данным, describe_data для списка полей, доступных для запросов, get_document_markdown для чтения текста документа). ТОЛЬКО ДЛЯ ЧТЕНИЯ ПО СВОЕЙ ПРИРОДЕ: платформа ограничивает учётные данные API-ключа инструментами реестра только для чтения (возможность data.read); инструменты реестра с правом записи никогда не вызываются через эти учётные данные, поэтому через учётные данные API-ключа этот инструмент читает и никогда не изменяет данные рабочего пространства. Целевой API: реестр инструментов агента Talonic - https://talonic.com/docs/api (POST /v1/agent/tools/{name}/invoke; входные схемы из talonic_list_agent_tools). КОГДА ИСПОЛЬЗОВАТЬ: talonic_list_agent_tools показал инструмент с can_invoke: true, который делает то, что нужно. Ожидает ровно те args, которые объявляет его input_schema. НЕ ДЛЯ: всего, что уже делает специализированный инструмент talonic_* (они предпочтительнее - они заточены под вас). АРГУМЕНТЫ: name (имя инструмента), args (объект, соответствующий input_schema инструмента), необязательный document_ids (жёсткое ограничение области для инструментов, которые учитывают область). ВОЗВРАЩАЕТ: { tool, result (разобранный вывод инструмента), citations?, artifacts?, cards? }. Отклонённые возможности возвращаются ошибкой с именем требуемой возможности; платформа перепроверяет каждый вызов.

Показывает задачи стадии Agent, видимые этим учётным данным рабочего пространства Talonic. КОГДА ИСПОЛЬЗОВАТЬ: когда ищете работу для внешнего агента; начинайте со статуса 'available'. Чтобы забрать пачку задач одного пайплайна (например, 'take 10 tasks of pipeline X'), запросите список с pipeline_id и статусом 'available', а затем заберите каждую через talonic_claim_agent_task; задача, которую уже забрал другой агент, вернёт HTTP 409, так что пропустите её и берите следующую. НЕ ДЛЯ: чтения неизменяемого payload задачи (используйте talonic_get_agent_task) или взятия аренды (используйте talonic_claim_agent_task). АРГУМЕНТЫ: необязательные status, pipeline_id, limit и cursor. ВОЗВРАЩАЕТ: только метаданные плюс pagination.next_cursor.

Перечисляет реестр инструментов агента платформы - все примитивы поиска, происхождения и анализа, на которых работает встроенный агент Talonic (find_data, describe_data, query_data для SQL-запросов только для чтения по извлечённым данным, get_document_markdown, workspace_overview, …) вместе с их входными схемами и указанием, может ли ЭТОТ ключ доступа вызвать каждый из них. Целевой API: https://talonic.com/docs/api (GET /v1/agent/tools). КОГДА ИСПОЛЬЗОВАТЬ: вам нужна возможность, которую инструменты talonic_* не покрывают напрямую (например, SQL по структурированным данным, обзор рабочего пространства, поиск когорты) - перечислите здесь, затем вызовите talonic_invoke_agent_tool с именем инструмента и его аргументами. НЕ ДЛЯ: обнаружения полей (talonic_list_fields / talonic_find_data) или документов (talonic_search) - они уже сделаны под вас. АРГУМЕНТЫ: only_invocable (по умолчанию true - скрывает инструменты, которые этот ключ не может запустить), include_schemas (по умолчанию true - включает JSON-схему входных данных каждого инструмента). ВОЗВРАЩАЕТ: { tools[] из { name, description, impact, capability, can_invoke, input_schema? }, invocable_count, totalCount }.

Перечисляет задачи принятия решений одного приложения в режиме External (запуски, приостановленные в ожидании решения внешнего агента), сначала самые новые. КОГДА ИСПОЛЬЗОВАТЬ: когда ищете решения, которые нужно принять для приложения; начинайте со статуса 'available'. Это альтернатива вебхуку app.decision_task.offered на основе опроса. НЕ ДЛЯ: задач с документами на этапе агента (используйте talonic_list_agent_tasks), чтения входного пакета задачи (заберите её, затем talonic_read_decision_package) или взятия лизы (talonic_claim_decision_task). АРГУМЕНТЫ: app_id, необязательные status, limit, cursor. ВОЗВРАЩАЕТ: только метаданные задачи (id, run_id, status, execution_epoch, тайминги lease и sla_deadline_at) плюс pagination.next_cursor. АВТОРИЗАЦИЯ: ключу tlnc_ нужен грант 'decide' для конкретного приложения; сессии OAuth-коннектора нужны scope apps:decide (согласованный при подключении) и действующая роль в рабочем пространстве senior_member или выше. Ошибка 403 (decide_grant_required, insufficient_scope, insufficient_tier) указывает, чего не хватает - скажите об этом пользователю, не повторяйте попытку.

Перечисляет реестр полей рабочего пространства - канонические концепции, которые Talonic обнаружил во всех обработанных документах. Каждая концепция содержит стабильный идентификатор, уровень зрелости, тип данных, синонимы и количество упоминаний. ИСПОЛЬЗУЙТЕ, КОГДА: нужно узнать, КАКИЕ данные существуют перед выполнением запроса, выбрать подходящую концепцию для вопроса или получить точный идентификатор поля для talonic_get_field / talonic_field_values. НЕ ДЛЯ: поиска конкретного документа (talonic_search) или фильтрации документов по значению (talonic_filter). АРГУМЕНТЫ: search (регистронезависимое вхождение в имени), maturity (core | proven | candidate - для всего, на чём будете строить, предпочитайте core/proven), include_superseded (по умолчанию false: строки, объединённые с другой концепцией, скрываются, чтобы вы никогда не видели два идентификатора для одной концепции), limit, cursor. ВОЗВРАЩАЕТ: data[] из { id, canonical_name, display_name, data_type, maturity, tier, synonyms, description, occurrence_count, superseded_by, links } плюс постраничную навигацию через cursor.

Перечисляет сохранённые схемы в рабочем пространстве в виде компактных сводок (id, short_id, name, description, version, field_count). ИСПОЛЬЗУЕТСЯ КОГДА: «what schemas do I have» или для поиска переиспользуемой схемы перед извлечением. НЕ ДЛЯ: одноразового извлечения со встроенной схемой (вызывайте talonic_extract напрямую). АРГУМЕНТЫ: нет. ВОЗВРАЩАЕТ: data[] со сводками схем. Полные определения полей здесь опущены — для их получения прочитайте ресурс talonic://schemas. Передавайте id/short_id схемы в talonic_extract как schema_id.

Перечисляет Specs рабочего пространства - настроенные пайплайны (rail + поля), которые выполняет talonic_run_spec. Каждая строка: id, name, description, schema_id (схема, на которую материализуется запуск - ДРУГОЙ id, отличный от id самого Spec), version / materialized_version (null = никогда не публиковался), field_count, node_count, метки времени. USE WHEN: пользователь хочет запустить «свой пайплайн» / «Spec для счетов», либо вам нужен spec_id для talonic_run_spec / talonic_get_spec. NOT FOR: схемы разового извлечения (talonic_list_schemas) или поиск полей (talonic_list_fields). ARGS: необязательные search (вхождение в name, без учёта регистра), limit (1–100, по умолчанию 20), cursor (из pagination.next_cursor), order (asc|desc по updated_at). RETURNS: { data[] из { id, name, description, schema_id, version, materialized_version, materialized_at, field_count, node_count, created_at, updated_at, links }, pagination { total, limit, has_more, next_cursor } }.

Читает одну страницу замороженного входного пакета взятой в работу задачи на решение: записи, из которых нужно принять решение, вместе с локаторами их происхождения. Читать может только текущий заявитель; каждая прочитанная страница попадает в журнал запуска. КОГДА ИСПОЛЬЗОВАТЬ: после успешного взятия задачи, перебирая страницы от package.first_cursor, пока pagination.has_more равно true. Первая страница также несёт список исходных документов. Пакет mining_round - это одна запись { system_prompt, first_turn, tools }. НЕ ДЛЯ: задач без заявителя (HTTP 409; сначала возьмите задачу) или перечисления задач (talonic_list_decision_tasks). АРГУМЕНТЫ: task_id, необязательные cursor и limit (от 1 до 2000). Копируйте локаторы доказательств дословно из этих записей для отправки. АВТОРИЗАЦИЯ: ключу tlnc_ нужно разрешение 'decide' в рамках приложения; сессии OAuth-коннектора нужен scope apps:decide (согласованный при подключении) и действующая роль в рабочем пространстве senior_member или выше. Ошибка 403 (decide_grant_required, insufficient_scope, insufficient_tier) называет то, чего не хватает - скажите об этом пользователю, не повторяйте попытку.

Возвращает взятую в работу задачу на принятие решения в статус 'available' без её решения; следующее взятие в работу увеличивает эпоху. ИСПОЛЬЗУЙТЕ, КОГДА: вы не можете уложиться в lease или SLA, но другой заявитель сможет её решить. НЕ ДЛЯ: объявления задачи неразрешимой (talonic_fail_decision_task, который создаёт ревью и применяет запасной вариант приложения) или удержания lease (talonic_heartbeat_decision_task). АРГУМЕНТЫ: task_id и execution_epoch. При устаревшей эпохе возвращается HTTP 409. АВТОРИЗАЦИЯ: ключу tlnc_ требуется разрешение 'decide' для конкретного приложения; сессии OAuth-коннектора требуются область apps:decide (согласованная при подключении) и активная роль в рабочем пространстве senior_member или выше. Код 403 (decide_grant_required, insufficient_scope, insufficient_tier) указывает, чего не хватает: сообщите пользователю, не повторяйте попытку.

Получает ссылку для загрузки в браузере, которую пользователь открывает, чтобы добавить файл в своё рабочее пространство. Возвращает ссылку и предварительно выделенный document_id. ИСПОЛЬЗУЙ, КОГДА: пользователь хочет загрузить документ, и вы не можете передать его напрямую - размещённые/песочные клиенты (ChatGPT, Claude.ai) или файлы слишком велики для аргументов вызова инструмента. НЕ ДЛЯ: документа, уже находящегося в рабочем пространстве (используйте его document_id) · файла, уже доступного по публичному URL (используйте file_url в talonic_extract). АРГУМЕНТЫ: имя файла (с расширением). ВОЗВРАЩАЕТ: upload_url, document_id, expires_at. После загрузки пользователя опрашивайте talonic_get_document с этим document_id, пока статус не станет 'completed', затем вызывайте talonic_extract. Если статус становится ocr_failed, extraction_failed или error, прекратите опрос и сообщите об ошибке пользователю.

Запускает Spec, настроенный пайплайн заказчика, по документам, одним вызовом. Два входа: document_ids (документы, уже лежащие в рабочем пространстве; для нового файла сначала talonic_request_upload → опрашивайте talonic_get_document, пока не завершится) ИЛИ file_urls (публичные https-файлы, максимум 20; Talonic сначала их загружает). Расходует кредиты. КОГДА ИСПОЛЬЗОВАТЬ: пользователь хочет «прогнать пайплайн счетов по этим документам», обработать файлы через свой Spec или получить структурированные строки Spec. НЕ ДЛЯ: разового извлечения по произвольной схеме (talonic_extract), проверки прогресса (talonic_get_run) или чтения строк (talonic_get_run_results). АРГУМЕНТЫ: spec_id (talonic_list_specs); ровно одно из document_ids[] (1–500) или file_urls[] (1–20, https); необязательные name, pipeline_mode (new по умолчанию | append - добавить к существующему пайплайну Spec); batch_id и плоский metadata только вместе с file_urls. ВОЗВРАЩАЕТ: RunEnvelope { run_kind ('pipeline'|'run'), run_id, pipeline_id, spec_id, status ('processing'|'completed'|'failed'), raw_status, input_count, documents?, message?, links }. Затем опрашивайте talonic_get_run с pipeline_id, когда run_kind равен 'pipeline', или с run_id, когда он равен 'run', каждые 5–10 с, пока статус не станет completed/failed, после чего talonic_get_run_results.

Сохраняет повторно используемую схему в рабочую область для применения в будущих извлечениях. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь подтверждает схему/шаблон, который хочет повторно использовать в разных документах. НЕ ДЛЯ: однократного извлечения (передайте схему напрямую в talonic_extract). АРГУМЕНТЫ: name; definition — JSON-схема ({type:'object',properties:{...}}) или плоская map {field:'type'}. ВОЗВРАЩАЕТ: сохранённую схему с id и short_id. Передайте любой из них в talonic_extract как schema_id.

Находит документы, поля, схемы или источники в рабочем пространстве. Один вызов возвращает ранжированные результаты по всем типам. ПОИСК ИДЁТ ПО ТОЧНОМУ КЛЮЧЕВОМУ СЛОВУ, а не по смыслу. Запрашивайте ОДНИМ коротким термином в единственном числе или точным именем файла: 'invoice', 'bank statement', 'sample-invoice.pdf'. Предложения ('documents related to invoices') и множественное число ('invoices') возвращают пустой результат. Если поиск ничего не дал, повторите с более коротким ключевым словом в единственном числе, прежде чем делать вывод, что в рабочем пространстве ничего нет. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь называет или описывает документ без идентификатора, или вам нужен document_id или имя фильтруемого поля перед вызовом extract / to_markdown / get_document / filter. НЕ ДЛЯ: структурированных фильтров вида «поле-значение» (например, 'amount > 1000' — для них используйте talonic_filter). АРГУМЕНТЫ: query (короткое точное ключевое слово); опционально limit. ВОЗВРАЩАЕТ: documents[], fields[]/fieldMatches[] (только записи с filterable: true работают в talonic_filter), schemas[], sources[]. Используйте id из documents[], чтобы работать с именованным файлом.

Отправляет заявленные поля вывода для захваченной задачи на этапе Agent и возобновляет приостановленный документ. ИСПОЛЬЗУЙТЕ, КОГДА: обработка завершена и все требуемые выходные данные в output_contract готовы. НЕ ДЛЯ: незаявленные поля или частичное обслуживание аренды (используйте talonic_heartbeat_agent_task). АРГУМЕНТЫ: task_id, execution_epoch, outputs, привязанные точно по ключу заявленного поля, и опциональное summary. Платформа проверяет все поля и типы транзакционно перед записью чего-либо.

Отправляет решение для взятой в работу задачи принятия решения; платформа транзакционно проверяет его и возобновляет выполнение. КОГДА ИСПОЛЬЗОВАТЬ: решение окончательное. outcome должен соответствовать output_contract из claim (обычная JSON Schema или конверт verdict_matrix / record_set), evidence перечисляет локаторы пакетов, на которые вы опирались (дословно; [] только если приложение допускает решения без доказательств), rationale - краткое резюме. Отклонения приходят как HTTP 422 с указанием причины и ничего не меняют; задача остаётся взятой под вашей эпохой, так что исправьте и отправьте заново до истечения аренды. НЕ ДЛЯ: возврата задачи нерешённой (talonic_release_decision_task) или объявления её неразрешимой (talonic_fail_decision_task). Устаревшая эпоха - HTTP 409. АРГУМЕНТЫ: task_id, execution_epoch, outcome, evidence, rationale, необязательные confidence и service_version. АВТОРИЗАЦИЯ: ключу tlnc_ нужно разрешение 'decide' для конкретного приложения; сессии OAuth-коннектора нужен scope apps:decide (согласованный при подключении) и активная роль в рабочем пространстве senior_member или выше. Код 403 (decide_grant_required, insufficient_scope, insufficient_tier) называет, чего не хватает - сообщите пользователю, не повторяйте попытку.

Получает текст документа в Markdown, преобразованный с помощью OCR. ИСПОЛЬЗУЙТЕ, КОГДА: пользователь хочет получить полный текст - 'что здесь написано', краткое содержание или перевод документа. НЕ ДЛЯ: конкретных структурированных полей (используйте talonic_extract со схемой). ПО ИМЕНИ: если пользователь указывает имя файла, сначала вызовите talonic_search, чтобы получить его document_id, затем вызовите этот. АРГУМЕНТЫ: предпочтительнее document_id (документ из рабочего пространства - один дешёвый вызов). В противном случае file_url, или file_data+filename для небольших локальных файлов - укажите ровно один. Ввод файла сначала загружает документ и расходует кредиты; document_id не расходует. ВОЗВРАЩАЕТ: document_id и markdown (полный текст).