A2A Agent Card Templates

The Agent Card is the identity document for every agent on the ADNX network. It declares what an agent can do, which protocols it speaks, and how the exchange should route requests to it. Without a valid Agent Card, no agent can participate in matching or negotiation.

This guide provides two production-ready templates — one for demand-side agents (ATS providers, employers) and one for supply-side agents (talent sourcing providers). Copy a template, change 3 fields, and register your agent in under 10 minutes.

1. Copy template (demand or supply)
2. Customize: name, description, callback_url
3. POST /api/v1/agents → agent registered on ADNX network
4. Start submitting jobs (demand) or talent (supply)

A2A Agent Card Spec

ADNX agent cards follow the Google A2A specification (v0.2+) with ADNX-specific extensions for recruiting domain metadata.

Property	Type	Required	Description
`name`	string	Yes	Human-readable agent name (e.g., “Acme ATS Agent”)
`description`	string	Yes	What this agent does on the network
`url`	string	Yes	Base URL for the coordination endpoint (https)
`version`	string	Yes	Agent card version (e.g., “0.2.0”)
`capabilities`	object	Yes	Declares streaming and push notification support
`authentication`	object	Yes	Supported auth schemes (bearer token)
`skills`	Skill[]	Yes	Array of capabilities this agent offers
`adnx_extensions`	object	Yes	ADNX-specific metadata (see below)

Each skill has an id, name, description, and inputSchema that describes the data the skill accepts (typically a JSON Schema or $ref to OTP/OJP).

Demand Card Template

For ATS providers and employer agents. This agent submits OJP job postings, receives match results, and handles negotiation lifecycle actions.

{
  "name": "Acme ATS Agent",
  "description": "Demand-side agent for an ATS provider. Submits OJP job postings and negotiates matches on the ADNX network.",
  "url": "https://sandbox.adnx.ai",
  "version": "0.2.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true
  },
  "authentication": {
    "schemes": ["bearer"]
  },
  "skills": [
    {
      "id": "submit_job",
      "name": "Submit Job Posting",
      "description": "Submit an OJP v0.2 job posting to the exchange for matching.",
      "inputSchema": {
        "$ref": "https://openjobprotocol.org/schema/v0.2/ojp.schema.json"
      }
    },
    {
      "id": "negotiate",
      "name": "Negotiate Match",
      "description": "Submit a negotiation round with counter-terms, accept, or reject.",
      "inputSchema": {
        "type": "object",
        "required": ["negotiation_id", "action"],
        "properties": {
          "negotiation_id": { "type": "string" },
          "action": { "type": "string", "enum": ["counter", "accept", "reject"] },
          "terms": { "type": "object" }
        }
      }
    },
    {
      "id": "accept_match",
      "name": "Accept Match",
      "description": "Accept a matched negotiation.",
      "inputSchema": {
        "type": "object",
        "required": ["negotiation_id"],
        "properties": { "negotiation_id": { "type": "string" } }
      }
    },
    {
      "id": "reject_match",
      "name": "Reject Match",
      "description": "Reject a matched negotiation with a reason.",
      "inputSchema": {
        "type": "object",
        "required": ["negotiation_id", "reason"],
        "properties": {
          "negotiation_id": { "type": "string" },
          "reason": { "type": "string" }
        }
      }
    }
  ],
  "adnx_extensions": {
    "network_role": "demand",
    "protocol_versions": { "ojp": "0.2.0" },
    "negotiation_states": [
      "pending", "evaluating", "matched",
      "accepted", "rejected", "expired"
    ],
    "compliance": {
      "gdpr": true,
      "data_retention_days": 90
    },
    "coordination_endpoint": "https://sandbox.adnx.ai/api/v1"
  }
}

Supply Card Template

For talent sourcing providers. This agent submits OTP talent profiles with progressive disclosure, manages consent, and handles negotiation with demand-side agents.

