Docs
Contents

Business Tool Gateway (AI Gateway / MCP), Client Tools, and Skill Packages

This manual corresponds to Agentbase v2.10.0 (same version as the Console).

To upgrade agents from "knowledge advisors that can look up information and answer questions" to "business agents that can query support tickets, call APIs, and follow standard operating procedures (SOPs) to complete complex tasks", Agentbase Agent Runtime Workbench provides a complete tool and skill extension system: discover and execute authorized business tools through the project's unified AI Gateway (AI Gateway / MCP) binding, let the frontend or host application safely participate in local action execution via the Client Tool pause-and-resume protocol, inject standardized domain operation guides into the model on demand via Skill packages (SKILL.md), and deeply integrate with Agent Observability (Observability / AgentOps) to enable end-to-end Trace tracking and four-dimensional Dataset RAG quality evaluation.


Feature Overview

In enterprise production projects (e.g., 企业智能客服与知识中台, ID: enterprise-ai-hub-210, OceanBase Shared V2 mode), tool invocation and skill governance often face challenges such as blurred security boundaries, interrupted frontend-backend coordination, and difficulty in quantitatively evaluating effectiveness. Agent Runtime builds a secure and controllable action loop through the following four pillars:

  1. AI Gateway and MCP server-side business tool mounting (/v1/agent-runtime/project/gateway):

    • Bind the Agent Runtime workbench with one click to an activated (ACTIVE) unified AI Gateway instance with a published regional snapshot under the same project (e.g., prod-enterprise-ai-gateway, ID: gw_7194685489feb1e169548619).

    • The Runtime automatically discovers from the bound Gateway snapshot the tool definitions permitted for the current invocation context, and strictly validates model-generated parameters against the tool's inputSchema before invocation; tool permissions and external authentication are fully enforced server-side by the Gateway, so the model cannot escalate privileges by forging tool names.

  2. Client Tool 5-step pause, return, and same-Run resume protocol (/runs/{runId}/tool-messages):

    • When the agent needs to perform an action that must be completed locally by the business application or client (such as reading local context, popping up a dialog for the user to confirm an order operation, or calling intranet-restricted components), the model issues a toolCallSource: "CLIENT" tool call, the current Run automatically pauses and enters the WAITING_CLIENT_TOOL state.

    • After the host application completes the local operation, it returns the structured result (if the tool declared outputSchema, the server automatically validates the returned content) or error information via POST /v1/agent-runtime/project/runs/{runId}/tool-messages, and the same Run is immediately re-enqueued (QUEUED → RUNNING) to continue reasoning until a terminal state, with no need to create a second Run.

  3. Project-level Skill package full lifecycle management (/v1/agent-runtime/project/skills):

    • Supports uploading standardized skill packages in .zip, .tar.gz, or .tgz formats (<= 10 MiB), whose root directory contains a SKILL.md with YAML Frontmatter plus auxiliary reference documents; supports list queries (returning skill_count, skill_limit, and skill_catalog_hash), detail retrieval, full-package replacement, and deletion.

    • During ReAct reasoning, the model can autonomously discover and read on demand the operation guidance of relevant Skills as the task requires, avoiding stuffing hundreds or thousands of lines of full business SOPs into system_prompt and consuming the fixed context window.

  4. End-to-end Trace navigation and Dataset RAG four-dimensional quality evaluation loop:

    • Each ASSISTANT message generated by a run carries an associated trace_id, supporting one-click navigation to Agent Observability → Traces to view the ATIF-v1.8-compliant trace and waterfall diagram.

    • In Agent Observability → Datasets, the project Agent Runtime workbench can be selected directly as an evaluation target, running the four RAG metric evaluations — retrieval query quality, context relevance, answer faithfulness, and answer accuracy — with one click, and enabling model-assisted root cause analysis (RCA) to generate actionable optimization suggestions.


Core Concepts and Architecture

Sequence diagram for coordinated execution of server-side tools (MCP), client tools (Client Tool), and Skills

Business Tool Gateway (AI Gateway / MCP), Client Tools, and Skill Packages: workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

