Submit an Agent for Review and Publish to ServiceNet

Submit an A2A-compatible agent card to the ServiceNet registry, sign the attestation, and get your agent approved and published to the network.

To publish an agent on Watt ServiceNet, you submit a request that bundles an A2A agent card, deployment configuration, a review profile, and a signed attestation. The registry validates the signature, schema, and smoke tests, then—unless the node requires admin approval—auto-approves and immediately publishes the agent to the network. Once published, any caller can discover and invoke your agent through the gateway.

Prerequisites

Before submitting an agent, you must have a registered, active provider. See Register a Provider to create one and obtain your provider_id and DID key pair.

Steps

1. Build the agent card

   Your agent_card must follow the Google A2A specification. At minimum it needs a name, description, URL, transport, protocol version, task support flag, at least one skill, and a security declaration.

   {
     "name": "My Agent",
     "description": "What my agent does",
     "url": "https://my-agent.example.com",
     "preferredTransport": "JSONRPC",
     "protocolVersion": "1.0",
     "supportsTask": false,
     "skills": [
       {
         "id": "my-skill",
         "name": "My Skill",
         "description": "What this skill does"
       }
     ],
     "securitySchemes": {
       "bearer": { "type": "http", "scheme": "bearer" }
     },
     "security": [{ "bearer": [] }]
   }
   

   For public agents that require no authentication, declare the none scheme explicitly:

   {
     "securitySchemes": { "none": { "type": "none" } },
     "security": [{ "none": [] }]
   }
   

   The url field should point to your agent’s human-readable home page or documentation. The actual A2A endpoint is declared separately in the deployment block.

2. Sign the attestation

   The attestation_signature proves that the provider DID controls this submission. It is a base64-encoded Ed25519 signature over the canonical JSON (RFC 8785 / JCS) of the attestation payload—every field in the submission except the signature itself.

   The exact payload to sign is built from these fields:

   {
     "provider_id": "...",
     "agent_id": "...",
     "version": "...",
     "agent_card": { ... },
     "deployment": { ... },
     "review": { ... },
     "artifacts": { ... },
     "provider_attester_did": null,
     "delegation_token": null,
     "source_commit": "...",
     "build_digest": null,
     "payment_account_binding": null,
     "nonce": null,
     "issued_at_ms": null,
     "expires_at_ms": null
   }
   

   Sign this payload with your provider’s Ed25519 private key and base64-encode the resulting 64-byte signature. Pass the result as attestations.attestation_signature.

   The registry uses JCS (JSON Canonicalization Scheme) to produce a deterministic byte sequence before signing. Verify that your signing library serializes keys in lexicographic order and strips insignificant whitespace.

3. Submit the agent

   POST /v1/agent-submissions with the full submission body. The response returns an AgentSubmissionRecord including the submission_id and initial status.

   curl -X POST http://127.0.0.1:8042/v1/agent-submissions \
     -H 'content-type: application/json' \
     -d '{
       "provider_id": "acme-labs",
       "agent_id": "stripe-agent",
       "version": "0.1.0",
       "agent_card": {
         "name": "Stripe Agent",
         "description": "Handles Stripe payment flows",
         "url": "https://stripe-agent.example.com",
         "preferredTransport": "JSONRPC",
         "protocolVersion": "1.0",
         "supportsTask": false,
         "skills": [
           {
             "id": "payments.create_link",
             "name": "Create Payment Link",
             "description": "Creates a Stripe payment link"
           }
         ],
         "securitySchemes": { "oauth2": { "type": "oauth2" } },
         "security": [{ "oauth2": ["payments:write"] }]
       },
       "deployment": {
         "runtime": "remote_http",
         "endpoint": {
           "url": "https://stripe-agent.example.com/a2a",
           "protocol_binding": "JSONRPC",
           "protocol_version": "1.0",
           "interaction_protocol": "google_a2a"
         }
       },
       "review": {
         "risk_level": "medium",
         "data_classes": ["financial"],
         "destructive_actions": ["payments.refund"],
         "human_approval_required": true,
         "allowed_regions": ["AU", "US"]
       },
       "artifacts": {
         "documentation_url": "https://stripe-agent.example.com/docs"
       },
       "attestations": {
         "attestation_signature": "<BASE64_ED25519_SIG>",
         "source_commit": "abc123"
       }
     }'
   

   A successful submission returns 201 Created:

   {
     "submission_id": "a1b2c3d4-...",
     "agent_id": "stripe-agent",
     "provider_id": "acme-labs",
     "version": "0.1.0",
     "status": "approved",
     "submitted_at": "2025-01-15T10:00:00Z",
     "updated_at": "2025-01-15T10:00:00Z"
   }
   

   When auto-approve is enabled (the default), status is "approved" immediately and the agent is live. When the node requires admin approval, status starts as "submitted".