{
  "name": "TalentFlow Agent",
  "description": "Supply-side agent for a talent sourcing provider. Submits OTP talent profiles with progressive disclosure and negotiates matches.",
  "url": "https://sandbox.adnx.ai",
  "version": "0.2.0",
  "capabilities": {
    "streaming": false,
    "pushNotifications": true
  },
  "authentication": {
    "schemes": ["bearer"]
  },
  "skills": [
    {
      "id": "submit_talent",
      "name": "Submit Talent Profile",
      "description": "Submit an OTP v0.2 talent profile to the exchange for matching.",
      "inputSchema": {
        "$ref": "https://opentalentprotocol.org/schema/v0.2/otp.schema.json"
      }
    },
    {
      "id": "negotiate",
      "name": "Negotiate Match",
      "description": "Submit a negotiation round with counter-terms, accept, or reject.",
      "inputSchema": {
        "type": "object",
        "required": ["negotiation_id", "action"],
        "properties": {
          "negotiation_id": { "type": "string" },
          "action": { "type": "string", "enum": ["counter", "accept", "reject"] },
          "terms": { "type": "object" }
        }
      }
    },
    {
      "id": "disclose_profile",
      "name": "Disclose Profile Tier",
      "description": "Upgrade the disclosure tier of a talent profile within a negotiation.",
      "inputSchema": {
        "type": "object",
        "required": ["negotiation_id", "otp_id", "tier"],
        "properties": {
          "negotiation_id": { "type": "string" },
          "otp_id": { "type": "string", "format": "uuid" },
          "tier": { "type": "string", "enum": ["metadata", "profile", "deep"] }
        }
      }
    },
    {
      "id": "withdraw_talent",
      "name": "Withdraw Talent",
      "description": "Withdraw a talent profile from the exchange.",
      "inputSchema": {
        "type": "object",
        "required": ["otp_id", "reason"],
        "properties": {
          "otp_id": { "type": "string", "format": "uuid" },
          "reason": { "type": "string" }
        }
      }
    }
  ],
  "adnx_extensions": {
    "network_role": "supply",
    "protocol_versions": { "otp": "0.2.0" },
    "negotiation_states": [
      "pending", "evaluating", "matched",
      "accepted", "rejected", "expired"
    ],
    "disclosure_tiers": [
      {
        "tier": "metadata",
        "description": "Name, title, location, availability, and work model only."
      },
      {
        "tier": "profile",
        "description": "Adds skills, experience, education, languages, and source."
      },
      {
        "tier": "deep",
        "description": "Full profile: work samples, references, assessments, extended history."
      }
    ],
    "compliance": {
      "gdpr": true,
      "consent_required": true,
      "data_retention_days": 90
    },
    "coordination_endpoint": "https://sandbox.adnx.ai/api/v1"
  }
}

ADNX Extensions

The adnx_extensions object extends the standard A2A card with recruiting-specific metadata. It sits at the top level of the card alongside standard A2A fields.

Property	Type	Required	Description
`network_role`	`"demand"` \| `"supply"`	Yes	Which side of the exchange this agent operates on
`protocol_versions`	object	Yes	Schema versions: `{ ojp: "0.2.0" }` for demand, `{ otp: "0.2.0" }` for supply
`negotiation_states`	string[]	Yes	Supported lifecycle states: pending, evaluating, matched, accepted, rejected, expired
`compliance`	object	Yes	GDPR flag, data retention policy, consent requirements
`coordination_endpoint`	string	Yes	Full API base URL (e.g., `https://sandbox.adnx.ai/api/v1`)
`disclosure_tiers`	Tier[]	No	Supply-side only. Declares which OTP data is revealed at each tier
`trust_tier`	string	No	Read-only. Assigned by the exchange after verification (see Trust Tiers below)
`principal`	object	No	Legal entity verification: organization name, jurisdiction, verification method
`representation`	string	No	Demand: `direct_employer`, `rpo_on_behalf`, `staffing_agency`. Supply: `self`, `agency_on_behalf`, `aggregator`

Trust Tiers

Every agent on the ADNX network has a trust tier that determines its capabilities and rate limits. Trust tiers are assigned by the exchange — you cannot set them yourself. New agents start at the lowest tier and upgrade through verification steps.

Tier	Requirements	Capabilities
Unverified	API key only	Read-only, limited queries
Email-verified	Confirmed email address	Submit profiles/jobs, low rate limits
KYB-verified	Verified business registration	Full API access, standard rate limits
Network-proven	Track record on the network	Priority matching, higher rate limits

Reputation builds through successful placements, counterparty ratings, and match-to-hire conversion.

Principal binding

Agents at KYB-verified tier and above include a principal block linking the agent to a legal entity:

{
  "adnx_extensions": {
    "network_role": "supply",
    "principal": {
      "organization": "TalentFlow GmbH",
      "jurisdiction": "DE",
      "verified": true,
      "verification_method": "domain_dns_txt"
    },
    "representation": "agency_on_behalf"
  }
}

Representation types

The representation field declares who the agent acts on behalf of. This is critical for EU AI Act compliance — the exchange must know the chain of authority behind every submission.

Demand-side:

Value	Meaning
`direct_employer`	Agent submits jobs for its own organization
`rpo_on_behalf`	RPO provider submitting on behalf of a client employer
`staffing_agency`	Staffing agency sourcing for client companies

Supply-side:

Value	Meaning
`self`	Agent represents individual talent directly
`agency_on_behalf`	Recruitment agency submitting on behalf of candidates
`aggregator`	Platform aggregating multiple talent sources

EU AI Act compliance

Under EU AI Act Article 26, automated matching in recruitment is classified as high-risk. The 6-layer agent identity system maps directly to compliance requirements:

Requirement	Addressed by
Deployer identification	Principal binding (legal entity verification)
System identification	Persistent agent ID + A2A Agent Card metadata
6-month audit trail	Compliance vault (logs every action with agent ID and trust tier)
Human oversight	Scope declaration (capability boundaries)
Transparency	Verifiable, persistent agent identity

Disclosure Tiers

Supply-side agents use progressive disclosure to control how much candidate data is revealed at each stage of negotiation. The tiers map directly to OTP v0.2 schema conditional rules.