Boundary comparison table of the three extension capabilities (Gateway Server Tool / Client Tool / Skill)

DimensionServer-side business tool (Gateway / MCP Tool)Client ToolSkill package
Core purposeInvoked directly by the platform backend to call enterprise internal microservices, database queries, or external MCP Server APIsExecuted locally by the customer's frontend or business host application, with results returned to the same RunProvides the model with on-demand reference of standardized task instructions (SKILL.md), domain specifications, and reference materials
Definition and management locationRegistered, approved, and published as a Gateway snapshot in the same project's AI Gateway (/ai-gateway), bound via PUT /project/gatewayRegistered in the same project's AI Gateway as a CLIENT source tool (including inputSchema and optional outputSchema)Uploaded directly via the Skills panel on the right side of the Agent Runtime workbench or via /v1/agent-runtime/project/skills as an archive
Execution entity and run stateAutomatically executed by the Runtime server-side; the Run stays in the RUNNING state until the tool returnsExecuted by the host application/client; the Run pauses in WAITING_CLIENT_TOOL and resumes upon receiving /tool-messagesExecutes no code or external calls; only read by the model as textual reference material during reasoning
Security and idempotency constraintsServer-side enforcement of inputSchema validation and Gateway authorization policies; parameters in SSE may be masked as {"redacted":true}The application must deduplicate by toolCallId, validate tool names and parameters, and use business idempotency keys for write operations; returns are validated against outputSchemaUploading a Skill does not automatically execute scripts in the package, and does not automatically grant the model any additional tool invocation permissions

Roles, Entry Points, and Relationships

Tool Gateway, Client Tool return, and Skill management API matrix

Functional moduleHTTP method and full pathWhether userId is requiredSuccess status codePrerequisites and permission Scope (uniform requirement: agent-runtime.project)
Query the bound AI GatewayGET /v1/agent-runtime/project/gatewayNot required (project-shared)200 OK (returns 404 when unbound)The project must be in OceanBase Shared V2 mode and have the AI Gateway service enabled
Set / switch AI Gateway bindingPUT /v1/agent-runtime/project/gatewayNot required (project-shared)200 OKThe request body passes {"gateway_id": "..."}; the target Gateway must belong to the current project, be in the ACTIVE state, and have a published regional snapshot
Return client tool execution resultsPOST /v1/agent-runtime/project/runs/{runId}/tool-messagesRequired (JSON body userId)202 AcceptedThe target Run is in the WAITING_CLIENT_TOOL state, and userId, toolCallId strictly match the original call
Upload a new Skill packagePOST /v1/agent-runtime/project/skillsNot required (project-shared)201 Createdmultipart/form-data Upload the file field (.zip/.tar.gz/.tgz, <= 10 MiB), not exceeding skill_limit
List all project SkillsGET /v1/agent-runtime/project/skillsNot required (project-shared)200 OKReturns {items: Skill[], skill_catalog_hash, skill_count, skill_limit}
Query a single Skill's metadataGET /v1/agent-runtime/project/skills/{skillId}Not required (project-shared)200 OKReturns Skill metadata, front_matter, and content_hash (does not directly download the binary archive)
Fully replace an existing SkillPUT /v1/agent-runtime/project/skills/{skillId}Not required (project-shared)200 OKmultipart/form-data Upload a new complete archive file, updating content_hash and updated_at
Delete a specified SkillDELETE /v1/agent-runtime/project/skills/{skillId}Not required (project-shared)204 No ContentRemoves the Skill from the current project workbench

Feature Details and Operation Guide

1. Bind the project AI Gateway and validate tool input/output Schema

1. Prerequisites: confirm the Shared V2 mode and the published Gateway snapshot

  1. Table mode requirement: AI Gateway mounting and client tools require the project to run in OceanBase Shared V2 storage mode (traditional JsonTable projects do not support enabling AI Gateway).

  2. Gateway instance and snapshot ready: In the project's left navigation AI Gateway (/ai-gateway), confirm that the Gateway instance prod-enterprise-ai-gateway (ID: gw_7194685489feb1e169548619) has been created, business tools have been registered and authorized in Tools & Agents (/ai-gateway/tools-agents), and a runtime snapshot available in the current region has been published (see Unified AI Gateway).

