Tools

Tooling

UAIX tools support validation, inspection, field-order governance, transport and trust review, fixture testing, machine-readable discovery, and implementation onboarding for UAI-1.

What tools should help with

Resolve the current public record without scraping page text.
Inspect schema targets, profile IDs, field order, fixtures, transport bindings, trust channels, error codes, and conformance expectations before release.
Surface structural drift, async workflow mistakes, trace-context problems, and trust-policy gaps before downstream users depend on them.
Export conformance outcomes as reviewable records that can travel into release notes, CI logs, or audit evidence.

Primary tooling path

Most readers should start with the Validator, then move back to Examples or forward into Implementations depending on whether the next need is debugging or release evidence.

Hello-world conformance path

Choose one published Example or prepare one candidate message tied to a known public profile.
Resolve the matching schema, registry, field-order, transport, trust, and error records before running the check so another reviewer can reproduce the same packet.
Run the Validator and export the result as a reviewable record.
Carry that result into Implementations, the Changelog, News, and References and Contributors when the check supports a public release or support claim.
Repeat the run whenever schemas, registry mappings, field order, transport guidance, error codes, validator behavior, or runtime mappings change.

Published starter path

Use the public proof run and client calls below when the next task is onboarding a tool, script, or QA flow to the live public surface without private helpers.

Step 1

Resolve the live catalog

Pull the current route inventory first so the rest of the proof run stays anchored to the published machine surface.

Step 2

Fetch one starter example

Use one published request example as the first packet so your review starts from current public structure instead of local guesswork.

Step 3

Wrap the message for validation

Build one validator request body with the example packet nested under `message` and request the result record format.

Step 4

Run one validator check

Submit the validation request to the live POST route and keep the returned result record with the exact packet that was checked.

Step 5

Test the live reference response

Post the same validated packet to the mock exchange route when you want one real conforming response shape before a runtime track exists.

Step 6

Carry only the named next step

Move from proof into the named implementation lane, conformance pack, and release trail instead of claiming broader support than the site publishes.

Catalog /wp-json/uaix/v1/catalog Schema /wp-json/uaix/v1/schemas/uai.intent.request.v1 Example /wp-json/uaix/v1/examples/uai.intent.request.v1 Validate /wp-json/uaix/v1/validate Adoption kit /wp-json/uaix/v1/adoption-kit Mock exchange /wp-json/uaix/v1/mock-exchange

起步消息 Example packet JSON starter-message.json

{
    "uai_version": "1.0",
    "profile": "uai.intent.request.v1",
    "message_id": "msg-2026-04-22-0001",
    "source": {
        "type": "agent",
        "id": "agent.alpha",
        "label": "Agent Alpha",
        "uri": "https://agents.alpha.example/runtime",
        "did": "did:web:agents.alpha.example",
        "role": "requesting-agent",
        "implementation": "alpha-runtime-2.4.1"
    },
    "target": {
        "type": "service",
        "id": "uaix.gateway",
        "label": "UAIX Gateway",
        "uri": "https://uaix.org/wp-json/uaix/v1/discovery",
        "did": "did:web:uaix.org",
        "role": "public-record-gateway",
        "implementation": "uaix-core-0.4.0"
    },
    "conversation": {
        "conversation_id": "conv-2026-04-22-uaix-001",
        "turn_id": "turn-001",
        "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
        "sequence": 1
    },
    "delivery": {
        "mode": "async",
        "priority": "interactive",
        "expires_at": "2026-04-22T16:05:00Z",
        "reply_requested": true,
        "ack_required": true
    },
    "trust": {
        "channel": "credentialed",
        "auth_scheme": "did+vc",
        "principal": "did:web:agents.alpha.example",
        "credential_ref": "https://agents.alpha.example/credentials/uai-interop.json",
        "signature_ref": "https://agents.alpha.example/signatures/msg-2026-04-22-0001.jws",
        "replay_window_id": "rw-2026-04-22-0001"
    },
    "body": {
        "intent": "resolve-profile",
        "subject": "uai.task.status.v1",
        "requested_profile": "uai.task.status.v1",
        "parameters": {
            "include_schema": true,
            "include_example": true,
            "include_field_registry": true
        },
        "constraints": [
            "public-record-only",
            "trace-linked",
            "validator-ready"
        ],
        "response_profile": "uai.intent.response.v1"
    },
    "provenance": {
        "trace_id": "trace-7f3a2d",
        "parent_trace_id": "trace-root-uaix-2026",
        "issued_at": "2026-04-22T16:00:00Z",
        "log_ref": "urn:uaix:log:2026:0001",
        "agent_id": "agent.alpha",
        "model_id": "model.alpha.reasoner-2",
        "confidence": 0.98,
        "lineage": [
            {
                "stage": "request-composition",
                "actor_id": "agent.alpha",
                "model_id": "model.alpha.reasoner-2",
                "note": "Requested the async task-status profile and matching field registry."
            }
        ]
    },
    "integrity": {
        "version": 2,
        "algorithm": "sha256",
        "canonicalization": "jcs",
        "checksum": "sha256:dd8a9d16c9226cc9d1f4888a4d2bbcbf06b5b4b8"
    },
    "extensions": [
        {
            "namespace": "urn:uaix:ext:delivery",
            "purpose": "Explicit async request handling and expiry semantics.",
            "critical": false
        }
    ]
}

