@opsregistry/adapter-yandex-ai

Independent server-side adapter for it.aiResponse.create, implemented with the OpenAI SDK against https://ai.api.cloud.yandex.net/v1. No dependency on VARM or any database.

Configuration: apiKey, folderId, model, instructions, mcp: {url, label, headers}. Supply credentials from the consuming server's secret store, never frontend input. headers carries the current user's MCP authorization; do not replace it with a shared administrative token.

createAdapter(config).createResponse({message, previousResponseId?}) returns normalized text, response ID, status, pending approvals, tool-call summaries and token usage. Continue approvals with {previousResponseId, approvals:[{requestId,approve}]}. Store and verify ownership of IDs in the application; possession of a provider response ID is not authorization.

The adapter sends defer_loading: true, store: true, previous_response_id, fresh instructions and MCP headers on every turn. Before each model request it discovers tools over Streamable HTTP with that same user's MCP headers (10-second discovery deadline). It derives never.tool_names only from readOnlyHint: true metadata without a contradictory destructiveHint: true; no handwritten tool list. Yandex currently asks for approval even with the read_only filter, so explicit names are needed. Unknown/unannotated/write tools still require approval; no read tools means require_approval: always. Discovery failure stops before calling the model, and lists are never cached across users. Read-only tools bypass approval; all other tools require approval. Never accept approval decisions from the model. Defaults: 600 output tokens, 3 tool calls. Optional limits, previousContextTokens, and awaited beforeRequest(plan) support consumer budget reservations before model execution. The plan uses a conservative UTF-8/context/output bound; the consumer must enforce the advertised MCP output bound and reconcile provider usage. It is not an invoice guarantee. Usage preserves cached/tool/reasoning/total counters when supplied. Non-streaming requests have a 90-second timeout, zero SDK retries, no background execution and no parallel tool calls. A transport error does not prove that no tool executed. Error bodies and full provider responses are not returned to the consumer.

store: true means conversation context is retained by the provider. The consuming application must define its own access and retention policies. Changing user permissions should invalidate continued context that may contain data no longer accessible to the user.

Agent handoff

Implemented: text turns, previous-response chaining, dynamic MCP headers, deferred discovery, normalized approval requests/decisions, safe error projection. Validation: bun test, bun run check. Fixtures verify request/response mapping, not remote feature support or a live business mutation.

Next: streaming/cancellation and explicit response deletion/retention operations; provider usage budgets; additional model/provider compatibility tests. Do not add ERP logic, employee identity, database tables, or application URLs here. Never enable automatic retries for tool-bearing requests.

Sources:

• https://aistudio.yandex.ru/en/docs/ai-studio/api/Responses/createResponse
• https://yandex.cloud/ru/blog/mcp-yandex-ai-studio-ai-agents-automation