2. Bind the AI Gateway to the Agent Runtime workbench (PUT / GET /v1/agent-runtime/project/gateway)

In the Console /console/project-default-enterprise-ai-hub-210/agent-runtime right-side configuration panel, select prod-enterprise-ai-gateway in the Tools Gateway area, or bind via the API:

export APPBASE_ENDPOINT="https://appbuild.oceanbase.com/v1"
export APPBASE_PROJECT_ID="enterprise-ai-hub-210"
export APPBASE_API_KEY="<APPBASE_API_KEY>"

# 1. Bind the project agent workbench to the AI Gateway of a published snapshot (no userId required)
curl -fsSL -X PUT "${APPBASE_ENDPOINT}/agent-runtime/project/gateway" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway_id": "gw_7194685489feb1e169548619"
  }'

Expected successful response (HTTP 200 OK):

{
  "gateway_id": "gw_7194685489feb1e169548619",
  "created_at": "2026-10-22T09:10:00Z"
}
# 2. Query the AI Gateway currently bound to the workbench
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/gateway" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

Note: Each project binds one Gateway at a time; you can switch to another Gateway in the same project by calling PUT /gateway again. If you attempt to bind a Gateway that has not published a snapshot, the API returns HTTP 400. The current project API does not support unbinding by passing an empty string "".

3. Tool inputSchema and outputSchema bidirectional validation mechanism

The tool schema is defined centrally in AI Gateway (there is no need to pass tool definitions in every POST /runs request). Taking an order/support ticket status query tool as an example:


2. Client Tool: Complete Hands-on of the 5-Step Pause, Return, and Resume

When a client tool with toolCallSource: "CLIENT" is configured in the gateway and the model decides to call it during execution, strictly follow the following 5-step standard protocol to complete local execution and result return:

Step 1: Capture the CLIENT tool call request from the SSE event stream

When subscribing to /runs/{runId}/events, you receive the following three types of events in sequence:

  1. TOOL_CALL_START: {"type": "TOOL_CALL_START", "toolCallId": "call_cli_9001", "toolCallName": "query_order_status", "toolCallSource": "CLIENT"} — the application creates a local pending record keyed by the unique toolCallId;

  2. TOOL_CALL_ARGS: concatenate delta string fragments according to toolCallId;

  3. TOOL_CALL_END: parameter transmission is complete; parse the concatenated JSON to obtain {"order_id": "ORD-1003"}.

Step 2: Confirm the Run has entered the WAITING_CLIENT_TOOL state and verify the persisted call

Query GET /v1/agent-runtime/project/runs/{runId}?userId=user_zhangwei_001 to confirm the state has changed to "status": "WAITING_CLIENT_TOOL". If you need the tool's complete output_schema metadata, read the payload of message_type === "TOOL_CALL" in GET /runs/{runId}/messages (containing call_id, tool_name, arguments, source: "CLIENT", and optional output_schema).

Step 3: Safely execute the local action in the host application

Before executing locally, the application must validate toolCallName and parameter legitimacy; never blindly execute arbitrary unauthorized commands. If the tool involves external write side effects such as creating orders or charging payments, be sure to use toolCallId as the business idempotency key to prevent duplicate execution during SSE disconnect replays.

Step 4: Call POST /runs/{runId}/tool-messages to return the execution result

Serialize the local execution result into a JSON string and put it in the content field (note: content must be of type string; do not pass an unserialized JSON Object directly):

