From 351a79d89c741dd4a732a44d74e5d82ad26985a3 Mon Sep 17 00:00:00 2001 From: EfeDurmaz16 Date: Sat, 16 May 2026 07:37:12 +0300 Subject: [PATCH 1/2] docs: add agent framework indexing guide Signed-off-by: EfeDurmaz16 --- context7.json | 13 ++++ docs/docs.json | 1 + .../overview/agent-framework-integrations.mdx | 67 +++++++++++++++++++ 3 files changed, 81 insertions(+) create mode 100644 context7.json create mode 100644 docs/overview/agent-framework-integrations.mdx diff --git a/context7.json b/context7.json new file mode 100644 index 0000000..2055f0c --- /dev/null +++ b/context7.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://context7.com/schema/context7.json", + "projectTitle": "Agent Commerce Kit", + "description": "Open protocols, SDKs, and demos for verifiable agent identity and agent payments.", + "folders": ["docs", "packages", "demos"], + "excludeFolders": ["node_modules", "dist", ".turbo"], + "excludeFiles": ["pnpm-lock.yaml"], + "rules": [ + "Use ACK-ID for verifiable agent identity, ownership chains, and service discovery.", + "Use ACK-Pay for payment requests, receipts, payment service flows, and human oversight.", + "Keep agent-framework integrations thin; ACK protocol primitives should remain framework-agnostic." + ] +} diff --git a/docs/docs.json b/docs/docs.json index 2f6da92..f5c4f9b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -37,6 +37,7 @@ "overview/introduction", "overview/concepts", "overview/architecture", + "overview/agent-framework-integrations", "overview/future-directions", "overview/references" ] diff --git a/docs/overview/agent-framework-integrations.mdx b/docs/overview/agent-framework-integrations.mdx new file mode 100644 index 0000000..f175c54 --- /dev/null +++ b/docs/overview/agent-framework-integrations.mdx @@ -0,0 +1,67 @@ +--- +title: Agent Framework Integrations +description: Guidance for indexing ACK docs and integrating ACK primitives with agent frameworks. +--- + +Agent Commerce Kit is designed to stay framework-agnostic. Agent runtimes should +use ACK-ID and ACK-Pay as protocol primitives, while framework-specific adapters +remain thin examples or optional packages. + +## Documentation indexing + +ACK documentation can be indexed by developer tools that retrieve library docs +for coding agents. For Context7, the repository includes a `context7.json` +configuration that points indexers at the docs, package READMEs, and runnable +demos. + +Maintainers or contributors can submit the public GitHub repository to Context7 +and use the checked-in configuration as the default parsing guide. The intended +library identity is: + +```text +agentcommercekit/ack +``` + +## Adapter boundary + +Framework adapters should not reimplement ACK protocol logic. They should call +the ACK SDKs and examples at the edges of an agent workflow: + +- use ACK-ID when an agent needs to prove its identity, owner, controller, or + service endpoint +- use ACK-Pay when an agent needs to request payment, present a payment receipt, + or pause for human approval +- keep payment execution, policy checks, and receipt verification explicit in + the application layer +- avoid hiding identity or payment state inside an LLM prompt-only abstraction + +## Framework cookbook targets + +Useful cookbook examples can be added incrementally: + +| Framework surface | Useful first example | +| ----------------- | ------------------------------------------------------------------------------ | +| OpenAI Agents SDK | Require an ACK-ID credential before an agent calls a paid tool. | +| Claude Agent SDK | Verify an ACK receipt before returning protected tool output. | +| Vercel AI SDK | Gate a route or tool call with ACK-Pay and return a receipt-aware response. | +| MCP servers | Expose paid tools that advertise ACK payment requirements and verify receipts. | + +Each example should be small enough to audit. The core pattern is always: + +1. Resolve and verify identity when the counterparty matters. +2. Evaluate payment or approval policy before execution. +3. Execute the paid action only after the ACK requirement is satisfied. +4. Persist or return the receipt evidence needed by the relying party. + +## Language SDKs + +Additional SDKs should be tracked as separate implementation efforts. A good +first milestone for any new language is a read-only example that can: + +- parse an ACK payment request +- verify a receipt shape +- call a reference TypeScript service +- document which protocol features are intentionally unsupported + +That keeps language work interoperable without coupling ACK core to any single +agent framework or runtime. From 3ef81332fbb1c6480366195a74e1795af4987728 Mon Sep 17 00:00:00 2001 From: EfeDurmaz16 Date: Sat, 16 May 2026 07:52:13 +0300 Subject: [PATCH 2/2] docs: use canonical context7 id Signed-off-by: EfeDurmaz16 --- docs/overview/agent-framework-integrations.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview/agent-framework-integrations.mdx b/docs/overview/agent-framework-integrations.mdx index f175c54..006472c 100644 --- a/docs/overview/agent-framework-integrations.mdx +++ b/docs/overview/agent-framework-integrations.mdx @@ -19,7 +19,7 @@ and use the checked-in configuration as the default parsing guide. The intended library identity is: ```text -agentcommercekit/ack +/agentcommercekit/ack ``` ## Adapter boundary