验证请求 Wrap the packet for validator POST validate-request.json

{
    "message": {
        "uai_version": "1.0",
        "profile": "uai.intent.request.v1",
        "message_id": "msg-2026-04-22-0001",
        "source": {
            "type": "agent",
            "id": "agent.alpha",
            "label": "Agent Alpha",
            "uri": "https://agents.alpha.example/runtime",
            "did": "did:web:agents.alpha.example",
            "role": "requesting-agent",
            "implementation": "alpha-runtime-2.4.1"
        },
        "target": {
            "type": "service",
            "id": "uaix.gateway",
            "label": "UAIX Gateway",
            "uri": "https://uaix.org/wp-json/uaix/v1/discovery",
            "did": "did:web:uaix.org",
            "role": "public-record-gateway",
            "implementation": "uaix-core-0.4.0"
        },
        "conversation": {
            "conversation_id": "conv-2026-04-22-uaix-001",
            "turn_id": "turn-001",
            "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
            "sequence": 1
        },
        "delivery": {
            "mode": "async",
            "priority": "interactive",
            "expires_at": "2026-04-22T16:05:00Z",
            "reply_requested": true,
            "ack_required": true
        },
        "trust": {
            "channel": "credentialed",
            "auth_scheme": "did+vc",
            "principal": "did:web:agents.alpha.example",
            "credential_ref": "https://agents.alpha.example/credentials/uai-interop.json",
            "signature_ref": "https://agents.alpha.example/signatures/msg-2026-04-22-0001.jws",
            "replay_window_id": "rw-2026-04-22-0001"
        },
        "body": {
            "intent": "resolve-profile",
            "subject": "uai.task.status.v1",
            "requested_profile": "uai.task.status.v1",
            "parameters": {
                "include_schema": true,
                "include_example": true,
                "include_field_registry": true
            },
            "constraints": [
                "public-record-only",
                "trace-linked",
                "validator-ready"
            ],
            "response_profile": "uai.intent.response.v1"
        },
        "provenance": {
            "trace_id": "trace-7f3a2d",
            "parent_trace_id": "trace-root-uaix-2026",
            "issued_at": "2026-04-22T16:00:00Z",
            "log_ref": "urn:uaix:log:2026:0001",
            "agent_id": "agent.alpha",
            "model_id": "model.alpha.reasoner-2",
            "confidence": 0.98,
            "lineage": [
                {
                    "stage": "request-composition",
                    "actor_id": "agent.alpha",
                    "model_id": "model.alpha.reasoner-2",
                    "note": "Requested the async task-status profile and matching field registry."
                }
            ]
        },
        "integrity": {
            "version": 2,
            "algorithm": "sha256",
            "canonicalization": "jcs",
            "checksum": "sha256:dd8a9d16c9226cc9d1f4888a4d2bbcbf06b5b4b8"
        },
        "extensions": [
            {
                "namespace": "urn:uaix:ext:delivery",
                "purpose": "Explicit async request handling and expiry semantics.",
                "critical": false
            }
        ]
    },
    "format": "result"
}