ToolMessage FieldTypeRequiredSpecification and Constraint Description
userIdstringRequiredMust exactly match the business user userId that created the Run (e.g., "user_zhangwei_001").
idstringRequiredA unique tool message ID generated by the client (e.g., "tmsg_ord1003_001"); when retrying the same return due to network timeout, the same id must be reused.
rolestringRequiredFixed as "tool".
toolCallIdstringRequiredMust strictly match the toolCallId (e.g., "call_cli_9001") in the server-side TOOL_CALL_START / TOOL_CALL message.
contentstringRequiredThe JSON-serialized string of the successful result (e.g., "{\"order_id\":\"ORD-1003\",\"status\":\"shipped\"}"); pass "{}" on failure.
errorstringOptionalWhen the client tool execution fails, pass a readable error reason description (e.g., "订单系统内网连接超时").

Example of returning a successful result curl:

curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/tool-messages" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_zhangwei_001",
    "id": "tmsg_ord1003_001",
    "role": "tool",
    "toolCallId": "call_cli_9001",
    "content": "{\"order_id\":\"ORD-1003\",\"status\":\"shipped\"}"
  }'

Example of returning a tool execution failure curl:

curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/runs/run_01j8x9p1q2r3s4t5u6v7w8x9y0/tool-messages" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_zhangwei_001",
    "id": "tmsg_ord1003_001",
    "role": "tool",
    "toolCallId": "call_cli_9001",
    "content": "{}",
    "error": "订单子系统暂不可用,请稍后重试"
  }'

Step 5: Resume observing the same Run until SUCCEEDED

After the return API is successfully accepted, it responds with HTTP 202 Accepted:

{
  "run_id": "run_01j8x9p1q2r3s4t5u6v7w8x9y0",
  "status": "QUEUED",
  "created_at": "2026-10-22T09:20:00Z"
}

Note: Returning a tool result does not create a new run_id; instead, the original run_id re-enters QUEUED → RUNNING from WAITING_CLIENT_TOOL, and after the model reads the tool result it generates the final answer and pushes RUN_FINISHED.


3. Skill Package Creation, Upload, and Full Lifecycle Management (/v1/agent-runtime/project/skills)

When an enterprise has multiple sets of standard operating procedures for niche scenarios (e.g., "OceanBase Lock Conflict Troubleshooting Skill", "VIP Support Ticket Escalation Verification Skill"), they can be packaged as Skill packages and uploaded to the Agent Workbench.

1. Create a Compliant Skill Archive (SKILL.md Specification)

  1. Archive format and size limits: Only .zip, .tar.gz, or .tgz formats are supported; a single archive must be at most <= 10 MiB, and the archive must not contain path traversal (..) or illegal symbolic links.

  2. Root directory SKILL.md and YAML Frontmatter specification: The archive root directory must contain a SKILL.md file, and the beginning of the file must include the following YAML Frontmatter metadata:

    • name: Required, length of 1~64 characters; only lowercase English letters, digits, or a single hyphen - are allowed (regex: ^[a-z0-9]+(-[a-z0-9]+)*$; uppercase letters, underscores, or consecutive hyphens -- are forbidden);

    • description: Required, length of 1~1024 characters; briefly describes the applicable scenario of the skill (the model decides when to read the full skill text on demand based on this description).

Standard SKILL.md example:

---
name: ob-troubleshooting-sop
description: 处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。
---

# OceanBase 核心故障标准排障流程

1. **确认故障码与版本**:首先确认用户报错码是 `-4013`(向量内存不足)还是 `-4024`(行锁等待超时),并核实集群是否为 OceanBase 4.3 Shared V2 模式。
2. **检索权威分块**:调用 `knowledge_retrieve` 检索 `kb_enterprise_support` 知识库中的《OceanBase分布式事务与向量索引排障指南.md》。
3. **输出结构化结论**:按「根因定位 → 诊断 SQL/视图 → 参数调整建议 → 风险提示」四段式输出,并保留知识库文档出处。

Package it locally into ob-troubleshooting-sop.zip:

zip -r ob-troubleshooting-sop.zip SKILL.md

2. Upload, List, Query, Replace, and Delete Skills (Console and curl Hands-on)

# 1. Upload a new Skill package (POST /v1/agent-runtime/project/skills)
# Note: using --form 'file=@...' automatically generates the multipart/form-data boundary; do not hand-write the Content-Type boundary
curl -fsSL -X POST "${APPBASE_ENDPOINT}/agent-runtime/project/skills" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  --form 'file=@./ob-troubleshooting-sop.zip'