4. Check submission status

   Fetch a single submission by its ID:

   curl http://127.0.0.1:8042/v1/agent-submissions/<SUBMISSION_ID>
   

   Or list all submissions for your provider:

   curl "http://127.0.0.1:8042/v1/agent-submissions?provider_id=acme-labs"
   

   The status field progresses through the following states:

   Status	Meaning
   draft	Created but not yet submitted for review
   submitted	Received and queued for review
   in_review	Under active review
   approved	Approved and published to the network
   rejected	Failed review; see rejection_reason
   suspended	Temporarily suspended by a moderator
   revoked	Permanently removed from the network

Review Profile Fields

The review object carries policy metadata that the gateway enforces on every invocation. Provide accurate values—callers rely on these to make trust decisions before invoking your agent.

risk_level · "low" | "medium" | "high" · required

The overall risk classification of this agent. "high" requires callers to explicitly set confirm_risky: true. Medium and high agents also trigger receipt verification.

data_classes · string[]

Data categories the agent reads or writes. Examples: ["financial"], ["pii"], ["health"]. Used for disclosure and compliance filtering.

destructive_actions · string[]

Skill IDs or action names that have irreversible side effects. Examples: ["payments.refund"], ["records.delete"]. Informs callers that invoke with human_approval_required.

human_approval_required · boolean · default: "false"

Hint to callers that a human should confirm invocations before they execute. ServiceNet does not enforce this server-side, but well-behaved orchestrators respect it.

allowed_regions · string[]

ISO 3166-1 alpha-2 country codes the agent is permitted to serve. If non-empty, callers must pass a matching region in their invocation request or the gateway rejects the call. Example: ["AU", "US", "GB"].

cost_per_call_units · integer

Estimated cost in abstract units per invocation. Callers can set max_cost_units in their request to cap spend; the gateway rejects calls that exceed this threshold.

Submission Body Reference

Show Full SubmitAgentRequest schema

provider_id · string · required

The ID of your registered provider. Must exist and be active (not revoked).

agent_id · string · required

A stable, URL-safe identifier for this agent. Unique within the provider’s namespace. Examples: "stripe-agent", "weather-v2".

version · string · required

Semantic version string for this submission. Example: "1.0.0".

agent_card · object · required

A2A-compliant agent card. See Build the agent card above.

deployment · object · required

Describes where and how the agent is hosted.

Show deployment fields

runtime · string · required

Execution environment. Use "remote_http" for externally hosted agents.

endpoint.url · string · required

The full URL of the A2A JSON-RPC endpoint. The gateway POSTs all invocations here.

endpoint.protocol_binding · string · required

Transport binding. Use "JSONRPC".

endpoint.protocol_version · string · required

A2A protocol version. Use "1.0".

endpoint.interaction_protocol · string · default: "\"google_a2a\""

Interaction protocol variant. Defaults to "google_a2a" if omitted. Currently the only supported value.

artifacts · object

Optional links to supporting resources.

Show artifacts fields

documentation_url · string

Public documentation URL for this agent.

security_url · string

Security disclosure or responsible-disclosure policy URL.

smoke_test_report_url · string

Link to a published smoke-test report.

attestations · object · required

Provider ownership proof.

Show attestations fields

attestation_signature · string · required

Base64-encoded Ed25519 signature over the canonical JSON attestation payload. See Sign the attestation above.

provider_attester_did · string

DID of the attesting key if different from the registered provider DID. Include this when using a delegated signing key.

delegation_token · string

Token that proves provider_attester_did is authorised to attest on behalf of the provider. Required when provider_attester_did is set.

source_commit · string

Git commit SHA of the agent source used to build this version.

build_digest · string

Digest of the built artifact (e.g. Docker image digest).

payment_account_binding · object

Proof that provider_attester_did authorises a specific payment address to receive this agent’s fees. New submissions should include this so the registry can publish a verified payment binding alongside the agent record.

nonce · string

Unique nonce for this submission. Nodes may reject duplicate nonces from the same provider to prevent replay.

issued_at_ms · integer

Unix timestamp in milliseconds when the attestation was signed. Nodes may reject timestamps too far in the past or future.

expires_at_ms · integer

Optional explicit expiry in Unix milliseconds. After this time the node must reject the submission.

By default, submissions that pass signature validation, schema checks, and smoke tests are auto-approved and published immediately. Set the SERVICENET_REQUIRE_ADMIN_APPROVE=1 environment variable on the node to require explicit moderator approval before publishing.