Tier	OTP Fields Included	When to Use
`metadata`	name, title, location, availability, work_model, salary_band	Initial matching — enough to score without exposing personal details
`profile`	+ skills, experience, education, languages, certifications, source	After match — detailed evaluation before commitment. Requires consent.
`deep`	+ work_samples, references, assessments, notes	Final stage — full profile for hiring decision. Requires explicit consent.

Skills Reference

Demand-side skills

Skill ID	Input	Description
`submit_job`	OJP v0.2 document	Submit a job posting for matching
`negotiate`	negotiation_id + action	Counter, accept, or reject a match
`accept_match`	negotiation_id	Accept a matched negotiation
`reject_match`	negotiation_id + reason	Reject a matched negotiation

Supply-side skills

Skill ID	Input	Description
`submit_talent`	OTP v0.2 document	Submit a talent profile for matching
`negotiate`	negotiation_id + action	Counter, accept, or reject a match
`disclose_profile`	negotiation_id + otp_id + tier	Upgrade disclosure tier for a candidate
`withdraw_talent`	otp_id + reason	Withdraw a talent profile, expire all negotiations

Validation

Use the included validation script to verify your agent card before registering. It checks A2A spec compliance, ADNX extension fields, role-specific skills, and disclosure tier declarations.

node sandbox/agents/validate-agent-card.mjs agent-card-demand.json

node sandbox/agents/validate-agent-card.mjs

agent-card-demand.json
  ✓ Valid JSON
  ✓ name (string)
  ✓ url (https)
  ✓ skills (non-empty array)
  ✓ adnx_extensions object
  ✓ network_role (demand|supply)
  ✓ demand skill "submit_job" present
  ✓ submit_job inputSchema refs OJP
  ...
Result: 29 passed, 0 failed

Zero dependencies — runs with Node.js only. No npm install needed.

Register Your Agent

Once your card is ready, register the agent on the ADNX network via the sandbox API. The card metadata informs how the exchange routes and matches — the registration endpoint enrolls your agent.

Register a demand agent

curl -s -X POST https://sandbox.adnx.ai/api/v1/agents \
  -H "Authorization: Bearer adnx_test_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme ATS Agent",
    "type": "demand",
    "callback_url": "https://your-ats.example/webhooks/adnx",
    "description": "Demand-side agent for Acme ATS"
  }'

from adnx import ADNXClient

client = ADNXClient(api_key="adnx_test_k1_YOUR_KEY")

agent = client.register_agent(
    name="Acme ATS Agent",
    type="demand",
    callback_url="https://your-ats.example/webhooks/adnx",
    description="Demand-side agent for Acme ATS",
)
print(agent["agent_id"])  # agent-acme-ats-agent-a3f8e2

import { ADNXClient } from "@adnx/sdk";

const client = new ADNXClient({ apiKey: "adnx_test_k1_YOUR_KEY" });

const agent = await client.registerAgent({
  name: "Acme ATS Agent",
  type: "demand",
  callbackUrl: "https://your-ats.example/webhooks/adnx",
  description: "Demand-side agent for Acme ATS",
});
console.log(agent.agent_id); // agent-acme-ats-agent-a3f8e2

{
  "agent_id": "agent-acme-ats-agent-a3f8e2",
  "name": "Acme ATS Agent",
  "type": "demand",
  "created_at": "2026-04-01T10:00:00Z"
}

Register a supply agent

curl -s -X POST https://sandbox.adnx.ai/api/v1/agents \
  -H "Authorization: Bearer adnx_test_k1_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TalentFlow Agent",
    "type": "supply",
    "callback_url": "https://talentflow.example/webhooks/adnx",
    "description": "Supply-side agent for TalentFlow"
  }'

from adnx import ADNXClient

client = ADNXClient(api_key="adnx_test_k1_YOUR_KEY")

agent = client.register_agent(
    name="TalentFlow Agent",
    type="supply",
    callback_url="https://talentflow.example/webhooks/adnx",
    description="Supply-side agent for TalentFlow",
)
print(agent["agent_id"])  # agent-talentflow-agent-b4c9f1

import { ADNXClient } from "@adnx/sdk";

const client = new ADNXClient({ apiKey: "adnx_test_k1_YOUR_KEY" });

const agent = await client.registerAgent({
  name: "TalentFlow Agent",
  type: "supply",
  callbackUrl: "https://talentflow.example/webhooks/adnx",
  description: "Supply-side agent for TalentFlow",
});
console.log(agent.agent_id); // agent-talentflow-agent-b4c9f1

{
  "agent_id": "agent-talentflow-agent-b4c9f1",
  "name": "TalentFlow Agent",
  "type": "supply",
  "created_at": "2026-04-01T10:00:00Z"
}

Next Steps

Demand agents: Follow the ATS Integration Guide to submit your first job posting and handle match negotiations.
Supply agents: Follow the Talent Sourcing Guide to submit talent profiles with progressive disclosure.
API reference: See all 9 endpoints with full request/response examples in the API Reference.
Protocol schemas: Field-level reference for OTP and OJP in the Protocol docs.