> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Praxa tools to Vercel AI SDK

> Adapt Praxa's governed tool definitions to a Vercel AI SDK ToolLoopAgent and preserve approval, scope, and completion checks.

Praxa provides executable tool definitions through <code>@praxa/sdk</code>.
Vercel AI SDK provides the model loop. Your backend remains responsible for
the reviewed model, token authority, and final user experience.

## Prerequisites

Before you begin, prepare:

* 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

```bash theme={null}
npm install ai @praxa/sdk@0.3.0
```

## 2. Adapt the tools

```ts theme={null}
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,
});
```

Do not remove the server-side Praxa checks because the host has an approval
option. Framework approval is defense in depth; Praxa still evaluates scope,
tenant, purpose, policy, revocation, and idempotency at execution time.

## 3. Run and inspect

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

console.log(result.text);
```

Treat the model response as presentation. For an operation that returns a
Praxa run ID, read the run or consume events before claiming the mission
completed.

## 4. Test the integration

1. Assert all expected tool names are registered exactly once.
2. Assert each input schema is passed through <code>jsonSchema()</code>.
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.

<Card title="ToolLoopAgent reference" icon="arrow-up-right-from-square" href="https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent">
  Review the current agent-loop contract in the official Vercel AI SDK docs.
</Card>

## Troubleshooting

| Symptom                              | Resolution                                                                                    |
| ------------------------------------ | --------------------------------------------------------------------------------------------- |
| Package imports but nothing executes | Separate package contracts from the deployment or provider executor they describe.            |
| Agent selects the wrong tool         | Shrink the allowlist and improve the specific tool description and task policy.               |
| Mutation repeats after timeout       | Persist the exact input and idempotency key, then reconcile before a new call.                |
| Tool output changes agent intent     | Treat tool content as untrusted data and preserve the original purpose and approval boundary. |

## 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.

Optimize only after the correctness and isolation matrix passes. Lower latency or cost is not an improvement if verified outcomes, authority checks, or recovery rates regress.

## 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.

After cleanup, run the [shared integration test matrix](/tutorials/test-your-integration) and record any environment-specific check that remains pending.

## Frequently asked questions

### What proves this tutorial works?

The minimum observable result is that the Vercel AI SDK adapter preserves exact schemas, approvals, and authoritative result readback. A compile, package import, mocked response, or initial admission alone does not prove the complete workflow.

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

Only a trusted server or agent host may hold delegated Praxa or provider credentials. Never place them in model input or client bundles.

### How should an ambiguous mutation be retried?

Persist the exact logical input and idempotency key before the first attempt. Reconcile through authoritative readback or replay the exact request with that same key before creating new work.

### What should we monitor after release?

Monitor tool-selection accuracy, approval decisions, call latency, context size, retries, denials, and verified outcomes. Alert on authorization bypass, cross-tenant disclosure, repeated conflicts, or cleanup failure.