mem9-ai/agent-stack-dev-guide/agent-stack-dev-guide

TiDB Link Developer

Help developers build on TiDB Link through the TiDB Link Customer API (every customer route is under /api/v1). Call the bundled contract OpenAPI. Keep wire names exact; some error descriptions still use the older name Agent Service.

Route the request

For requests in Chinese, prefer the corresponding Simplified Chinese guide under references/zh-CN/: architecture, development path, reliability, Connectors, Realtime voice, and upstream compatibility. Keep this single Skill entry point. All languages share references/openapi.yaml as the contract and references/api-reference.html as the English API reference; preserve wire names and verify operations against that YAML. Translation provenance and sync rules are in references/zh-CN/TRANSLATION.md.

Classify the request before loading detail:

• For a vague request such as “integrate TiDB Link”, ask one question: which stage of the development path (setup, define the Agent, provision users, connect devices, text conversation, voice conversation) or troubleshooting.
• To explain how the pieces fit — credentials, Template → Session, text vs. voice, devices — read references/architecture.md.
• To build or extend an integration, read references/development-path.md and follow its stages in order. Start at the earliest stage whose “done when” check the developer has not passed.
• For idempotency keys, clientEventId, ETags, SSE reconnection, receipts, pagination, retries, errors or diagnosis, read references/reliability.md.
• When implementing a device server, read references/protocols/connectors.md. When implementing a voice client, read references/protocols/realtime-voice.md.
• For exact operations, parameters, security, schemas, status codes or error codes, search references/openapi.yaml before answering.
• When the developer wants browsable documentation, return a clickable absolute path to references/api-reference.html. The HTML is for humans; reason from the YAML.

Load only the references the request reaches. The route is complete when every requested branch has a specific step or an explicit Console handoff.

Stay within the guide's scope

The development path is the supported way to build. The contract also contains operations this guide does not cover — platform Hardware (Hardware Models, inventory, Registrations, Bindings, /api/v1/hardware/connect), Client Tools, MCP Server registrations, Scheduler, Drive files, Billing. Connect hardware through the developer's own device server registered as a Connector, not through platform Hardware routes. When a developer asks for an uncovered capability, say it is outside this guide, then answer only from the operation's contract without presenting it as the recommended path.

Before Stage 3, confirm a Console account can edit Templates in the same Organization. MSP provisioning does not create that membership. The Organization Template API rejects content.tools; never propose tools.mcp in an Org API body. Prefer streamable_http on multi-replica deployments; tunnel readiness is replica-local.

Treat the contract as evidence

The bundled contract is pinned to the revision in references/upstream.md; a deployment can lag behind it. For each operation, verify its method, path, operation-level security, headers, request schema, success response and documented errors. Operation-level security controls that operation; authorization is also described in the operation's description. When two parts of the contract disagree, state the conflict and follow the operation-specific definition. When an operation lists a status without a description or error code, call out the gap instead of inventing meaning.

Know the credentials

The persisted credential determines Organization and End User scope. No header, path or body field selects another Organization or acting user.

Wrong-family credentials return 403; missing, revoked or rotated keys return 401.

Use raw HTTP

Default to a runnable curl request. When the developer asks for a language or an existing codebase change, use that project's existing HTTP, SSE and WebSocket clients, and the official MCP SDK for a device server. Use no TiDB Link SDK.

Standardize these inputs:

• TIDB_LINK_BASE_URL: service root; remove a trailing slash before joining a path.
• TIDB_LINK_ORG_KEY: Organization API Key, backend only.
• TIDB_LINK_USER_KEY: the User API Key of the End User being served, backend only.

Represent userId, agentId, sessionId, ETags, cursors, Idempotency-Key and clientEventId values as runtime values, not environment variables. The application stores your user → userId, each End User's key, and sessionId → your user (needed by the device server).

Protect authority

Reference secrets through environment variables or the developer's secret manager. Keep plaintext secrets out of conversation output, generated code, logs, files and URLs. Secrets returned once — User API Keys (token), connectorKey, connectToken — go straight to protected storage or the intended client; a lost secret requires rotation, not a retry.

Keep the Organization API Key and User API Keys on the backend. Browsers and devices receive only short-lived grants.

Before executing a live write, key issuance or rotation, Connector registration, activation or credential change, or deletion, require an explicit request for that side effect. Treat Console-only work — issuing the Organization API Key, referencing a Connector from a Template, Template Playground — as a Console handoff: give numbered human steps instead of requesting a cookie or generating cookie-authenticated curl.

Shape the answer

Follow the developer's language. Name the stage and step number from the development path. For an HTTP call, include the exact method, path, credential, required headers, body, the success signal, and the documented error that most directly affects the next step. Finish according to the stage's “done when” check. Never claim a live integration succeeded without an observed service response.