Expected response (HTTP 201 Created):

{
  "skill_id": "skl_01j8xa1b2c3d4e5f6g7h8j9k0m",
  "name": "ob-troubleshooting-sop",
  "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。",
  "front_matter": {
    "name": "ob-troubleshooting-sop",
    "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。"
  },
  "content_hash": "sha256_8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d",
  "created_by": "user_admin_001",
  "created_at": "2026-10-22T09:25:00Z",
  "updated_at": "2026-10-22T09:25:00Z"
}
# 2. List all uploaded Skills and capacity quota for the current project (GET /v1/agent-runtime/project/skills)
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/skills" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

Expected response (HTTP 200 OK):

{
  "items": [
    {
      "skill_id": "skl_01j8xa1b2c3d4e5f6g7h8j9k0m",
      "name": "ob-troubleshooting-sop",
      "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。",
      "front_matter": {
        "name": "ob-troubleshooting-sop",
        "description": "处理 OceanBase 分布式事务锁冲突(4024)与向量索引内存不足(4013)的标准排障作业流程。"
      },
      "content_hash": "sha256_8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d",
      "created_by": "user_admin_001",
      "created_at": "2026-10-22T09:25:00Z",
      "updated_at": "2026-10-22T09:25:00Z"
    }
  ],
  "skill_catalog_hash": "cat_7f6e5d4c3b2a1908",
  "skill_count": 1,
  "skill_limit": 10
}

Quota judgment guideline: The application should dynamically read skill_count and skill_limit in the response to determine the remaining uploadable slots; never hardcode a fixed limit in business code.

# 3. Query a single Skill's metadata (GET /v1/agent-runtime/project/skills/{skillId})
curl -fsSL -X GET "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

# 4. Replace an existing Skill with a new version archive (PUT /v1/agent-runtime/project/skills/{skillId})
curl -fsSL -X PUT "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}" \
  --form 'file=@./ob-troubleshooting-sop-v2.zip'

# 5. Delete an unused Skill (DELETE /v1/agent-runtime/project/skills/{skillId} -> 204 No Content)
curl -i -X DELETE "${APPBASE_ENDPOINT}/agent-runtime/project/skills/skl_01j8xa1b2c3d4e5f6g7h8j9k0m" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  -H "X-Appwrite-Key: ${APPBASE_API_KEY}"

4. Linked Agent Operations (Observability): Trace Drill-down and Dataset RAG Four-Dimension Evaluation

1. One-Click Jump from Workbench Conversation to the Trace Waterfall

When agentops.runtimeExportEnabled is enabled on the platform, every Run in the Agent Workbench is automatically reported as an OpenTelemetry trace tagged with capability:agent and organized into the ATIF-v1.8 standard format.

2. Perform RAG Four-Dimension Quality Evaluation and Root Cause Analysis on the Agent Workbench in Datasets

