Add Praxa tools to Vercel AI SDK

​

Prerequisites

• the exact published Praxa package versions used by the tutorial;
• a trusted agent host with explicit tool, approval, timeout, and output policies;
• deployment-specific OAuth or backend-owned provider clients where the selected lane requires them;
• synthetic tenant, subject, prompt, and tool fixtures for positive and adversarial tests;
• an acceptance assertion that proves the Vercel AI SDK adapter preserves exact schemas, approvals, and authoritative result readback.

​

1. Install the packages

npm install ai @praxa/sdk@0.3.0

​

2. Adapt the tools

import { jsonSchema, tool, ToolLoopAgent } from "ai";
import { createPraxaAgentTools, PraxaClient } from "@praxa/sdk";

const client = new PraxaClient({
  baseUrl: process.env.PRAXA_BASE_URL!,
  accessToken: () => process.env.PRAXA_ACCESS_TOKEN!,
});

const tools = Object.fromEntries(
  createPraxaAgentTools(client).map((definition) => [
    definition.name,
    tool({
      description: definition.description,
      inputSchema: jsonSchema(definition.inputSchema),
      execute: definition.execute,
      needsApproval: !definition.readOnly,
    }),
  ]),
);

const agent = new ToolLoopAgent({
  model: reviewedModel,
  instructions: "Use Praxa tools only for the user's explicit request.",
  tools,
});

​

3. Run and inspect

const result = await agent.generate({
  prompt: "Prepare the weekly review with a bounded mission.",
});

console.log(result.text);

​

4. Test the integration

1. Assert all expected tool names are registered exactly once.
2. Assert each input schema is passed through jsonSchema().
3. Assert mutation tools require approval in your host.
4. Test a token without the required scope and require a fail-closed result.
5. Replay a timed-out mutation with its original idempotency key.
6. Verify a returned run independently of the model’s final prose.
7. Confirm tokens and tool payloads are absent from browser bundles and logs.

​

Troubleshooting

​

Best practices

• Enable the smallest tool or source set needed for the workflow.
• Require approval for mutations and independently for destructive actions.
• Derive tenant, subject, purpose, and credential from trusted host context.
• Bound tool inputs, output bytes, concurrent calls, retries, and total turn time.
• Verify a run, event, trace, receipt, or source status independently of model prose.

​

Optimize for production

• Reduce tool definitions and provider sources to the relevant set before each turn.
• Use deterministic filtering and pagination before placing results in model context.
• Cache only versioned, non-sensitive contracts and read-only metadata.
• Measure tool-selection accuracy, approval rate, p50/p95 call latency, context bytes, retries, and verified completion.

​

Cleanup and next steps

1. Revoke disposable delegated grants and remove test host configuration.
2. Delete provider fixtures through the provider’s own lifecycle when applicable.
3. Disable mutation tools until their negative and approval tests pass again after upgrades.
4. Retain only redacted tool, run, trace, and receipt identifiers needed for evaluation.

​

Frequently asked questions

​

What proves this tutorial works?

​

Can a browser, mobile app, or model prompt hold the credential?

​

How should an ambiguous mutation be retried?

​

What should we monitor after release?