Reference exchange Ask the live mock surface for one conforming response mock-exchange-request.json

{
    "scenario": "accepted-task",
    "format": "exchange",
    "message": {
        "uai_version": "1.0",
        "profile": "uai.intent.request.v1",
        "message_id": "msg-2026-04-22-0001",
        "source": {
            "type": "agent",
            "id": "agent.alpha",
            "label": "Agent Alpha",
            "uri": "https://agents.alpha.example/runtime",
            "did": "did:web:agents.alpha.example",
            "role": "requesting-agent",
            "implementation": "alpha-runtime-2.4.1"
        },
        "target": {
            "type": "service",
            "id": "uaix.gateway",
            "label": "UAIX Gateway",
            "uri": "https://uaix.org/wp-json/uaix/v1/discovery",
            "did": "did:web:uaix.org",
            "role": "public-record-gateway",
            "implementation": "uaix-core-0.4.0"
        },
        "conversation": {
            "conversation_id": "conv-2026-04-22-uaix-001",
            "turn_id": "turn-001",
            "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
            "sequence": 1
        },
        "delivery": {
            "mode": "async",
            "priority": "interactive",
            "expires_at": "2026-04-22T16:05:00Z",
            "reply_requested": true,
            "ack_required": true
        },
        "trust": {
            "channel": "credentialed",
            "auth_scheme": "did+vc",
            "principal": "did:web:agents.alpha.example",
            "credential_ref": "https://agents.alpha.example/credentials/uai-interop.json",
            "signature_ref": "https://agents.alpha.example/signatures/msg-2026-04-22-0001.jws",
            "replay_window_id": "rw-2026-04-22-0001"
        },
        "body": {
            "intent": "resolve-profile",
            "subject": "uai.task.status.v1",
            "requested_profile": "uai.task.status.v1",
            "parameters": {
                "include_schema": true,
                "include_example": true,
                "include_field_registry": true
            },
            "constraints": [
                "public-record-only",
                "trace-linked",
                "validator-ready"
            ],
            "response_profile": "uai.intent.response.v1"
        },
        "provenance": {
            "trace_id": "trace-7f3a2d",
            "parent_trace_id": "trace-root-uaix-2026",
            "issued_at": "2026-04-22T16:00:00Z",
            "log_ref": "urn:uaix:log:2026:0001",
            "agent_id": "agent.alpha",
            "model_id": "model.alpha.reasoner-2",
            "confidence": 0.98,
            "lineage": [
                {
                    "stage": "request-composition",
                    "actor_id": "agent.alpha",
                    "model_id": "model.alpha.reasoner-2",
                    "note": "Requested the async task-status profile and matching field registry."
                }
            ]
        },
        "integrity": {
            "version": 2,
            "algorithm": "sha256",
            "canonicalization": "jcs",
            "checksum": "sha256:dd8a9d16c9226cc9d1f4888a4d2bbcbf06b5b4b8"
        },
        "extensions": [
            {
                "namespace": "urn:uaix:ext:delivery",
                "purpose": "Explicit async request handling and expiry semantics.",
                "critical": false
            }
        ]
    }
}

Keep the starter packet, validator request, and optional mock-exchange request together with the returned result. That bundle is the smallest repeatable proof-and-response packet on the current public surface.

Read UAI-1 Open API reference page Open adoption kit page Open validator page Open conformance pack page

Starter snippets use the live public routes, not a private SDK or unpublished helper layer.

Adoption kit Fetch the published onboarding bundle uai-adoption-kit.json

curl -sS "http://uiax.org/wp-json/uaix/v1/adoption-kit" -o uai-adoption-kit.json

Catalog Resolve the live route catalog

curl -sS "http://uiax.org/wp-json/uaix/v1/catalog"

