Agent (plugin) development rules

Xiaoya supports standard MCP agents and OAuth-backed web agents. Both run on developer-owned infrastructure; these documentation pages are statically generated at build time and add no production service.

Choose an integration

Need	Integration	Required implementation
Let Xiaoya AI discover and invoke tools	MCP agent	Manifest, initialize, tools/list, tools/call
Independent pages, forms, orders, or durable business state	Web agent	OAuth callback, server session, Open API calls
Both	Hybrid	Keep both trust boundaries and never double-charge one action

Manifest and review

Register a stable application ID and version, display metadata, exact production entry URL, and MCP URL. Production endpoints must use public HTTPS. Callback URLs require exact matching; wildcards and open redirects are forbidden.

Removing a tool, changing input meaning, expanding permissions, increasing price, or changing sync to async requires a fresh tool review.

MCP sequence

Xiaoya uses JSON-RPC 2.0 and calls initialize, notifications/initialized, tools/list, then tools/call. Notifications have no id and receive no response.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "xiaoya-open-platform", "version": "1.0.0" }
  }
}

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

A Streamable HTTP endpoint accepts application/json and text/event-stream, maintains Mcp-Session-Id, limits body sizes, concurrency, and execution time, and rejects unexpected redirects.

Tool definition

Every tool needs inputSchema, outputSchema, standard annotations, and complete xiaoya/* metadata:

{
  "name": "generate_product_brief",
  "title": "Generate product brief",
  "description": "Generate a structured marketing brief",
  "inputSchema": {
    "type": "object",
    "required": ["productName"],
    "properties": {
      "productName": { "type": "string", "minLength": 1, "maxLength": 120 }
    },
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "required": ["status", "summary", "data", "artifacts"],
    "properties": {
      "status": { "type": "string", "enum": ["accepted", "completed", "failed", "cancelled"] },
      "summary": { "type": "string" },
      "data": { "type": "object" },
      "artifacts": { "type": "array", "items": { "type": "object" } }
    },
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  },
  "_meta": {
    "xiaoya/version": "1.0.0",
    "xiaoya/pricePoints": 20,
    "xiaoya/requiredScopes": [],
    "xiaoya/executionMode": "async",
    "xiaoya/artifactTypes": ["markdown"],
    "xiaoya/timeoutSeconds": 600
  }
}

Constrain required values, lengths, ranges, array items, and additionalProperties. Identity, tokens, invocation IDs, callbacks, Team context, and billing values must never be AI-supplied business arguments. Free tools still declare xiaoya/pricePoints: 0; execution mode is sync or async; timeout is 1–3600 seconds. Artifact types are text, markdown, html, image, audio, video, file, json, table, or link.

Call and result

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "generate_product_brief",
    "arguments": { "productName": "Xiaoya Claw" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "The brief is ready" }],
    "structuredContent": {
      "status": "completed",
      "summary": "The brief is ready",
      "data": { "briefId": "brief_01" },
      "artifacts": [{
        "type": "markdown",
        "title": "Marketing brief",
        "url": "https://agent.example.com/artifacts/immutable-id",
        "mimeType": "text/markdown",
        "size": 1024,
        "sha256": "<hex-digest>"
      }]
    }
  }
}

Artifact URLs must be short-lived, unguessable, read-only, and scoped to one artifact. Do not return local paths, internal URLs, or large inline files.

Context, callbacks, and billing

The platform supplies protected call-context headers. Verify signature, freshness, target agent, and invocation, optionally through POST /api/v1/open-agent-tools/call-context/introspect. Never forward security headers to a model, browser, or logs, and never share a platform JWT secret.

An async tool immediately returns status: "accepted" and a stable task ID. Submit the final envelope for the same invocation to POST /api/v1/open-agent-tools/callbacks/{invocation_id} with platform-issued callback credentials. Retries keep the same invocation and idempotency identity; never ask the AI to run the job again.

One business action uses exactly one billing path: reviewed MCP xiaoya/pricePoints for platform-managed confirmation, charge, and refund; or /api/v1/open/charge for a separately confirmed web-agent purchase. Never use both. Prices, order IDs, and idempotency keys come from a trusted server; /balance is display-only and does not replace the atomic /charge result.

Errors, security, and release

• Use JSON-RPC -32700, -32600, -32601, and -32602 for parse, invalid request, unknown method/tool, and invalid params errors. Business failures use status: "failed" with a stable data.errorCode.
• Set explicit timeouts on external HTTP, retry only idempotent operations, and never hold a database transaction across an upstream call.
• Enforce invocation, order, and callback idempotency with database constraints and transactions. Memory or JSON-file stores are development-only.
• Never log authorization, OAuth codes, call-security headers, raw PII, full prompts, or provider credentials.
• Before release, validate the Manifest, schemas, prices, scopes, execution modes, and artifacts; refresh and review the tool snapshot. Contract changes require another review.

See the complete API reference for every public operation, parameter, request body, and response schema. Download templates, validators, and offline API guidance from the Xiaoya Open Agent Developer Skill.