{ "schema": "agentx-site-agent-install-guide-v0.1", "audience": "website_owner_agent", "service": "https://xagent.id", "target": "https://example.com", "host": "example.com", "endpoints": { "capabilities": "https://xagent.id/api/agent/capabilities", "install_guide": "https://xagent.id/api/site_agents/install_guide", "register": "https://xagent.id/api/site_agents/register", "verify_domain": "https://xagent.id/api/site_agents/verify_domain", "install_status": "https://xagent.id/api/site_agents/install_status", "actions": "https://xagent.id/api/site_agents/actions", "private_call": "https://xagent.id/api/site_agents/call", "sdk_event": "https://xagent.id/api/agent/sdk_event", "public_sdk": "https://xagent.id/templates/aeo-site-sdk.js", "agent_card": "https://xagent.id/.well-known/agent-card.json", "openapi": "https://xagent.id/agent/openapi.json", "managed_subscription": "https://xagent.id/api/site_agents/v1/managed/subscription", "managed_runs": "https://xagent.id/api/site_agents/v1/managed/runs", "tasks": "https://xagent.id/api/site_agents/v1/tasks", "task_comparison": "https://xagent.id/api/site_agents/v1/tasks/{task_id}/comparison", "dashboard": "https://xagent.id/dashboard", "dashboard_pairing": "https://xagent.id/api/site_agents/v1/dashboard/pairings", "dashboard_history": "https://xagent.id/api/dashboard/history", "dashboard_export": "https://xagent.id/api/dashboard/export" }, "verification_methods": [ { "id": "dns_txt", "proof_strength": "high", "owner_action": "Publish the challenge token as a DNS TXT record for the verified host.", "best_for": [ "enterprise_domain", "cdn_or_dns_admin_available" ] }, { "id": "well_known_json", "proof_strength": "high", "owner_action": "Publish the challenge JSON under the website's .well-known path.", "best_for": [ "website_backend", "static_site", "cms_file_access" ] }, { "id": "html_meta", "proof_strength": "medium", "owner_action": "Place the challenge token in the homepage metadata.", "best_for": [ "cms_only_access", "temporary_verification" ] } ], "secret_policy": { "server_side_only": true, "public_files_must_not_contain_private_secret": true, "browser_bundles_must_not_contain_private_secret": true, "allowed_storage": [ "backend_secret_store", "cms_connector_secret", "worker_secret", "website_agent_runtime_secret" ] }, "cli_installer": { "release": { "package": "@twin3-ai/agent-id", "version": "0.3.19", "integrity": "sha512-+zSORpYlXaVLGlmKJNGNgK8jcNI7ztOt4Ppjm+6UdLiiT6/xfQ0bYs+5harI7J4iK+yXovJhHE6jwpaNBfE06g==", "ready": true, "api_origin": "https://xagent.id", "commit": "1322c73c43fd9927971fb6f16c015ca4156a5250", "published_at": "2026-08-15T06:15:30.443Z", "manifest": "https://xagent.id/.well-known/agent-id-release.json", "manifest_hash": "sha256:b0e91a5d168c152f70c3a81f4f98949af820fe35b1888ddaf2263a46748b3f76", "compatibility": { "node": ">=20", "npm": ">=10" }, "rollback": { "package": "@twin3-ai/agent-id", "version": "0.3.18", "integrity": "sha512-+fe8zVvHQfF1e6Fen/WDsuR8iyKrlSU5AUd1YbV/Xrgk4jPgfilsjDtvhPcRvjklZm+stOyBDeqleCFdTxpWyA==", "source": "previous_production_release" } }, "package": "@twin3-ai/agent-id", "publication_status": "public_npm_0.3.19", "model": "one_package_with_five_selectable_modules", "modules": { "identity": { "permission": "identity_publish", "required": true }, "audit": { "permission": "public_read", "required": false }, "measurement": { "permission": "telemetry_submit", "required": false }, "optimization": { "permission": "insights_read", "required": false }, "automation": { "permission": "ai_files_write", "required": false, "default": false } }, "dry_run": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id install --modules identity,audit,optimization --grant identity_publish,public_read,insights_read --project-root ", "apply": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id install --modules identity,audit,optimization --grant identity_publish,public_read,insights_read --project-root --apply", "resume": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id install-resume --project-root ", "uninstall": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id install-uninstall --project-root --approve", "apply_side_effect": "write_only_agent_id_namespace", "does_not_issue_key_before_domain_verification": true }, "enterprise_installation": { "package_status": "public_npm_0.3.19", "target_status": "ready", "key_ownership": "customer_side_only", "local_policy_default": "deny_all", "verified_host": "example.com", "domain_proof": { "create_challenge_endpoint": "https://xagent.id/api/site_agents/v1/challenges", "verify_challenge_endpoint": "https://xagent.id/api/site_agents/v1/challenges/verify", "challenge_lifetime_seconds": 86400, "single_use": true, "verification_authority": "private_one_time_capability", "verify_request_requires": [ "challenge_id", "verification_capability" ], "server_capability_storage": "domain_separated_digest_only", "customer_capability_storage": "encrypted_at_rest_bound_to_site_private_key", "exact_host_required": true, "method": "well_known", "public_proof_url": "https://example.com/.well-known/agent-id.json", "expected_http_status": 200 }, "token_exchange": { "create_challenge_endpoint": "https://xagent.id/api/site_agents/v1/token/challenge", "exchange_endpoint": "https://xagent.id/api/site_agents/v1/token", "access_token_lifetime_seconds": 900, "access_token_storage": "memory_only" }, "customer_cli_flow": [ { "id": "enroll", "command": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id enterprise-enroll https://example.com --environment production --method well_known --project-root ", "actor": "customer_agent", "side_effect": "create_customer_owned_identity_and_request_domain_challenge" }, { "id": "preview_domain_proof", "command": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id enterprise-domain-proof --project-root --public-root ", "actor": "customer_agent", "side_effect": "none_dry_run_only" }, { "id": "publish_domain_proof", "command": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id enterprise-domain-proof --project-root --public-root --apply", "actor": "customer_agent", "side_effect": "write_only_well_known_agent_id_json" }, { "id": "verify_domain_proof", "command": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id enterprise-domain-verify --project-root ", "actor": "customer_agent", "side_effect": "request_independent_public_refetch_and_store_customer_credential" }, { "id": "publish_durable_identity", "command": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id enterprise-identity-publish --project-root --public-root --apply", "actor": "customer_agent", "side_effect": "replace_short_lived_challenge_with_customer_signed_public_identity" }, { "id": "initialize_policy", "command": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id enterprise-policy-init --project-root ", "actor": "customer_agent", "side_effect": "create_local_deny_all_policy" }, { "id": "propose_bounded_task", "command": "npm exec --yes --package=@twin3-ai/agent-id@0.3.19 -- agent-id enterprise-task-propose --project-root --idempotency-key ", "actor": "customer_agent", "side_effect": "issue_signed_draft_after_public_baseline_and_allowlist_validation" } ], "customer_secret_storage": { "local_paths": [ ".agent-id/secrets/enterprise-ed25519.pem", ".agent-id/secrets/enterprise-credential.json" ], "runtime_files": [ { "path": ".agent-id/secrets/enterprise-ed25519.pem", "role": "sign_token_challenge" }, { "path": ".agent-id/secrets/enterprise-credential.json", "role": "exchange_scoped_access_token" } ], "file_mode": "0600", "git_ignored": true, "secret_never_printed_to_stdout": true, "production_destination": "customer_secret_manager_with_read_only_runtime_mount", "mother_service_receives_private_key": false }, "credential_delivery_recovery": { "existing_credential_action": "validate_with_mother_service_then_resume_local_state", "missing_credential_action": "request_new_domain_challenge", "missing_credential_command": "agent-id enterprise-enroll https://example.com --environment production --method well_known --project-root ", "orphaned_server_credential_has_no_recoverable_customer_secret": true, "recovery_never_returns_previous_bootstrap_secret": true }, "managed_inspection": { "schema": "agentx-managed-inspection-installation-v1", "status": "production_deployed", "requires": [ "verified_domain", "signed_enterprise_credential" ], "cadence": "monthly", "execution_owner": "agent_id_mother_service", "scheduler_auth": "google_service_account_oidc", "access": "public_read_only", "mutation_authority": "none", "requires_customer_repository_access": false, "requires_customer_deployment_credentials": false, "can_modify_customer_site": false, "commands": { "enable": "agent-id enterprise-managed-enable --project-root ", "status": "agent-id enterprise-managed-status --project-root ", "pause": "agent-id enterprise-managed-pause --project-root ", "resume": "agent-id enterprise-managed-resume --project-root ", "runs": "agent-id enterprise-managed-runs --project-root --limit 20" }, "evidence": [ "public_homepage_and_sampled_pages", "public_robots_txt", "public_sitemap_xml", "public_llms_txt", "public_agent_card", "public_aeo_agent_descriptor" ], "private_connectors_required_for": [ "gsc_or_bing_search_performance", "private_cdn_ai_crawler_logs", "crm_lead_or_order_attribution" ], "retention_seconds": 34214400, "non_claims": [ "public_inspection_does_not_prove_ai_citation_or_ranking", "public_inspection_does_not_prove_conversion_causality", "managed_runner_does_not_modify_or_deploy_customer_site" ] }, "task_proposal": { "schema": "agentx-enterprise-task-v1", "endpoint": "https://xagent.id/api/site_agents/v1/tasks", "method": "POST", "required_scope": "tasks:execute", "required_fields": [ "path", "content", "policy_digest", "idempotency_key" ], "auto_managed_paths": [ "llms.txt", ".well-known/agent-card.json", ".well-known/agent-id.json", ".well-known/aeo-agent.json", ".well-known/agent-knowledge.json" ], "review_only_paths": [ "robots.txt" ], "baseline": "mother_service_fetches_the_exact_public_path_and_binds_expected_hash_before_signing", "customer_authority": "local_policy_default_deny_and_customer_approval_required", "non_claims": [ "task_issuance_is_not_site_execution", "site_receipt_and_public_refetch_required" ] }, "responsibility_boundary": { "customer_agent": [ "generate_and_keep_private_key", "publish_public_domain_proof", "move_runtime_credential_to_customer_secret_manager", "approve_bounded_policy_rules", "deploy_or_rollback_customer_changes" ], "mother_service": [ "issue_single_use_domain_challenge", "independently_refetch_public_proof", "verify_exact_host_environment_agent_id_and_public_key", "issue_scoped_short_lived_access_token", "retain_public_verification_receipt_without_private_key" ], "mother_service_has_source_access": false, "mother_service_has_deployment_credentials": false, "mother_service_can_widen_customer_policy": false }, "steps": [ "read_public_contract", "install_published_release", "create_customer_owned_identity", "prove_domain_control", "credential_exchange", "initialize_deny_all_policy", "connect_customer_selected_adapter", "receive_signed_task", "approve_bounded_change", "submit_signed_site_receipt", "independent_public_verification", "rollback_or_remove" ], "tenant_zero_gate": { "target": "https://twin3.ai", "status": "external_evidence_required", "live_domain_proof_verified": false, "live_mutation_verified": false, "failure_receipts_verified": false, "second_stack_verified": false }, "non_claims": [ "public_npm_release_is_not_google_marketplace_approval", "local_tests_are_not_live_customer_evidence", "control_plane_cannot_widen_customer_policy" ] }, "runtime_contract": { "state_machine": [ "active", "paused", "disconnected", "revoked" ], "metadata": [ "runtime_version", "capabilities", "cursor" ], "local_controls": [ "--pause", "--resume", "--disconnect", "--revoke", "--status" ], "incompatible_work_is_blocked": true }, "repository_connector": { "schema": "agentx-repository-patch-plan-v1", "mode": "local_reviewable_patch", "allowed_paths": [ "llms.txt", "robots.txt", ".well-known/agent-card.json", ".well-known/agent-id.json", ".well-known/aeo-agent.json", ".well-known/agent-knowledge.json" ], "requires_explicit_approval": true, "produces": [ "diff", "before_after_hashes", "rollback_receipt", "post_write_verification" ], "never_modifies": [ "package.json", "secrets", "pricing", "legal", "checkout", "database", "default_branch" ] }, "sdk_examples": { "contentWorkflow": { "helper": "createSiteAgentClient().contentWorkflow", "purpose": "Generate the Agent-readable C4 content workflow package for one page: diagnosis, answer-first rewrite, schema guidance, citation gaps, community plan, 30-day plan, and prompt-test sheet.", "request_schema": { "required": [ "url" ], "optional": [ "audit_url", "questions", "competitors", "engines", "content", "market", "cadence" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "audit_url": true, "questions": [ "best supplier for export buyers" ], "competitors": [ "CompetitorCo" ], "engines": [ "ChatGPT", "Gemini", "Claude" ] }, "response_schema": { "fields": [ "ok", "action", "package", "steps" ], "schemas": { "package": "agentx-c4-content-workflow-package-v0.1", "content_plan": "agentx-c1-content-optimization-plan-v0.1", "prompt_sheet": "agentx-c2-prompt-test-run-sheet-v0.1" } }, "claim_boundary": "generated_content_workflow_not_ai_citation_claim" }, "contentWorkflowReview": { "helper": "createSiteAgentClient().contentWorkflowReview", "purpose": "Review a generated Content Pack or C4 workflow package before publication, checking completeness, evidence boundaries, and fabricated-claim risk.", "request_schema": { "required": [ "content_pack" ], "optional": [ "audit", "strict" ], "secret_source": "no_private_secret_required" }, "example_request": { "content_pack": { "schema": "agentx-content-optimization-pack-v0.1" } }, "response_schema": { "fields": [ "ok", "review" ], "schemas": { "review": "agentx-c5-content-workflow-review-v0.1" } }, "claim_boundary": "review_evidence_boundaries_only_not_real_ai_visibility_proof" }, "contentPublication": { "helper": "createSiteAgentClient().contentPublication", "purpose": "Report which C4 content workflow outputs were published, with proof URLs and optional strict proof verification.", "request_schema": { "required": [ "url" ], "optional": [ "content_workflow_package", "published_items", "items", "evidence", "verify_publication" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "published_items": [], "verify_publication": false }, "response_schema": { "fields": [ "ok", "action", "package", "steps" ], "schemas": { "package": "agentx-m8-content-publication-evidence-package-v0.1" } }, "claim_boundary": "publication_evidence_only_not_ai_visibility_proof" }, "promptTestCycle": { "helper": "createSiteAgentClient().promptTestCycle", "purpose": "Create a fixed C2 prompt-test sheet, then import completed C3 rows only when real AI answer results are supplied.", "request_schema": { "required": [ "url" ], "optional": [ "questions", "topics", "engines", "competitors", "market", "cadence", "rows", "results", "completed_rows" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "questions": [ "best supplier for export buyers" ], "engines": [ "ChatGPT", "Gemini", "Claude" ], "rows": [] }, "response_schema": { "fields": [ "ok", "schema", "action", "sheet", "import_result", "steps" ], "schemas": { "cycle": "agentx-site-agent-prompt-test-cycle-v0.1", "sheet": "agentx-c2-prompt-test-run-sheet-v0.1", "import_result": "agentx-c3-prompt-test-results-import-v0.1" } }, "claim_boundary": "manual_import_required_for_ai_visibility_claims" }, "siteEvents": { "helper": "createSiteAgentClient().siteEvents", "purpose": "Upload authenticated connector-observed page signals from a verified backend, CMS connector, Worker, or website Agent runtime.", "request_schema": { "required": [ "url" ], "optional": [ "events", "sdk_events", "event", "path", "signals", "source" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "events": [ { "path": "/rfq", "event": "page_signal", "signals": { "h1_count": 1, "jsonld_count": 1 } } ] }, "response_schema": { "fields": [ "ok", "action", "stored", "import", "steps" ], "schemas": { "import": "agentx-site-agent-events-import-v0.1" } }, "claim_boundary": "connector_observed_page_signal_not_ai_read_citation_or_conversion_proof" }, "siteSignalPackage": { "helper": "createSiteAgentClient().siteSignalPackage", "purpose": "Return a reviewable S1 evidence package from observed SDK or connector page-structure signals.", "request_schema": { "required": [ "url" ], "optional": [ "events", "sdk_events", "period", "source" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "period": { "from": "2026-07-01", "to": "2026-07-31" } }, "response_schema": { "fields": [ "ok", "action", "package", "steps" ], "schemas": { "package": "agentx-s1-site-signal-evidence-package-v0.1" } }, "claim_boundary": "site_signal_evidence_only_not_ai_read_citation_conversion_or_ranking_proof" }, "aiReads": { "helper": "createSiteAgentClient().aiReads", "purpose": "Upload observed A1 AI crawler read rows from Cloudflare, CDN, nginx, server logs, or a verified backend collector.", "request_schema": { "required": [ "url" ], "optional": [ "logs", "events", "user_agent", "status", "path", "bytes", "source" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "logs": [ { "user_agent": "GPTBot/1.0", "status": 200, "path": "/products" } ] }, "response_schema": { "fields": [ "ok", "action", "stored", "import", "steps" ], "schemas": { "import": "agentx-a1-ai-read-import-v0.1" } }, "claim_boundary": "observed_server_log_only_not_ai_citation_or_conversion_proof" }, "conversions": { "helper": "createSiteAgentClient().conversions", "purpose": "Upload observed B1 lead, RFQ, order, CRM, or survey conversion events after domain verification.", "request_schema": { "required": [ "url" ], "optional": [ "conversions", "events", "event", "referrer", "survey_source", "value", "currency", "source" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "conversions": [ { "event": "lead", "referrer": "https://chatgpt.com/c/example", "value": 100, "currency": "USD" } ] }, "response_schema": { "fields": [ "ok", "action", "stored", "import", "steps" ], "schemas": { "import": "agentx-b1-conversion-import-v0.1" } }, "claim_boundary": "observed_conversion_event_not_incrementality_proof" }, "a1ReadPackage": { "helper": "createSiteAgentClient().a1ReadPackage", "purpose": "Return a reviewable A1 evidence package from the verified website's observed AI crawler log rows.", "request_schema": { "required": [ "url" ], "optional": [ "logs", "events", "period", "source" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "period": { "from": "2026-07-01", "to": "2026-07-31" } }, "response_schema": { "fields": [ "ok", "action", "package", "steps" ], "schemas": { "package": "agentx-a1-ai-read-evidence-package-v0.1" } }, "claim_boundary": "reviewable_evidence_package_not_new_ai_citation_or_conversion_proof" }, "b1ConversionPackage": { "helper": "createSiteAgentClient().b1ConversionPackage", "purpose": "Return a reviewable B1 evidence package from observed lead, RFQ, order, CRM, or survey conversion events.", "request_schema": { "required": [ "url" ], "optional": [ "conversions", "events", "period", "source" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "period": { "from": "2026-07-01", "to": "2026-07-31" } }, "response_schema": { "fields": [ "ok", "action", "package", "steps" ], "schemas": { "package": "agentx-b1-conversion-evidence-package-v0.1" } }, "claim_boundary": "reviewable_evidence_package_not_incrementality_proof" }, "outcomeReport": { "helper": "createSiteAgentClient().outcomeReport", "purpose": "Return the M1 outcome report that combines observed G1/G2, A1, A2, B1, SDK, and job evidence.", "request_schema": { "required": [ "url" ], "optional": [ "a2_citation_package", "ai_citation_package", "ai_reads", "ai_citations", "conversions", "google_reports", "jobs", "events" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "a2_citation_package": {} }, "response_schema": { "fields": [ "ok", "action", "report", "steps" ], "schemas": { "report": "agentx-m1-outcome-report-v0.1" } }, "claim_boundary": "observed_evidence_not_causality_claim" }, "outcomePackage": { "helper": "createSiteAgentClient().outcomePackage", "purpose": "Return the M1 outcome evidence package with reviewable files, claim limits, and next actions.", "request_schema": { "required": [ "url" ], "optional": [ "period", "a2_citation_package", "ai_citation_package", "ai_reads", "ai_citations", "conversions", "google_reports", "jobs", "events" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "period": { "from": "2026-07-01", "to": "2026-07-31" } }, "response_schema": { "fields": [ "ok", "action", "package", "steps" ], "schemas": { "package": "agentx-m1-outcome-evidence-package-v0.1" } }, "claim_boundary": "observed_evidence_not_causality_claim" }, "outcomeReview": { "helper": "createSiteAgentClient().outcomeReview", "purpose": "Run the M1 outcome report and M1 outcome evidence package in one server-side SDK call sequence.", "sequence": [ "outcome_report", "m1_outcome_evidence_package" ], "request_schema": { "required": [ "url" ], "optional": [ "period", "a2_citation_package", "ai_citation_package", "ai_reads", "ai_citations", "conversions", "google_reports", "jobs", "events" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "period": { "from": "2026-07-01", "to": "2026-07-31" } }, "response_schema": { "fields": [ "ok", "schema", "action", "report", "package", "steps" ], "schemas": { "cycle": "agentx-site-agent-outcome-review-v0.1", "report": "agentx-m1-outcome-report-v0.1", "package": "agentx-m1-outcome-evidence-package-v0.1" } }, "claim_boundary": "observed_evidence_not_causality_claim" }, "optimizationCycle": { "helper": "createSiteAgentClient().optimizationCycle", "purpose": "Return the read-only O1 continuous optimization cycle: SDK evidence, G3, I1 insights, audit-check job drafts, and M1 context.", "sequence": [ "optimization_cycle" ], "request_schema": { "required": [ "url" ], "optional": [ "audit_url", "audit", "ai_reads", "ai_citations", "conversions", "google_reports", "jobs", "events", "currency" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "audit_url": true }, "response_schema": { "fields": [ "ok", "action", "cycle", "steps" ], "schemas": { "cycle": "agentx-o1-continuous-optimization-cycle-v0.1" } }, "claim_boundary": "read_only_optimization_plan_not_site_mutation" }, "jobDrafts": { "helper": "createSiteAgentClient().jobDrafts", "purpose": "Convert evidence-backed I1 optimization insights, audit checks, or C5 review_gate repair items into scoped AEO job drafts for the verified host.", "sequence": [ "job_drafts" ], "request_schema": { "required": [ "url" ], "optional": [ "insights", "review_gate", "audit", "ai_reads", "ai_citations", "conversions", "google_reports", "provider", "evaluator", "currency" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "currency": "USD" }, "response_schema": { "fields": [ "ok", "action", "drafts", "steps" ], "schemas": { "drafts": "agentx-i1-job-drafts-v0.1, agentx-aeo-job-drafts-v0.1, or agentx-c5-repair-job-drafts-v0.1" } }, "claim_boundary": "drafts_only_not_started_work" }, "acceptJobDraft": { "helper": "createSiteAgentClient().acceptJobDraft", "purpose": "Accept one explicit job draft into the verified website Agent's AEO job ledger.", "sequence": [ "accept_job_draft" ], "request_schema": { "required": [ "url", "draft" ], "optional": [ "provider", "evaluator", "currency", "budget" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "draft": { "draft_id": "draft_from_jobDrafts" } }, "response_schema": { "fields": [ "ok", "action", "job", "steps" ], "schemas": { "job": "agentx-aeo-job-v0.1" } }, "claim_boundary": "explicit_owner_or_agent_confirmation_required" }, "decideJobDraft": { "helper": "createSiteAgentClient().decideJobDraft", "purpose": "Record accept, defer, or reject for one explicit job draft. Defer and reject create a decision receipt only.", "sequence": [ "decide_job_draft" ], "request_schema": { "required": [ "url", "decision" ], "optional": [ "draft", "draft_id", "reason", "provider", "evaluator", "currency", "budget" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "decision": "defer", "draft": { "draft_id": "draft_from_jobDrafts" }, "reason": "Owner review needed before implementation." }, "response_schema": { "fields": [ "ok", "action", "decision", "job", "steps" ], "schemas": { "decision": "agentx-draft-decision-v0.1", "job": "agentx-aeo-job-v0.1 when decision is accept" } }, "claim_boundary": "decision_receipt_only_not_delivery_or_outcome_proof" }, "draftDecisions": { "helper": "createSiteAgentClient().draftDecisions", "purpose": "List draft decision receipts for the verified website Agent.", "sequence": [ "draft_decisions" ], "request_schema": { "required": [ "url" ], "optional": [ "decision", "draft_id" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com" }, "response_schema": { "fields": [ "ok", "action", "decisions", "steps" ], "schemas": { "decisions": "agentx-draft-decisions-v0.1" } }, "claim_boundary": "decision_history_not_delivery_or_outcome_proof" }, "decisionReviews": { "helper": "createSiteAgentClient().decisionReviews", "purpose": "List owner apply-plan decision review receipts for the verified website Agent.", "sequence": [ "decision_reviews" ], "request_schema": { "required": [ "url" ], "optional": [ "decision", "apply_item_id", "item_id" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com" }, "response_schema": { "fields": [ "ok", "action", "reviews", "steps" ], "schemas": { "reviews": "agentx-owner-decision-reviews-v0.1" } }, "claim_boundary": "decision_review_history_not_delivery_or_outcome_proof" }, "monthlyEvidenceLoop": { "helper": "createSiteAgentClient().monthlyEvidenceLoop", "purpose": "Generate one monthly evidence package for the verified website Agent using a shared Content Pack.", "request_schema": { "required": [ "url" ], "optional": [ "audit_url", "questions", "competitors", "engines", "content", "content_pack", "period" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "audit_url": true, "questions": [ "best supplier for export buyers" ], "engines": [ "ChatGPT", "Gemini", "Claude" ], "period": { "from": "2026-07-01", "to": "2026-07-31" } }, "response_schema": { "fields": [ "ok", "action", "pack", "review", "review_gate", "repair_pack", "repair_job_drafts", "package", "tracker", "scorecard", "dashboard", "delivery_summary", "steps" ], "schemas": { "pack": "agentx-content-optimization-pack-v0.1", "review": "agentx-c5-content-workflow-review-v0.1", "repair_pack": "agentx-c6-content-repair-pack-v0.1 when C5 blocks release or citability findings need advisory repair", "repair_job_drafts": "agentx-c5-repair-job-drafts-v0.1 when C5 blocks release or citability findings need advisory repair", "package": "agentx-m2-monthly-optimization-package-v0.1", "tracker": "agentx-m3-monthly-execution-tracker-v0.1", "scorecard": "agentx-m4-monthly-outcome-scorecard-v0.1", "dashboard": "agentx-m5-monthly-dashboard-v0.1", "delivery_summary": "agentx-monthly-delivery-summary-v0.1 with decision_queue when repair_job_drafts or pending O1 job drafts are present" } }, "claim_boundary": "generated_content_pack_not_ai_citation_claim" }, "applyCycle": { "helper": "createSiteAgentClient().applyCycle", "purpose": "Poll private work, create an apply plan, and optionally report proof for the first or supplied apply item.", "request_schema": { "required": [ "url" ], "optional": [ "audit_url", "feed", "evidence_uri", "proof_url", "pull_request_url", "deployment_reference", "verify_proof" ], "secret_source": "server_side_secret_environment" }, "example_request": { "url": "https://example.com", "audit_url": true, "evidence_uri": "https://example.com/.well-known/apply-proof.json", "verify_proof": true }, "response_schema": { "fields": [ "ok", "schema", "action", "feed", "apply_plan", "evidence_results", "steps" ], "schemas": { "feed": "agentx-m16-site-agent-insights-feed-v0.1", "apply_plan": "agentx-m19-site-agent-apply-plan-v0.1", "cycle": "agentx-site-agent-apply-cycle-v0.1" } }, "claim_boundary": "does_not_apply_changes_without_owner_or_connector" } }, "steps": [ { "id": "read_capabilities", "actor": "website_owner_agent", "endpoint": "https://xagent.id/api/agent/capabilities", "method": "GET", "side_effect": "none", "output": "Understand the service lanes before registration." }, { "id": "register_site_agent", "actor": "website_owner_agent", "endpoint": "https://xagent.id/api/site_agents/register", "method": "POST", "side_effect": "creates_pending_domain_record", "input": { "url": "https://example.com" }, "output": "Domain challenge, public descriptor draft, and pending Agent ID." }, { "id": "publish_domain_proof", "actor": "domain_owner_or_authorized_connector", "method": "owner_action", "accepted_methods": [ "dns_txt", "well_known_json", "html_meta" ], "proof_rule": "The proof must be placed on the same host being registered.", "output": "Public proof that the requester controls the website." }, { "id": "verify_domain_ownership", "actor": "website_owner_agent", "endpoint": "https://xagent.id/api/site_agents/verify_domain", "method": "POST", "side_effect": "issues_domain_bound_private_secret", "output": "Verified Site Agent identity plus a private server-side secret." }, { "id": "install_public_descriptor", "actor": "website_agent_or_connector", "path": "/.well-known/aeo-agent.json", "method": "publish_file", "source": "install_descriptor", "secret_policy": "public_descriptor_only", "output": "Machine-readable website Agent descriptor for external agents." }, { "id": "configure_server_helper", "actor": "website_backend_or_worker", "package": "@twin3-ai/agent-id", "method": "server_side_runtime", "secret_policy": "store_private_secret_only_in_backend_cms_connector_worker_or_agent_runtime", "calls": [ "insightsFeed", "siteEvents", "siteSignalPackage", "contentWorkflow", "contentWorkflowReview", "contentPublication", "promptTestCycle", "aiReads", "conversions", "a1ReadPackage", "b1ConversionPackage", "outcomeReport", "outcomePackage", "outcomeReview", "optimizationCycle", "jobDrafts", "acceptJobDraft", "decideJobDraft", "draftDecisions", "decisionReviews", "contentPack", "monthlyPackage", "monthlyTracker", "monthlyScorecard", "monthlyDashboard", "monthlyEvidenceLoop", "applyPlan", "applyCycle", "applyEvidence" ], "output": "The website Agent can poll private work and report evidence without exposing secrets." }, { "id": "send_sdk_heartbeat", "actor": "public_website_or_server_event_collector", "endpoint": "https://xagent.id/api/agent/sdk_event", "method": "POST", "side_effect": "records_sdk_activity", "output": "Proof Graph can show that the website integration is active." }, { "id": "poll_insights_feed", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "POST", "action": "insights_feed", "requires": [ "verified_domain", "server_side_secret" ], "output": "Current monthly work items, evidence gaps, and verification follow-ups." }, { "id": "run_content_workflow", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().contentWorkflow", "sequence": [ "content_workflow_package" ], "requires": [ "verified_domain", "server_side_secret", "page_or_buyer_questions" ], "claim_boundary": "generated_content_workflow_not_ai_citation_claim", "output": "C4 content deliverable package with C1 rewrite plan, community/citation gaps, 30-day plan, and C2 manual prompt-test sheet." }, { "id": "review_content_workflow", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/agent/content_workflow_review", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().contentWorkflowReview", "sequence": [ "content_workflow_review" ], "requires": [ "generated_content_pack_or_c4_package" ], "claim_boundary": "review_checks_completeness_and_evidence_boundaries_not_real_ai_visibility", "output": "C5 review result with failed checks before publication or reporting." }, { "id": "report_content_publication", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().contentPublication", "sequence": [ "content_publication_package" ], "requires": [ "verified_domain", "server_side_secret", "published_items_or_pending_outputs" ], "claim_boundary": "publication_evidence_only_not_ai_visibility_proof", "output": "M8 publication evidence for C4 outputs, including accepted, rejected, verified, and pending items." }, { "id": "run_prompt_test_cycle", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().promptTestCycle", "sequence": [ "prompt_test_run_sheet", "prompt_test_results" ], "requires": [ "verified_domain", "server_side_secret", "fixed_questions" ], "claim_boundary": "manual_import_required_for_ai_visibility_claims", "output": "C2 fixed prompt-test sheet and optional C3 import of real AI answer rows." }, { "id": "upload_ai_reads", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().aiReads", "sequence": [ "a1_ai_reads" ], "requires": [ "verified_domain", "server_side_secret", "http_or_cdn_logs" ], "claim_boundary": "observed_server_log_only_not_ai_citation_or_conversion_proof", "output": "A1 import summary for observed AI crawler requests from the verified host." }, { "id": "package_site_signals", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().siteSignalPackage", "sequence": [ "site_signal_package" ], "requires": [ "verified_domain", "server_side_secret", "observed_sdk_or_connector_site_signals" ], "claim_boundary": "site_signal_evidence_only_not_ai_read_citation_conversion_or_ranking_proof", "output": "S1 review package with observed page-structure signals, finding rows, recommended fixes, and non-claims." }, { "id": "upload_conversions", "actor": "website_backend_or_crm_connector", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().conversions", "sequence": [ "b1_conversions" ], "requires": [ "verified_domain", "server_side_secret", "lead_rfq_order_crm_or_survey_events" ], "claim_boundary": "observed_conversion_event_not_incrementality_proof", "output": "B1 import summary for AI-attributed lead, RFQ, order, CRM, or survey events." }, { "id": "package_a1_reads", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().a1ReadPackage", "sequence": [ "a1_read_evidence_package" ], "requires": [ "verified_domain", "server_side_secret", "observed_a1_rows_or_stored_a1_data" ], "claim_boundary": "reviewable_evidence_package_not_new_ai_citation_or_conversion_proof", "output": "A1 review package with summary, provider breakdown, samples, failed reads, labels, and non-claims." }, { "id": "package_b1_conversions", "actor": "website_backend_or_crm_connector", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().b1ConversionPackage", "sequence": [ "b1_conversion_evidence_package" ], "requires": [ "verified_domain", "server_side_secret", "observed_b1_rows_or_stored_b1_data" ], "claim_boundary": "reviewable_evidence_package_not_incrementality_proof", "output": "B1 review package with attribution summary, redacted samples, CRM checklist, evidence labels, and non-claims." }, { "id": "run_outcome_review", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().outcomeReview", "sequence": [ "outcome_report", "m1_outcome_evidence_package" ], "requires": [ "verified_domain", "server_side_secret", "observed_measurement_layers_or_package_inputs" ], "claim_boundary": "observed_evidence_not_causality_claim", "output": "M1 outcome report plus M1 outcome evidence package for the same verified website." }, { "id": "run_optimization_cycle", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().optimizationCycle", "sequence": [ "optimization_cycle" ], "requires": [ "verified_domain", "server_side_secret", "observed_evidence_or_audit_inputs" ], "claim_boundary": "read_only_optimization_plan_not_site_mutation", "output": "O1 continuous optimization cycle with SDK evidence, G3, I1 insights, audit-check job drafts, M1 context, and next actions." }, { "id": "draft_optimization_jobs", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().jobDrafts", "sequence": [ "job_drafts" ], "requires": [ "verified_domain", "server_side_secret", "own_i1_insights_audit_checks_or_evidence_inputs" ], "claim_boundary": "drafts_only_not_started_work", "output": "Scoped AEO job drafts for the verified host. These are not active jobs yet." }, { "id": "accept_job_draft", "actor": "website_owner_agent", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().acceptJobDraft", "sequence": [ "accept_job_draft" ], "requires": [ "verified_domain", "server_side_secret", "explicit_owner_or_agent_confirmation", "own_job_draft" ], "claim_boundary": "explicit_owner_or_agent_confirmation_required", "output": "Accepted draft appears in the AEO job ledger for later proof submission and evaluator review." }, { "id": "decide_job_draft", "actor": "website_owner_agent", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().decideJobDraft", "sequence": [ "decide_job_draft" ], "requires": [ "verified_domain", "server_side_secret", "explicit_owner_or_agent_decision", "own_job_draft" ], "claim_boundary": "decision_receipt_only_not_delivery_or_outcome_proof", "output": "Accept, defer, or reject is recorded. Defer and reject do not start implementation work." }, { "id": "list_draft_decisions", "actor": "website_owner_agent", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().draftDecisions", "sequence": [ "draft_decisions" ], "requires": [ "verified_domain", "server_side_secret" ], "claim_boundary": "decision_history_not_delivery_or_outcome_proof", "output": "Decision receipts for the verified host only, with accept/defer/reject counts." }, { "id": "list_decision_reviews", "actor": "website_owner_agent", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().decisionReviews", "sequence": [ "decision_reviews" ], "requires": [ "verified_domain", "server_side_secret" ], "claim_boundary": "decision_review_history_not_delivery_or_outcome_proof", "output": "Owner apply-plan decision review receipts for the verified host only, with accept/defer/reject counts." }, { "id": "run_monthly_evidence_loop", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "server_side_sdk_helper", "helper": "createSiteAgentClient().monthlyEvidenceLoop", "sequence": [ "content_pack", "content_workflow_review", "monthly_package", "monthly_tracker", "monthly_scorecard", "monthly_dashboard" ], "conditional_sequence": [ "content_repair_pack and job_drafts when C5 blocks release or citability findings need advisory repair" ], "requires": [ "verified_domain", "server_side_secret" ], "claim_boundary": "generated_content_pack_not_ai_citation_claim", "output": "One response containing pack, C5 review, optional C6 repair pack, optional repair job drafts, package, tracker, scorecard, and dashboard for the same monthly evidence window." }, { "id": "report_apply_evidence", "actor": "website_backend_or_worker", "endpoint": "https://xagent.id/api/site_agents/call", "method": "POST", "action": "apply_evidence", "requires": [ "verified_domain", "server_side_secret", "apply_item_id" ], "evidence_rule": "proof_url_or_pr_url_required", "output": "AEO job ledger evidence waiting for evaluator acceptance or rejection." } ], "non_claims": [ "installing_the_agent_does_not_grant_us_direct_write_access_to_the_website", "installation_does_not_prove_ai_ranking_or_conversion_lift", "private_actions_require_domain_verification_first" ], "next_public_document": "https://xagent.id/agent/install.md" }