Example Fetch one published starter packet example-record.json

curl -sS "http://uiax.org/wp-json/uaix/v1/examples/uai.intent.request.v1" -o example-record.json

Validate Submit the packet for a result record validate-request.json

curl -sS -X POST "http://uiax.org/wp-json/uaix/v1/validate" \
  -H "Content-Type: application/json" \
  -d @validate-request.json

Mock exchange Request one live conforming response mock-exchange-request.json

curl -sS -X POST "http://uiax.org/wp-json/uaix/v1/mock-exchange" \
  -H "Content-Type: application/json" \
  -d @mock-exchange-request.json

Adoption kit Fetch the published onboarding bundle uai-adoption-kit.json

Invoke-RestMethod -Uri "http://uiax.org/wp-json/uaix/v1/adoption-kit" | ConvertTo-Json -Depth 20 | Set-Content .\uai-adoption-kit.json

Catalog Resolve the live route catalog

Invoke-RestMethod -Uri "http://uiax.org/wp-json/uaix/v1/catalog"

Example Fetch one published starter packet example-record.json

Invoke-RestMethod -Uri "http://uiax.org/wp-json/uaix/v1/examples/uai.intent.request.v1" | ConvertTo-Json -Depth 20 | Set-Content .\example-record.json

Validate Submit the packet for a result record validate-request.json

$message = (Get-Content -Raw .\example-record.json | ConvertFrom-Json).message
$body = @{ message = $message; format = "result" } | ConvertTo-Json -Depth 20
Invoke-RestMethod -Method Post -Uri "http://uiax.org/wp-json/uaix/v1/validate" -ContentType "application/json" -Body $body

Mock exchange Request one live conforming response mock-exchange-request.json

$message = (Get-Content -Raw .\example-record.json | ConvertFrom-Json).message
$body = @{ scenario = "accepted-task"; format = "exchange"; message = $message } | ConvertTo-Json -Depth 20
Invoke-RestMethod -Method Post -Uri "http://uiax.org/wp-json/uaix/v1/mock-exchange" -ContentType "application/json" -Body $body

Adoption kit Fetch the published onboarding bundle uai-adoption-kit.json

import json, urllib.request
kit = json.load(urllib.request.urlopen("http://uiax.org/wp-json/uaix/v1/adoption-kit"))

Catalog Resolve the live route catalog

import json, urllib.request
catalog = json.load(urllib.request.urlopen("http://uiax.org/wp-json/uaix/v1/catalog"))

Example Fetch one published starter packet example-record.json

example_record = json.load(urllib.request.urlopen("http://uiax.org/wp-json/uaix/v1/examples/uai.intent.request.v1"))
message = example_record.get("message", example_record)

Validate Submit the packet for a result record validate-request.json

payload = json.dumps({"message": message, "format": "result"}).encode("utf-8")
request = urllib.request.Request("http://uiax.org/wp-json/uaix/v1/validate", data=payload, headers={"Content-Type": "application/json"}, method="POST")
result = json.load(urllib.request.urlopen(request))

Mock exchange Request one live conforming response mock-exchange-request.json

payload = json.dumps({"scenario": "accepted-task", "format": "exchange", "message": message}).encode("utf-8")
request = urllib.request.Request("http://uiax.org/wp-json/uaix/v1/mock-exchange", data=payload, headers={"Content-Type": "application/json"}, method="POST")
exchange = json.load(urllib.request.urlopen(request))

Adoption kit Fetch the published onboarding bundle uai-adoption-kit.json

const kit = await fetch("http://uiax.org/wp-json/uaix/v1/adoption-kit").then((response) => response.json());

Catalog Resolve the live route catalog

const catalog = await fetch("http://uiax.org/wp-json/uaix/v1/catalog").then((response) => response.json());

Example Fetch one published starter packet example-record.json

const exampleRecord = await fetch("http://uiax.org/wp-json/uaix/v1/examples/uai.intent.request.v1").then((response) => response.json());
const message = exampleRecord.message ?? exampleRecord;

Validate Submit the packet for a result record validate-request.json

