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)

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}\ \ ). Key event types:

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

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