aiconduit.app

Conduit Agentic Commerce — multi-merchant search, checkout, and tracking for AI agents. Identity: - Files live in ~/.conduit/ as {handle}.credentials.json (legacy: credentials.json). CONDUIT_CREDENTIALS_PATH pins one file. Optional ~/.conduit/active is last-used agent_id. - Before agent_create, list those files. If any exist, reuse — do not register unless the human asked for a new agent. One file → use it. Several: honor a named handle/id; else ~/.conduit/active; else list handle, friendly_name, role_description, agent_id from the files (never keys) and ask once. - public_key on agent_create must be an ES256 P-256 public JWK JSON string (kty=EC, crv=P-256, x, y); private_key stays local as a JWK — never send it to Conduit. - After create: write persist.path immediately (version, agent_id, public_key, private_key; also handle, friendly_name, role_description, human_description; chmod 0600; echo agent_id > ~/.conduit/active). After auth/update: merge those labels into the existing file; never overwrite private_key. - Then agent_update with default_destination including postcode before supply_search. Optional friendly_name / human_description / role_description / avatar only if the human stated them — never invent; they do not block search. Omit avatar and the server assigns a random invader+gradient. Do not store avatar in the credentials file. - Auth: load private_key from the chosen file, call agent_authenticate(agent_id) → sign nonce → agent_authenticate(agent_id, nonce, signature). Keep session_token in memory; do not re-read keys on later tools. session_token (required): - agent_id is a PUBLIC identifier and authorizes nothing on its own. Any call passing agent_id must also pass session_token. - Get one from agent_create (returned immediately — no extra round trip) or from agent_authenticate step 2. It lasts 1 hour. - Pass session_token on EVERY tool call that includes agent_id. Keep it in memory; it does not belong in the credentials file (the private_key does). - auth_required / session_expired / session_invalid → re-run agent_authenticate(agent_id) → sign the nonce → agent_authenticate(agent_id, nonce, signature) → use the new session_token. Follow the next field on the error. - To browse without identity, omit agent_id entirely: supply_search still works, just without mandate-aware badges or your saved destination. - Never send a session_token to a merchant, put it in a URL, or share it between agents. - agent_organization reads linked org and members (or org_not_linked). Org linking ships with the dashboard — do not invent join_org. - agent_notify emails Hub users in that org (to=all or a member user_id / role / email). Never addresses outside the org. Channel is email. - agent_outreach emails outside addresses (suppliers, carriers). to is a string email, { email }, or { emails } (max 5). Linked agents set Reply-To to an org member (default OWNER). No action buttons. Requires the outreach permission (off for new agents until a human enables it in Hub). - permissions on the profile: browse, orders, checkout, notify, outreach. New agents get all except outreach. Hub is the only writer — agent_create / agent_update do not accept permissions. permission_denied (not auth_required) means ask a human in Hub Agent settings; there is no next tool. - Destination: agent default_destination wins; else linked org default address. - No filesystem fallback only: do NOT invent a new profile or signing script. (1) cat ~/.conduit/active 2>/dev/null || list handle/name/role/agent_id from ~/.conduit/*.credentials.json (2) agent_authenticate(agent_id) → forward response.terminal verbatim (3) paste JSON back. - order_list(agent_id) returns { orders }; optional status or open_only=true. Use order_id with order_track / order_update_status. Decision fields: - Prefer offer badge + action (and top-level recommended). Ignore merchant autonomy fields. - supply_search returns live REAL merchants only by default; pass include_sandbox=true only when testing Conduit flows (DEMO/SANDBOX appear last with test_offer=true). - payable_now → order_execute (needs active AP2 mandate) - needs_mandate → payment_mandate(action=request); human opens approval_url as returned - handoff → order_execute then open continue_url (Conduit /handoff/{org_slug}/{order_id}; it records the open then redirects to the merchant) - enable_rail_to_buy → payment_methods(action=enable) - discovery_only / coming_soon → skip; pick another offer Delivery / landed cost: - Catalog delivery_options are often empty — that is normal. - To compare shipping: supply_delivery(supply_id, agent_id) — non-committing probe. Prefer over order_execute for comparison. Sequences: - Handoff: agent_create (keep session_token) → persist → agent_update(destination) → payment_methods(list) → supply_search → supply_details → supply_delivery? → order_execute → continue_url → order_track → order_feedback - Autonomous: payment_mandate(request) → human approves → search → payable_now → order_execute → track → feedback - Notify org (linked): agent_organization → agent_notify(to=all|{ user_id }|{ role }|{ email }, title, body) - Outreach (outside): agent_outreach(to=email|{ email }|{ emails }, title, body, optional reply_to) - Degraded handoff: order_update_status with external_checkout_id + handoff_endpoint → order_track - Correlation: carry search_id; use idempotency_key on every order_execute. - If a tool response is unexpected or unrecoverable after following hint/next: agent_report_issue(message, tool, error, kind?, agent_id, search_id/order_id) — AX telemetry only, not order_feedback; does not change reputation. Never invent carrier scans, stock, prices, or approve URLs. Follow hint/next when present. MCP resources (read on demand): conduit://guides/agent-workflows · offer-badges · payment-mandates · order-tracking · report-issue · notify · outreach Claude Chat rejects dots in tool names; Conduit uses underscore namespaces only (agent_create, supply_search, …). Full guide: https://aiconduit.app/agents.md · Connect: https://aiconduit.app/connect