const result = await fetch("http://uiax.org/wp-json/uaix/v1/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ message, format: "result" }),
}).then((response) => response.json());

Mock exchange Request one live conforming response mock-exchange-request.json

const exchange = await fetch("http://uiax.org/wp-json/uaix/v1/mock-exchange", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ scenario: "accepted-task", format: "exchange", message }),
}).then((response) => response.json());

Read UAI-1 Examples Open adoption kit page Open validator page Open conformance pack page

Discovery and sitemap surfaces

Automation and public QA should be able to resolve the same page inventory from both the root discovery surface and the locale-prefixed route space.

Use /.well-known/uaix.json as the preferred machine-readable manifest.
Use /sitemap.xml and /sitemap.html as the durable root crawl and directory surfaces.
Use /en-us/sitemap.xml and /en-us/sitemap.html when localized readers or tooling need the same inventory through the English route space.
Treat the root sitemap files as the canonical public SEO surface even when locale-prefixed sitemap routes are also live and tested.

Current machine-facing routes

The public tooling surface includes a human-facing validator page plus machine-facing REST routes for automation and release checks.

/wp-json/uaix/v1/catalog and /wp-json/uaix/v1/discovery expose the current standards catalog and discovery manifest.
/wp-json/uaix/v1/status and /wp-json/uaix/v1/modules expose runtime status and module inventory.
/wp-json/uaix/v1/schemas, /wp-json/uaix/v1/registry, /wp-json/uaix/v1/field-registry, and /wp-json/uaix/v1/examples expose the published machine-readable record families.
/wp-json/uaix/v1/transport-bindings, /wp-json/uaix/v1/trust-channels, /wp-json/uaix/v1/conformance-levels, and /wp-json/uaix/v1/error-registry expose the operating guidance that makes transport, trust, support claims, and failure handling explicit.
/wp-json/uaix/v1/validate is the JSON POST validation endpoint for automation; use the Validator page when a human needs the workbench experience.
/wp-json/uaix/v1/roadmap exposes the forward-plan boundary for current, next, planned, and research-track work.

API reference and reusable pack surfaces

API Reference turns the live REST surface into a route-by-route handbook with a published OpenAPI 3.1 document and starter request examples.
Adoption Kit publishes the first-proof onboarding bundle with starter files, validator-ready payloads, and mock-exchange examples.
Conformance Pack assembles the broader schemas, registry data, fixtures, transport and trust guidance, and validator entry points into one reusable machine-readable packet.
/wp-json/uaix/v1/adoption-kit is the machine-facing onboarding bundle for the shortest reusable first-proof run; append ?download=1 when you want the same response as an attachment.
/wp-json/uaix/v1/openapi.json is the machine-facing OpenAPI export for the live UAIX REST surface.
/wp-json/uaix/v1/conformance-pack is the machine-facing JSON packet for launch review and repeatable conformance work; append ?download=1 when you want the same response as an attachment.
/wp-json/uaix/v1/roadmap is the machine-facing forward-plan record for current, next, planned, and research-track work; append ?download=1 when you want the same response as an attachment.

Published operating-surface references

The records below are part of the live machine-readable protocol surface and should be carried with schema and example resolution when you are evaluating interoperability or support claims.

Transport

Published bindings

Default: https-json-envelope.v1
Bindings: 2

https-json-envelope.v1: application/vnd.uaix.uai+json
https-json-keyless.v1: application/vnd.uaix.uai-keyless+json

Open transport JSON

Trust

Published trust channels

public-web: Publicly readable records over HTTPS with no prior bilateral trust setup.
private-api: Service-to-service exchange on a scoped network or tenant boundary.
mtls: Transport-authenticated exchange where peer identity is anchored at the connection layer.
signed-envelope: Message-level signature or detached signature reference accompanies the record.
credentialed: The sender or execution context is backed by a machine-verifiable credential or comparable signed identity assertion.

Open trust JSON

Conformance

Published level ladder

L1-core-envelope: Core Envelope
L2-exchange-participant: Exchange Participant
L3-async-workflow: Async Workflow
L4-public-record-publisher: Public Record Publisher

