Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

fix(exchange): record agent Exchange charges on the agent run's call credits (#5329)

Rakshith Ramprakash1a1398095a8e
diff --git a/apps/api/src/controllers/v2/scrape-alexandria.test.ts b/apps/api/src/controllers/v2/scrape-alexandria.test.ts
index d7eb788e1..da3a222c9 100644
--- a/apps/api/src/controllers/v2/scrape-alexandria.test.ts
+++ b/apps/api/src/controllers/v2/scrape-alexandria.test.ts
@@ -151,7 +151,7 @@ it("relays a failed single legacy call as an error, not a success", async () =>
});
});
-it("only lets trusted agent interop bypass billing, and prefers its request id", async () => {
+it("only lets trusted agent interop bypass billing, and charges its run without keying calls by it", async () => {
const untrusted = await request(app)
.post("/v2/scrape")
.send({
@@ -175,12 +175,66 @@ it("only lets trusted agent interop bypass billing, and prefers its request id",
});
expect(trusted.status).toBe(200);
expect(mocks.retrieve).toHaveBeenCalledWith(
- expect.objectContaining({ requestId: "agent-id", bypassBilling: true }),
+ expect.objectContaining({
+ requestId: "hop-id",
+ agentRequestId: "agent-id",
+ bypassBilling: true,
+ }),
);
expect(mocks.log).not.toHaveBeenCalled();
expect(mocks.scrapeLog).not.toHaveBeenCalled();
});
+it("gives each agent call its own request id when the agent sends none", async () => {
+ const interop = {
+ auth: "test-secret",
+ requestId: "agent-id",
+ shouldBill: true,
+ };
+ await request(app)
+ .post("/v2/scrape")
+ .send({ alexandria: call, __agentInterop: interop });
+ await request(app)
+ .post("/v2/scrape")
+ .send({ alexandria: call, __agentInterop: interop });
+ const [first, second] = mocks.retrieve.mock.calls.map(([arg]) => arg);
+ expect(first.agentRequestId).toBe("agent-id");
+ expect(second.agentRequestId).toBe("agent-id");
+ expect(first.requestId).not.toBe("agent-id");
+ expect(first.requestId).not.toBe(second.requestId);
+});
+
+it("accepts agent interop on both legacy request shapes", async () => {
+ const interop = {
+ auth: "test-secret",
+ requestId: "agent-id",
+ shouldBill: true,
+ };
+ const single = await request(app)
+ .post("/exchange/retrieve")
+ .send({ ...call, zeroDataRetention: true, __agentInterop: interop });
+ const batch = await request(app)
+ .post("/exchange/retrieve")
+ .send({ requests: [call], __agentInterop: interop });
+ expect(single.status).toBe(200);
+ expect(batch.status).toBe(200);
+ for (const [arg] of mocks.retrieve.mock.calls)
+ expect(arg).toEqual(
+ expect.objectContaining({
+ calls: [call],
+ agentRequestId: "agent-id",
+ bypassBilling: false,
+ }),
+ );
+ expect(mocks.retrieve.mock.calls[0][0].zeroDataRetention).toBe(true);
+
+ const untrusted = await request(app)
+ .post("/exchange/retrieve")
+ .send({ ...call, __agentInterop: { ...interop, auth: "wrong" } });
+ expect(untrusted.status).toBe(403);
+ expect(mocks.retrieve).toHaveBeenCalledTimes(2);
+});
+
it("returns before logging finishes but orders the child after the parent", async () => {
let finish!: () => void;
mocks.log.mockReturnValue(
diff --git a/apps/api/src/controllers/v2/scrape-alexandria.ts b/apps/api/src/controllers/v2/scrape-alexandria.ts
index e82fcbd5b..3023fa64a 100644
--- a/apps/api/src/controllers/v2/scrape-alexandria.ts
+++ b/apps/api/src/controllers/v2/scrape-alexandria.ts
@@ -47,6 +47,13 @@ const findToolsItems = (data: unknown): unknown[] => {
return Array.isArray(items) ? items : [];
};
+const agentInteropSchema = z.strictObject({
+ auth: z.string(),
+ requestId: z.string(),
+ shouldBill: z.boolean(),
+ boostConcurrency: z.boolean().optional(),
+});
+
const providerScrapeSchema = z.strictObject({
alexandria: z.preprocess(
value => (Array.isArray(value) ? value : [value]),
@@ -61,14 +68,7 @@ const providerScrapeSchema = z.strictObject({
origin: z.string().default("api"),
integration: z.string().nullable().optional(),
zeroDataRetention: z.boolean().optional(),
- __agentInterop: z
- .strictObject({
- auth: z.string(),
- requestId: z.string(),
- shouldBill: z.boolean(),
- boostConcurrency: z.boolean().optional(),
- })
- .optional(),
+ __agentInterop: agentInteropSchema.optional(),
});
export async function providerScrapeController(
@@ -76,7 +76,10 @@ export async function providerScrapeController(
res: Response,
legacy = false,
) {
- const legacyZeroDataRetention = { zeroDataRetention: z.boolean().optional() };
+ const legacyZeroDataRetention = {
+ zeroDataRetention: z.boolean().optional(),
+ __agentInterop: agentInteropSchema.optional(),
+ };
const legacyBody = legacy
? z
.union([
@@ -87,9 +90,10 @@ export async function providerScrapeController(
: null;
const body = providerScrapeSchema.parse(
legacyBody
- ? (({ zeroDataRetention, ...rest }) => ({
+ ? (({ zeroDataRetention, __agentInterop, ...rest }) => ({
alexandria: "requests" in rest ? rest.requests : [rest],
zeroDataRetention,
+ __agentInterop,
}))(legacyBody)
: req.body,
);
@@ -104,8 +108,7 @@ export async function providerScrapeController(
.status(403)
.json({ success: false, error: "Invalid agent interop." });
}
- const requestId =
- body.__agentInterop?.requestId ?? req.get("x-request-id") ?? randomUUID();
+ const requestId = req.get("x-request-id") ?? randomUUID();
if (REQUEST_ID_PATTERN.test(requestId))
res.setHeader("x-request-id", requestId);
@@ -169,6 +172,7 @@ export async function providerScrapeController(
calls: body.alexandria,
resultAuthorization: req.get("authorization"),
requestId,
+ agentRequestId: body.__agentInterop?.requestId,
scrapeId: uuidv7(),
timeoutMs: body.timeout,
bypassBilling: body.__agentInterop?.shouldBill === false,
diff --git a/apps/api/src/services/alexandria/retrieve.test.ts b/apps/api/src/services/alexandria/retrieve.test.ts
index ea357ea91..f8ae29574 100644
--- a/apps/api/src/services/alexandria/retrieve.test.ts
+++ b/apps/api/src/services/alexandria/retrieve.test.ts
@@ -19,8 +19,15 @@ const mocks = vi.hoisted(() => {
refund: vi.fn(),
billAdd: vi.fn(),
report: vi.fn(),
+ initCredits: vi.fn(),
+ recordCredits: vi.fn(),
};
});
+vi.mock("../../lib/request-credits-store", () => ({
+ AGENT_REQUEST_CREDITS_SHARDS: 8,
+ initializeRequestCredits: mocks.initCredits,
+ recordRequestCredits: mocks.recordCredits,
+}));
vi.mock("../../config", () => ({ config: mocks.config }));
vi.mock("../rate-limiter", () => ({ redisRateLimitClient: mocks.redis }));
vi.mock("./client", () => ({ exchangeRequest: mocks.request }));
@@ -85,6 +92,8 @@ beforeEach(() => {
mocks.refund.mockResolvedValue(undefined);
mocks.billAdd.mockResolvedValue({});
mocks.report.mockResolvedValue(true);
+ mocks.initCredits.mockResolvedValue(true);
+ mocks.recordCredits.mockResolvedValue(true);
exchangeAnswers(answer);
});
@@ -693,3 +702,54 @@ it("refuses the same x-request-id with a different zero data retention setting",
);
expect(executions()).toHaveLength(1);
});
+
+it("records an agent call's charge on the agent run, once, at Exchange's price", async () => {
+ await run({ agentRequestId: "agent-run", zeroDataRetention: true });
+ expect(mocks.initCredits).not.toHaveBeenCalled();
+ expect(mocks.recordCredits).toHaveBeenCalledTimes(1);
+ expect(mocks.recordCredits).toHaveBeenCalledWith({
+ requestId: "agent-run",
+ jobId: expect.stringMatching(/^alexandria:/),
+ credits: 3,
+ });
+
+ await run({ agentRequestId: "agent-run", zeroDataRetention: true });
+ expect(mocks.recordCredits).toHaveBeenCalledTimes(1);
+});
+
+it("records nothing on the agent run when nothing was charged", async () => {
+ await run({ agentRequestId: "agent-run", bypassBilling: true });
+ mocks.store.clear();
+ mocks.finalize.mockResolvedValueOnce(false);
+ await run({ agentRequestId: "agent-run" });
+ mocks.store.clear();
+ mocks.billAdd.mockRejectedValue(new Error("queue down"));
+ await run({ agentRequestId: "agent-run" });
+ expect(mocks.recordCredits).not.toHaveBeenCalled();
+});
+
+it("still answers when the agent run's credits cannot be recorded", async () => {
+ mocks.recordCredits.mockRejectedValue(new Error("bigtable down"));
+ expect(await run({ agentRequestId: "agent-run" })).toMatchObject({
+ status: 200,
+ executed: true,
+ });
+ expect(mocks.billAdd).toHaveBeenCalledTimes(1);
+});
+
+it("creates the agent run's credit row only when it is missing", async () => {
+ mocks.recordCredits.mockResolvedValueOnce(false).mockResolvedValueOnce(true);
+ await run({ agentRequestId: "agent-run" });
+ expect(mocks.initCredits).toHaveBeenCalledWith("agent-run", 8);
+ expect(mocks.recordCredits).toHaveBeenCalledTimes(2);
+});
+
+it("does not retry the write when the credit store is unavailable", async () => {
+ mocks.recordCredits.mockResolvedValue(false);
+ mocks.initCredits.mockResolvedValue(false);
+ expect(await run({ agentRequestId: "agent-run" })).toMatchObject({
+ status: 200,
+ executed: true,
+ });
+ expect(mocks.recordCredits).toHaveBeenCalledTimes(1);
+});
diff --git a/apps/api/src/services/alexandria/retrieve.ts b/apps/api/src/services/alexandria/retrieve.ts
index 545a0f997..fc18705f2 100644
--- a/apps/api/src/services/alexandria/retrieve.ts
+++ b/apps/api/src/services/alexandria/retrieve.ts
@@ -13,6 +13,11 @@ import {
featureIdForBillingEndpoint,
} from "../autumn/autumn.service";
import type { LockCreditsResult } from "../autumn/types";
+import {
+ AGENT_REQUEST_CREDITS_SHARDS,
+ initializeRequestCredits,
+ recordRequestCredits,
+} from "../../lib/request-credits-store";
import { getBillingQueue } from "../queue-service";
import { redisRateLimitClient } from "../rate-limiter";
import { authorizeProviders } from "./access";
@@ -92,6 +97,8 @@ export async function retrieveProviders(input: {
flags: TeamFlags | null | undefined;
calls: ProviderCall[];
requestId: string;
+ /** The agent run this call belongs to: its credits join that run's call credits. */
+ agentRequestId?: string;
scrapeId: string;
timeoutMs: number;
bypassBilling?: boolean;
@@ -475,6 +482,10 @@ export async function retrieveProviders(input: {
refundable,
)
: settled;
+ const charged =
+ settled && billable && credits > 0 && (recorded || !refundable);
+ if (charged && input.agentRequestId)
+ await recordAgentCredits(input.agentRequestId, id, credits);
if (!billable || recorded)
void reportExchangeUsageBilling({
requestId: id,
@@ -494,6 +505,37 @@ export async function retrieveProviders(input: {
}
}
+async function recordAgentCredits(
+ agentRequestId: string,
+ chargeId: string,
+ credits: number,
+) {
+ const record = () =>
+ recordRequestCredits({
+ requestId: agentRequestId,
+ jobId: `alexandria:${chargeId}`,
+ credits,
+ });
+ try {
+ if (await record()) return;
+ if (
+ !(await initializeRequestCredits(
+ agentRequestId,
+ AGENT_REQUEST_CREDITS_SHARDS,
+ ))
+ )
+ throw new Error("Request credits store is unavailable");
+ await record();
+ } catch (error) {
+ logger.error("Provider credits were not recorded on the agent run", {
+ chargeId,
+ agentRequestId,
+ credits,
+ error,
+ });
+ }
+}
+
async function recordLedgerUsage(
id: string,
teamId: string,