{"uid":"cap_oMjb3pTWya6wuLcIIHzhE","slug":"effectguard-preflight-agent-operation-deduplication-idempotency-check-4bd80fd4","name":"EffectGuard Preflight – Agent Operation Deduplication & Idempotency Check","description":"","url":"https://effectguard-x402-experiment.onrender.com/v1/preflight?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method","bodyType","body"],"properties":{"body":{"type":"object","title":"PreflightRequest","required":["request_id","agent_id","session_id","account_id","tool","arguments"],"properties":{"tool":{"type":"string","title":"Tool","maxLength":128,"minLength":1},"intent":{"type":"string","title":"Intent","default":"","maxLength":2000},"agent_id":{"type":"string","title":"Agent Id","maxLength":128,"minLength":1},"arguments":{"type":"object","title":"Arguments","additionalProperties":{}},"account_id":{"type":"string","title":"Account Id","maxLength":128,"minLength":1},"max_age_ms":{"type":"integer","title":"Max Age Ms","default":30000,"maximum":3600000,"minimum":0},"request_id":{"type":"string","title":"Request Id","maxLength":128,"minLength":8},"session_id":{"type":"string","title":"Session Id","maxLength":128,"minLength":1}},"additionalProperties":false},"type":{"type":"string","const":"http"},"method":{"enum":["POST","PUT","PATCH"],"type":"string"},"bodyType":{"enum":["json","form-data","text"],"type":"string"}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","title":"PreflightResponse","required":["decision","reason"],"properties":{"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","default":null},"age_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Age Ms","default":null},"reason":{"type":"string","title":"Reason"},"result":{"anyOf":[{"type":"object","additionalProperties":{}},{"type":"null"}],"title":"Result","default":null},"decision":{"enum":["EXECUTE","REUSE","BLOCK_DUPLICATE","WAIT","REVIEW"],"type":"string","title":"Decision"},"effect_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effect Id","default":null},"match_method":{"type":"string","title":"Match Method","default":"policy_canonicalization"},"policy_version":{"type":"string","title":"Policy Version","default":"effect-contract-v1"},"retry_after_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Retry After Ms","default":null},"execution_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Token","default":null},"reservation_expires_at_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Reservation Expires At Ms","default":null}},"additionalProperties":false}}}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_g0I5ZnR8GD2iCTetw2PoP","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Checks whether a proposed agent tool call should be executed, reused from cache, blocked as a duplicate, or held for review — before the agent spends money or causes side effects.","exampleAgentPrompt":"Before I run the 'send_invoice' tool for account acct_123 in session sess_abc, check whether agent agent-7 already ran it with the same arguments in the last 30 seconds — use request ID req_20240601_001 and block it if it's a duplicate.","exampleUseCases":[{"title":"Prevent double-payment in parallel agents","prompt":"I have two agents that might both try to trigger 'process_payment' for account acct_789 at the same time — before either one runs it, check if it's already been done in the last 30 seconds using request ID req_pay_20240601 and block the second one if it's a duplicate."},{"title":"Reuse cached read result across agents","prompt":"Agent-A already fetched the account balance for account acct_456 in session sess_main a few seconds ago — before agent-B runs 'get_balance' with the same arguments, check if we can just reuse that cached result instead of calling it again; use request ID req_bal_20240601."},{"title":"Gate irreversible action before execution","prompt":"I'm about to run the 'delete_records' tool for account acct_321, agent agent-ops, session sess-cleanup — preflight it with request ID req_del_20240601 so I know whether to actually execute, wait for another agent, or flag it for review before anything gets deleted."}],"resultDescription":"Returns a decision enum (EXECUTE, REUSE, BLOCK_DUPLICATE, WAIT, or REVIEW) with a human-readable reason, an optional cached result and its age in milliseconds, an effect_id for tracking, the current state of the operation, and the match method used to reach the decision.","failureModes":["Missing required fields (request_id, agent_id, session_id, account_id, tool, arguments) returns 422 validation error","Expired or invalid Bearer token returns 401 unauthorized","request_id shorter than 8 characters returns validation error","max_age_ms outside 0–3600000 range returns validation error","Service cold-start on Render may cause elevated latency","WAIT decision means another agent is mid-execution and caller must poll or retry","REVIEW decision means human review is required before proceeding"],"whenToPreferThis":"Use this endpoint when multiple AI agents share a single account and may attempt the same tool call concurrently or in rapid succession, and you need to prevent duplicate side effects (double payments, double sends, repeated writes). Prefer this over client-side deduplication when the agents run in separate processes or threads and cannot share in-process state. It is especially valuable before irreversible or expensive operations where exactly-once semantics matter.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-13T06:34:31.078Z","isFirstParty":false,"canonicalSlug":"effectguard-preflight-agent-operation-deduplication-idempotency-check-4bd80fd4"}