Open conformance JSON

Errors

Published message error codes

invalid_message: Invalid message
unknown_profile: Unknown profile
capability_not_supported: Capability not supported
auth_required: Authentication required
insufficient_trust: Insufficient trust
task_not_found: Task not found

Open error registry JSON

Discovery surface

Automation should start with the current UAIX discovery manifest and standards catalog.

Discovery manifest

Well-known entry points

Use the `.well-known` manifest for durable site discovery, or the REST discovery route when you want the same data from the API surface. Production deployments should publish the same manifest from the canonical HTTPS origin.

Release: UAI-1
Profiles: 6
Generated: 2026-04-26T15:33:17+00:00

Open /.well-known/uaix.json Open discovery JSON

Public routes

Current machine-facing surface

The manifest advertises the API and public publication paths that make up the current UAIX standards surface.

Catalog: /wp-json/uaix/v1/catalog
Schemas: /wp-json/uaix/v1/schemas
Registry: /wp-json/uaix/v1/registry
Field registry: /wp-json/uaix/v1/field-registry
Transport bindings: /wp-json/uaix/v1/transport-bindings
Trust channels: /wp-json/uaix/v1/trust-channels
Conformance levels: /wp-json/uaix/v1/conformance-levels
Error registry: /wp-json/uaix/v1/error-registry
Examples: /wp-json/uaix/v1/examples
Validate: /wp-json/uaix/v1/validate (POST JSON)
Adoption kit: /wp-json/uaix/v1/adoption-kit
Mock exchange: /wp-json/uaix/v1/mock-exchange (GET metadata, POST message)

Next step

Start with the Validator, then carry the resulting evidence into Implementations, the Changelog, and News when the result affects a public release.

Tooling

What tools should help with

Primary tooling path

Hello-world conformance path

Published starter path

How the first proof packet should move through validation

Resolve the live catalog

Fetch one starter example

Wrap the message for validation

Run one validator check

Test the live reference response

Carry only the named next step

Copyable starter requests in curl, PowerShell, Python, and TypeScript

Plain shell

Windows-native call path

Python standard library

Typed fetch workflow

Discovery and sitemap surfaces

Current machine-facing routes

API reference and reusable pack surfaces

Published operating-surface references

Transport, trust, errors, and conformance

Published bindings

Published trust channels

Published level ladder

Published message error codes

Discovery surface

Machine-readable standards discovery

Well-known entry points

Current machine-facing surface

Next step

Tooling#

What tools should help with#

Primary tooling path#

Hello-world conformance path#

Published starter path#

How the first proof packet should move through validation#

Resolve the live catalog#

Fetch one starter example#

Wrap the message for validation#

Run one validator check#

Test the live reference response#

Carry only the named next step#

Copyable starter requests in curl, PowerShell, Python, and TypeScript#

Plain shell#

Windows-native call path#

Python standard library#

Typed fetch workflow#

Discovery and sitemap surfaces#

Current machine-facing routes#

API reference and reusable pack surfaces#

Published operating-surface references#

Transport, trust, errors, and conformance#

Published bindings#

Published trust channels#

Published level ladder#

Published message error codes#

Discovery surface#

Machine-readable standards discovery#

Well-known entry points#

Current machine-facing surface#

Next step#

Tooling

What tools should help with

Primary tooling path

Hello-world conformance path

Published starter path

How the first proof packet should move through validation

Resolve the live catalog

Fetch one starter example

Wrap the message for validation

Run one validator check

Test the live reference response

Carry only the named next step

Copyable starter requests in curl, PowerShell, Python, and TypeScript

Plain shell

Windows-native call path

Python standard library

Typed fetch workflow

Discovery and sitemap surfaces

Current machine-facing routes

API reference and reusable pack surfaces

Published operating-surface references

Transport, trust, errors, and conformance

Published bindings

Published trust channels

Published level ladder

Published message error codes

Discovery surface

Machine-readable standards discovery

Well-known entry points

Current machine-facing surface

Next step