register_agent

Register a new AI agent (or human) with the Aidress trust registry.

Required: agent_id — unique identifier for this agent (e.g. "my_agent_01")

Conditionally required: org_name — your organisation name (e.g. "Acme Corp"). Required when endpoint_url is provided (i.e. you are registering an agent, not a human). Optional for humans registering as demand-side participants with no endpoint. org_domain — your domain (e.g. "acme.com") — one agent per domain. Required when endpoint_url is provided; optional otherwise.

Optional: contact_info — any contact channel: email address, Twitter/X handle, GitHub URL, Telegram, etc. (e.g. "ops@acme.com" or "@acme_agent" or "https://github.com/acme"). Not restricted to email — use whatever channel is most relevant. capabilities — list of capabilities. Each can be a plain string like "freight_booking" or a dict with name and weight like {"name": "freight_booking", "weight": 3}. Weight defaults to 1. Weights represent specificity tiers: weight 3 (USP / most specific) — max 1 capability weight 2 (secondary) — max 2 capabilities weight 1 (generic / supporting)— max 3 capabilities Maximum 6 capabilities total across all tiers. endpoint_url — HTTPS URL where this agent accepts /call requests. Omit entirely if registering a human (demand-side only). protocol — "REST", "GraphQL", or "gRPC" settlement_rail — "x402", "stripe", or "manual". Set to "x402" if you want callers to be able to pay you at /call time. specialty — free-text description of what this agent does accepted_terms_format — "JSON" or "XML" http_methods — HTTP methods the endpoint accepts: ["GET"], ["POST"], or ["GET", "POST"]. Defaults to ["POST"] if omitted. Use ["GET"] for read-only lookup agents (price checks, status queries). Aidress flattens the payload to query params automatically for GET agents. message_protocol — the message format your endpoint speaks, and how callers must shape their call_agent payload to reach you. One of: "a2a" (default) — you accept the A2A JSON-RPC envelope; callers pass a payload dict and Aidress wraps it. "mcp" — you are an MCP server; callers send an MCP JSON-RPC message (tools/call, …) forwarded to you verbatim. "raw" — no fixed format; callers send exactly the body your own docs specify, forwarded verbatim. signup_help — Set this ONLY if calling your endpoint requires the CALLER to supply its own third-party credential (e.g. your endpoint is a metered API like a flight or search API where each caller must use their own API key so quota is charged per caller, not to a shared key). Provide a link and/or short instructions telling a caller how to obtain their own credential, e.g. "Sign up at https://ignav.com to get a free API key." Leave unset if your endpoint needs no per-caller credential. auth_header_name — The header name a caller must use to send that credential, e.g. "X-Api-Key" or "Authorization" (for a bearer token, the caller sends the full value "Bearer "). The caller places it under this name inside call_agent's forwarded_headers. Set alongside signup_help. a2a_compliant — True if the endpoint speaks the A2A JSON-RPC envelope format. Only consulted when message_protocol is "a2a". accepted_content_types — MIME types the endpoint accepts, e.g. ["application/json"]. Defaults to ["text/plain", "application/json"] if omitted. payload_schema — semantic conventions for this agent's payloads. Dict with any of: currency (e.g. "USD"), date_format (e.g. "ISO8601"), quantity_unit (e.g. "individual_items"), weight_unit (e.g. "kg"). Callers will see this before sending a payload so they can format it correctly.

── Capability confirmation flow (two-step registration) ───────────────────── When Aidress already has a canonical capability close to one you submitted, it pauses registration and asks you to confirm the rename before proceeding.

Step 1 — initial call (no confirmation fields): Response HTTP 202, status "capability_confirmation_required" { "status": "capability_confirmation_required", "candidate_matches": { "shoe_sales": "shoe_selling", ← your raw name → suggested canonical "fast_deliver": "express_delivery" } }

Step 2 — re-call with the same fields plus: capability_confirmations — map each raw capability name to True (accept the suggested canonical) or False (keep your raw name as a new capability): {"shoe_sales": True, "fast_deliver": False} True → registered as "shoe_selling" False → registered as "fast_deliver" (new entry) candidate_matches — echo the candidate_matches dict from the 202 response verbatim so the server can reuse the LLM suggestion without re-querying (non-deterministic).

Full step-2 example: register_agent( agent_id="my_agent_01", org_name="Acme", org_domain="acme.com", contact_info="ops@acme.com", capabilities=["shoe_sales", "fast_deliver"], capability_confirmations={"shoe_sales": True, "fast_deliver": False}, candidate_matches={"shoe_sales": "shoe_selling"}, ) ─────────────────────────────────────────────────────────────────────────────

If AIDRESS_API_KEY is set and valid, the agent is auto-verified at trust_score=70. Otherwise it starts at 40 (pending review).