TencentDB DatabaseClaw Skill

This skill should be used when an AI agent or automated system needs to send messages to a TencentDB DatabaseClaw instance and receive streaming responses. It provides a verified Python client (scripts/chat.py) and complete TC3-HMAC-SHA256 signing reference for the CreateChatCompletion SSE API. Trigger on keywords: DatabaseClaw, DBClaw, clawins-, TDAI chat, agent-to-agent database query.

TencentDB-DatabaseClaw

Send messages to a DatabaseClaw instance via the CreateChatCompletion SSE API and receive streaming Agent responses.

When to Use

• An AI agent needs to invoke DatabaseClaw for SQL execution, inspection, or data analysis
• Building an AI workflow that integrates DatabaseClaw as a tool (LangChain / CrewAI / custom)
• Verifying a DatabaseClaw instance is healthy by sending a test message
• Cross-product function-calling where DBClaw acts as a backend tool

Not for: instance lifecycle management (isolate/restart/offline) — user must operate in the DatabaseClaw Console.

API Scope: This skill ONLY uses CreateChatCompletion (SSE chat) and CreateClawSession (create session for console visibility). No other APIs are supported.

---

Critical Facts (Must-Know Before Starting)

Fact	Value
SSE streaming host	tdai.ai.tencentcloudapi.com
Non-streaming host (list/describe)	tdai.tencentcloudapi.com
Service name (for TC3 signing)	tdai
API version	2025-07-17
Action (chat)	CreateChatCompletion
Action (session)	CreateClawSession (non-streaming host)
Required body fields	InstanceId, InputContent
Optional body fields	ChatId (pass SessionKey here to link with console session list)
Forbidden body fields	AppId, Uin, OwnerUin, IdempotencyKey (identity derived from AK/SK)
Instance requirement	Status must be running
SSE end marker	data: [DONE]
Response wrapper	Frames may be wrapped in {"Response": {...}} — unwrap before parsing
Heartbeat interval	20 seconds (ignore these frames)
Recommended timeout	120s (covers 99% cases); complex multi-region scans may take 60-90s
Timeout guidance	Simple Q&A: 2-5s; single query: 5-15s; multi-region scan: 30-90s

Domain split is the #1 pitfall: CreateChatCompletion MUST hit tdai.ai.tencentcloudapi.com. Using tdai.tencentcloudapi.com returns InternalError.

---

Workflow

Step 0: Ensure Instance is Running

Before using this skill, the target DatabaseClaw instance must be in running status. If the instance is not running (API returns an error like "实例状态异常"), guide the user to:

1. Open the DatabaseClaw Console
2. Locate the target instance and ensure it is in "运行中" status
3. If the instance is stopped/isolated, click "重启" or "解除隔离" in the console

Important: This skill only uses the CreateChatCompletion API (and optionally CreateClawSession). Instance lifecycle operations (restart/isolate/offline) are NOT supported via this skill — the user must operate them in the console.

Step 1: Session Creation (Default Behavior)

By default, chat.py automatically calls CreateClawSession (on tdai.tencentcloudapi.com) to get a SessionKey before sending the message. This makes the conversation visible in the console's session list page (会话列表).

# Default: session is created automatically
python3 scripts/chat.py --instance-id $INSTANCE_ID --secret-id $SECRET_ID --secret-key $SECRET_KEY \
  --message "hello"

To skip session creation (conversation won't appear in console list):

python3 scripts/chat.py --instance-id $INSTANCE_ID --secret-id $SECRET_ID --secret-key $SECRET_KEY \
  --no-session --message "hello"

Step 2: Send Message (Programmatic)

Use scripts/chat.py — two output modes:

• Default (clean): Only final Agent response on stdout. Ideal for piping into other tools or Agent integrations.
• --verbose / -v: Shows tool calls, reasoning, and connection info on stderr. Ideal for debugging and development.

# Clean mode (default) — only final answer on stdout
python3 scripts/chat.py \
  --instance-id $INSTANCE_ID \
  --secret-id $SECRET_ID \
  --secret-key $SECRET_KEY \
  --message "查询近7天慢查询 TOP 10"

Omit --message for interactive multi-turn mode.

Verbose mode (show tool calls and intermediate steps on stderr):

python3 scripts/chat.py -v \
  --instance-id $INSTANCE_ID \
  --secret-id $SECRET_ID --secret-key $SECRET_KEY \
  --message "查询ap-shanghai的MySQL实例"

For internal dev gateway (no signing needed):

python3 scripts/chat.py \
  --internal \
  --instance-id $INSTANCE_ID \
  --message "SELECT 1"

Step 3: Parse SSE Stream

The response is a standard SSE stream (data: {json}\n\n). Key event types:

Event Object	Meaning	Action
(first frame, has ChatId)	Connection established	Store ChatId for multi-turn
claw.tool_call	Agent calling a tool	Display progress (optional)
claw.tool_result	Tool execution complete	Display result (optional)
claw.partial / chat.chunk	Text chunk	Append to output buffer
claw.final / FinishReason=stop	Stream complete	Close connection
heartbeat	Keep-alive (every 20s)	Ignore
"Error" key in Response	API error	Log and abort
data: [DONE]	Hard stream end	Close connection

Concatenate all Delta.Content values to form the complete Agent response.

Step 4: Integrate into Agent Framework

For Python integration with proper TC3 signing, see references/python-integration.md. The reference includes:

• Verified tc3_sign() function
• HTTP headers format
• SSE stream parsing example
• Error diagnosis table

---

Error Handling

Error	Cause	Fix
InternalError	Wrong host (used tdai.tencentcloudapi.com)	Switch to tdai.ai.tencentcloudapi.com
UnknownParameter	Body contains AppId/Uin/OwnerUin	Remove them; identity is from AK/SK
MissingParameter (InputContent)	Missing required field	Add InputContent to body
AuthFailure.SignatureExpire	Timestamp drift	Use int(time.time()), never datetime.utcnow()
InvalidAuthorization	Wrong credential_scope	Must be YYYY-MM-DD/tdai/tc3_request
Instance error in SSE	Instance not running	Go to DatabaseClaw Console and ensure instance is in "运行中" status
Connection timeout	Instance stuck	Restart instance via console, retry

---

TC3 Signing Checklist

When implementing TC3 signing manually (not using scripts/chat.py):

1. Timestamp: int(time.time()) — never datetime.utcnow() (macOS timezone drift)
2. SignedHeaders must include: content-type;host;x-tc-timestamp (alphabetical)
3. credential_scope: {date}/tdai/tc3_request (service name = tdai)
4. Host in canonical_headers: tdai.ai.tencentcloudapi.com (the SSE host)
5. HTTP headers must include: X-TC-Action, X-TC-Version, X-TC-Region, X-TC-Timestamp, Authorization
6. Accept header: text/event-stream

Full signing implementation: references/python-integration.md

---

Files

Path	Purpose
scripts/chat.py	Standalone CLI client — single message or interactive mode, zero external deps beyond stdlib
references/python-integration.md	Complete TC3 signing code, HTTP headers, SSE parsing, error diagnosis