{ "request_id": "1778815336564-d42abeaeb425b", "service": "agent-trust-contract-kit", "checked_at": "2026-05-15T03:22:16.575Z", "base_url": "https://k-work-trust-api.fly.dev", "result": "usable_with_limits", "safe_to_call": "discovery_and_documented_first_call_only_until_auth_and_quota_are_confirmed", "agent_contract_score": 100, "trust_contract_profiles": [ { "id": "agent-trust-contract-kit.discovery.v1", "status": "implemented", "scope": "portable", "purpose": "A small machine-readable profile that lets agents decide whether an API is discoverable, authenticated, quota-aware, and safe to call before parsing domain-specific fields.", "required_public_surfaces": [ "/health", "/.well-known/k-work-trust-agent.json", "/v1/agent/readiness", "/openapi.json", "/skill.md" ], "required_contract_fields": [ "base_url", "auth", "response_contract", "failure_modes", "runtime_contract", "max_payload_size", "recommended_first_call", "safe_test_payloads" ], "caller_decisions_supported": [ "discovery_only", "verify_key", "make_first_safe_call", "retry_after_limit", "abort_invalid_auth", "escalate_for_human_review", "stop_when_payload_exceeds_declared_limit", "continue_local_only_when_source_unavailable" ], "extension_rule": "Portable fields describe how an agent should call and recover. Domain extensions may add business-specific evidence, but must not change the meaning of portable fields." }, { "id": "k-work-trust.kyb-workflow.v1", "status": "implemented", "scope": "domain_extension", "extends": "agent-trust-contract-kit.discovery.v1", "purpose": "Korean vendor, invoice, payment, CRM, ecommerce, agent-action, technical-due-diligence, advanced technical-assurance, and Agent Trust Compiler gates layered on top of the portable agent discovery contract.", "domain_evidence_fields": [ "normalized_record", "official_business_status", "official_address", "official_ftc_ecommerce_registration", "official_dart_disclosures", "official_opensanctions_screening", "official_companies_house_company", "document_cross_check", "technical_due_diligence_ready", "supply_chain_ready", "secret_flow_safe", "contract_drift_safe", "policy_invariants_ready", "fuzzing_ready", "trust_compiler_ready", "open_world_certificate_ready", "safe_use_boundary", "asset_profile", "provenance_profile", "flow_profile", "contract_profile", "policy_profile", "fuzz_profile", "mathematical_model", "action_graph", "temporal_model_check", "risk_bound", "tail_risk", "evidence_quality_ready", "quality_score", "autonomy_budget", "trust_certificate", "assumption_ledger", "open_world_unknowns", "monitors", "counterexamples", "human_review_packet" ], "compatibility_rule": "Agents that do not understand this domain profile can still use the portable discovery profile to stop, retry, or escalate safely." } ], "runtime_contract": { "schema_version": "agent-runtime-contract/v1", "errors_endpoint": "https://k-work-trust-api.fly.dev/v1/agent/runtime/errors", "max_payload_size": { "request_body_bytes": 1000000, "response_body_bytes": 1000000, "tool_result_bytes": 1000000, "agent_trust_fetch_bytes": 200000, "unit": "bytes" }, "payload_size_policy": "Before the first mutating or high-volume call, compare expected request, response, and tool-result size against max_payload_size. If the payload may exceed the ceiling, request a smaller projection/page, use a narrower endpoint, or abort and escalate with request_id.", "http_status_routing": { "401": "abort_and_verify_key", "403": "abort_or_correct_policy_violation", "410": "remove_capability_until_manifest_refresh", "422": "correct_input_before_retry", "429": "backoff_or_stop_until_quota_reset", "500": "escalate_with_request_id", "503": "retry_with_backoff_then_escalate" }, "required_public_error_fields": [ "request_id", "error.code", "error.message", "error.failure_mode", "error.retry", "error.agent_next_action", "error.escalation" ], "failure_modes": [ { "code": "UNAUTHORIZED", "applies_to": [ "authenticated_api", "whoami" ], "http_status": 401, "category": "auth_failure", "retry": "do_not_retry_same_key", "agent_next_action": "Abort the protected call, verify the key with /v1/auth/whoami, and obtain a valid key through self-serve signup or the operator.", "escalation": "human_or_operator_if_the_agent_expected_this_key_to_be_active", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "RATE_LIMITED", "applies_to": [ "authenticated_api", "signup" ], "http_status": 429, "category": "temporary_limit", "retry": "retry_after_retry_after_seconds", "agent_next_action": "Wait for retry_after_seconds before retrying. If the workflow is urgent or repeated rate limits occur, escalate instead of looping.", "escalation": "human_review_or_alternative_route_for_time_sensitive_workflows", "safe_to_log": [ "request_id", "error.code", "retry_after_seconds" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "QUOTA_EXCEEDED", "applies_to": [ "authenticated_api" ], "http_status": 429, "category": "quota_exhausted", "retry": "do_not_retry_until_resets_at", "agent_next_action": "Stop automated calls for this key until resets_at or ask an operator for review. Do not request a manual key in public channels.", "escalation": "operator_review_required_for_quota_change", "safe_to_log": [ "request_id", "error.code", "quota.limit", "quota.used", "quota.resets_at" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "VALIDATION_BLOCKED", "applies_to": [ "workflow_response" ], "http_status": 200, "category": "business_rule_block", "retry": "retry_only_after_correcting_input", "agent_next_action": "Do not proceed with the workflow action. Preserve blocking_issues and evidence, then collect corrected fields or ask a human reviewer.", "escalation": "human_review_if_the_record_is_business_critical", "safe_to_log": [ "request_id", "status", "decision", "blocking_issues", "warnings" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "MANUAL_REVIEW", "applies_to": [ "workflow_response" ], "http_status": 200, "category": "needs_human_judgment", "retry": "do_not_auto_retry_without_new_information", "agent_next_action": "Route the normalized record, warnings, and evidence to a human reviewer before creating or updating downstream records.", "escalation": "human_review_required_before_downstream_write", "safe_to_log": [ "request_id", "status", "decision", "warnings", "evidence" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "SOURCE_UNAVAILABLE", "applies_to": [ "workflow_response", "official_sources" ], "http_status": 200, "category": "external_source_unavailable", "retry": "retry_later_or_continue_local_only_if_policy_allows", "agent_next_action": "Use local validation only when acceptable. If official-source evidence is required, pause the workflow and escalate with request_id and evidence.", "escalation": "human_or_operator_if_official_source_evidence_is_required", "safe_to_log": [ "request_id", "external_status", "warnings", "evidence" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "PROOF_OF_WORK_FAILED", "applies_to": [ "signup" ], "http_status": 403, "category": "signup_challenge_failure", "retry": "request_fresh_challenge_and_solve_contract", "agent_next_action": "Request a fresh challenge, solve sha256(nonce + ':' + subject + ':' + solution), and avoid repeated blind retries.", "escalation": "only_if_repeated_failures_indicate_onboarding_blocker", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "SIGNUP_RATE_LIMITED", "applies_to": [ "signup" ], "http_status": 429, "category": "signup_limit", "retry": "wait_before_requesting_another_challenge_or_mutation", "agent_next_action": "Wait before continuing signup. Do not ask for a pasted plaintext key; use the self-serve flow after the limit resets.", "escalation": "operator_review_only_for_repeated_legitimate_tester_blockers", "safe_to_log": [ "request_id", "error.code" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] }, { "code": "ABUSE_GUARD_BLOCKED", "applies_to": [ "authenticated_api", "workflow_request" ], "http_status": 403, "category": "misuse_or_sensitive_input_guard", "retry": "do_not_retry_same_payload", "agent_next_action": "Stop the request. Remove secrets, sensitive personal identifiers, bulk records, or enumeration-like input before retrying with one synthetic or authorized business record.", "escalation": "operator_review_if_the_agent_believes_the_block_is_false_positive", "safe_to_log": [ "request_id", "error.code", "abuse.reason" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets", "personal_identifiers" ] }, { "code": "CAPABILITY_REMOVED", "applies_to": [ "discovery", "agent_routing", "authenticated_api" ], "http_status": 410, "category": "capability_no_longer_available", "retry": "remove_capability_until_manifest_refresh", "agent_next_action": "Remove this capability from the routing cache, refresh the manifest/readiness/runtime contract, and do not call the removed path again unless a newer contract advertises it.", "escalation": "human_or_operator_if_a_live_workflow_depends_on_the_removed_capability", "safe_to_log": [ "request_id", "error.code", "path", "replacement_endpoint" ], "do_not_log": [ "plaintext_api_key", "private_records", "secrets" ] } ] }, "first_safe_call": { "method": "POST", "path": "/v1/vendor-onboarding/validate", "description": "Use before an agent registers a Korean vendor or customer, updates CRM, prepares invoice data, or touches ecommerce business records.", "body_example": { "company_name": "Test Company", "registration_number": "1234567891", "phone_number": "01012345678" }, "response_contract": { "profile_id": "agent-trust-contract-kit.discovery.v1", "success_fields": [ "request_id", "tool", "result.status", "result.decision", "result.blocking_issues", "result.warnings", "result.evidence", "result.agent_next_action" ], "decision_meanings": { "register_vendor": "Proceed only with normalized_record and retained evidence.", "request_human_review": "Pause downstream writes and route warnings/evidence to a human reviewer.", "do_not_proceed": "Abort downstream workflow until blocking_issues are corrected." }, "failure_mode_field": "failure_modes", "runtime_contract_field": "runtime_contract", "escalation_contract": "Use failure_modes to choose retry, abort, or human/operator escalation without guessing from HTTP status alone.", "portable_fields": [ "request_id", "status", "decision", "warnings", "blocking_issues", "evidence", "agent_next_action", "failure_modes" ], "domain_extensions": [ "normalized_record", "official_business_status", "official_address", "official_ftc_ecommerce_registration", "official_dart_disclosures", "official_opensanctions_screening", "human_review_packet" ] } }, "missing": [], "risks": [], "recommended_next_action": "Use the first safe call, then require a low-quota key before any mutation, paid, or sensitive-data workflow.", "checks": [ { "name": "health_endpoint", "passed": true, "detail": "status=200", "recommendation": "Expose a fast GET /health endpoint." }, { "name": "agent_manifest", "passed": true, "detail": "status=200", "recommendation": "Publish a machine-readable agent manifest." }, { "name": "manifest_links", "passed": true, "detail": "readiness/openapi/skill/mcp links checked", "recommendation": "Link readiness, OpenAPI, skill, and MCP endpoints from the manifest." }, { "name": "readiness_contract", "passed": true, "detail": "status=200", "recommendation": "Publish a readiness endpoint with a machine-readable status." }, { "name": "openapi_contract", "passed": true, "detail": "status=200", "recommendation": "Publish OpenAPI with paths, schemas, auth, and error responses." }, { "name": "skill_instructions", "passed": true, "detail": "status=200; bytes=20056", "recommendation": "Publish skill.md instructions that an agent can follow without a human inbox." }, { "name": "failure_modes", "passed": true, "detail": "count=10", "recommendation": "Document failure modes with retry and escalation behavior." }, { "name": "response_contract", "passed": true, "detail": "present", "recommendation": "Document success fields, decisions, and escalation semantics." }, { "name": "runtime_limits", "passed": true, "detail": "runtime contract present", "recommendation": "Publish max payload-size limits and HTTP status routing so agents know when to retry, abort, or escalate." }, { "name": "trust_contract_profile", "passed": true, "detail": "profiles=agent-trust-contract-kit.discovery.v1,k-work-trust.kyb-workflow.v1", "recommendation": "Publish a portable trust contract profile so agents can separate universal call/recovery semantics from domain-specific fields." }, { "name": "auth_and_onboarding", "passed": true, "detail": "auth/signup surface checked", "recommendation": "Publish auth, key handling, quota, and low-risk onboarding guidance." }, { "name": "first_safe_call", "passed": true, "detail": "POST /v1/vendor-onboarding/validate", "recommendation": "Name the first non-mutating or low-risk call an agent should make." } ], "evidence": { "health": { "path": "/health", "source": "self_sample", "status": 200, "ok": true, "content_type": "application/json", "error": null, "redirected": false }, "manifest": { "path": "/.well-known/service.json", "source": "self_sample", "status": 200, "ok": true, "content_type": "application/json", "error": null, "redirected": false }, "readiness": { "path": "/v1/agent/readiness", "source": "self_sample", "status": 200, "ok": true, "content_type": "application/json", "error": null, "redirected": false }, "openapi": { "path": "/openapi.json", "source": "self_sample", "status": 200, "ok": true, "content_type": "application/json", "error": null, "redirected": false }, "runtime_errors": { "path": "/v1/agent/runtime/errors", "source": "self_sample", "status": 200, "ok": true, "content_type": "application/json", "error": null, "redirected": false }, "skill": { "path": "/skill.md", "source": "self_sample", "status": 200, "ok": true, "content_type": "text/markdown; charset=utf-8", "error": null, "redirected": false } }, "sample": true, "sample_target": "k-work-trust-self", "sample_note": "This public sample scores K-Work Trust's own discovery contract. POST /v1/agent-trust/check is the authenticated scanner for arbitrary public API base URLs." }