The Agent Workbench has no isolated popup evaluation button; instead, it deeply reuses the unified evaluation pipeline of Agent Operations → Datasets (/observability/datasets) (see Evaluation Dataset Management and Evaluation, Scoring, and Index Quality Assessment):

  1. Start a dataset evaluation run:

    • Go to Agent Operations → Datasets, select the golden evaluation set (e.g., enterprise-support-golden-v1) → switch to the Runs tab → click Create run;

    • Step One (Select evaluation target): Select the Agent Workbench and the current run configuration;

    • Step Two (Select RAG evaluators): Check all four core RAG metrics at once from the built-in evaluator library (keep an independent variable mapping for each metric, and use the project's default Judge LLM evaluation model).

  2. Table of the Four RAG Evaluation Metrics and Evidence Judgment Criteria:

Evaluation Metric NameReal-Run Evidence Compared for ScoringQuality Measurement DimensionKey Prerequisites and Boundary Notes
Retrieval Query QualityThe user's original question in this round vs the knowledge_retrieve retrieval Query actually issued by the agentEvaluates whether the retrieval terms rewritten or generated by the evaluation model faithfully preserve user intent and key qualifiers (e.g., error code 4013)Requires that this Run actually saved trusted RAG retrieval evidence consistent with the sample identity
Context RelevanceUser question vs the set of retrieved chunks actually fed into the final answer step (including image understanding descriptions and source localization)Evaluates how relevant the document chunks retrieved from the knowledge base are to the user's questionMultiple retrieval steps are merged in the order of the final model messages; if evidence is missing or truncated by compressed summaries, it is marked as "insufficient evidence" rather than forcibly scored with empty context
Answer FaithfulnessThe agent's final answer vs the retrieved chunks actually sent to the modelEvaluates whether the factual claims in the answer are well-grounded and whether there are hallucinations detached from the retrieval evidenceStrictly compares the retrieval chunks frozen for the current run; it does not re-query the current knowledge base to supply evidence for historical runs
Answer AccuracyThe agent's final answer vs the frozen standard answer (expectedOutput) in the dataset sampleEvaluates whether the final answer is correct and completely covers the core points of the standard answerA sample standard answer (expectedOutput) must be provided; even if answer faithfulness is high, if key troubleshooting steps are omitted, answer accuracy can still keenly identify the low score
  1. View model-assisted Root Cause Analysis (RCA) and optimization suggestions: After the evaluation completes, open the Score Details of low-scoring samples. When the project's "use model for root cause analysis" is enabled, the system automatically compares "user question → retrieval Query → retrieved chunks → final answer → frozen standard answer" to pinpoint whether the issue is retrieval rewrite deviation, insufficient knowledge base chunk relevance, or model summarization omission, and provides actionable tuning suggestions based on the currently active configuration parameters (the administrator confirms and independently decides whether to modify the Workbench configuration; the system will not automatically tamper with the online configuration without authorization).


FAQ and Troubleshooting

Q1: Why does calling PUT /v1/agent-runtime/project/gateway to bind a gateway return HTTP 400 or 412?

Cause and troubleshooting steps:

  1. Check the project table schema and service toggles: Binding the AI Gateway requires the project to use the OceanBase Shared V2 table schema, and the AI Gateway service must already be enabled in Settings → Overview → Services.

  2. Check the gateway status and region snapshot: The target gateway_id (e.g., gw_7194685489feb1e169548619) must belong to the current project, be in the ACTIVE state, and have successfully published at least one available snapshot in the AI Gateway Console (binding an empty gateway that has never published a snapshot stably returns 400).

Q2: Why does returning client tool results to /runs/{runId}/tool-messages return 400 INVALID_REQUEST?

Cause and troubleshooting steps: The two most common causes are as follows:

  1. The content field is not serialized as a string: ToolMessage.content must be a JSON-serialized string (e.g., "{\"status\":\"shipped\"}"); if a JSON object is passed directly, {"status": "shipped"} will be rejected due to a type mismatch.

  2. Violation of the tool's declared outputSchema: If the client tool defines an outputSchema in AI Gateway (e.g., requiring the mandatory order_id and enum value status), but the returned content JSON is missing required fields or contains extra fields forbidden by additionalProperties: false, the server-side Schema validator will directly reject the return.

Q3: Uploading a Skill archive fails with an error — how to quickly determine whether it is a format problem or a metadata problem?

Cause and troubleshooting steps: Please check the archive item by item against the following checklist:

  1. Archive structure: After extraction, SKILL.md must be located directly at the archive root directory (i.e., unzip -l your-skill.zip should show a top-level SKILL.md, not nested one level under a my-folder/SKILL.md subdirectory);

  2. YAML Frontmatter format: the SKILL.md file must begin with --- wrapping name and description; name may only contain 1~64 lowercase letters, digits, and single hyphens (e.g. customer-support-v1); uppercase letters, spaces, underscores _, or consecutive hyphens -- are not allowed;

  3. Size and quantity quota: the archive size must not exceed 10 MiB, and the skill_count already uploaded in the current project must not have reached the skill_limit returned by GET /skills.