Use Praxa SDK tools in an agent loop

​

Choose the integration shape

​

1. Bind the executable tools

import { createPraxaAgentTools, PraxaClient } from "@praxa/sdk";

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

const tools = createPraxaAgentTools(client);
const toolsByName = new Map(tools.map((tool) => [tool.name, tool]));

​

2. Filter by granted scope and policy

function visiblePraxaTools(grantedScopes: ReadonlySet<string>) {
  return tools.filter((tool) => grantedScopes.has(tool.requiredScope));
}

const visible = visiblePraxaTools(session.praxaScopes);

​

3. Adapt the definitions

import { jsonSchema, tool, ToolLoopAgent } from "ai";

const aiTools = Object.fromEntries(
  visible.map((definition) => [
    definition.name,
    tool({
      description: definition.description,
      inputSchema: jsonSchema(definition.inputSchema),
      execute: (input, options) =>
        definition.execute(input, { signal: options.abortSignal }),
    }),
  ]),
);

const agent = new ToolLoopAgent({ model, tools: aiTools });

import { PRAXA_OPENAI_FUNCTION_TOOLS } from "@praxa/sdk";

const response = await openai.responses.create({
  model: "your-reviewed-model",
  input: "Inspect the governed mission and explain its current state.",
  tools: PRAXA_OPENAI_FUNCTION_TOOLS,
});

for (const call of extractFunctionCalls(response)) {
  const definition = toolsByName.get(call.name);
  if (!definition) throw new Error(`Unknown Praxa tool: ${call.name}`);
  await enforceApplicationApproval(call, definition);
  const result = await definition.execute(JSON.parse(call.arguments));
  await submitFunctionResult(call.callId, result);
}

for (const proposed of modelOutput.toolCalls) {
  const definition = toolsByName.get(proposed.name);
  if (!definition) throw new Error("Unregistered tool");
  if (!session.praxaScopes.has(definition.requiredScope)) {
    throw new Error("Tool is outside the delegated scope set");
  }
  if (!definition.readOnly) {
    await requireReviewedMutation(proposed);
  }
  const output = await definition.execute(proposed.input, {
    signal: request.signal,
  });
  await appendToolResult(proposed.id, output);
}

​

Approval placement

​

Handle tool errors

import { PraxaClientError } from "@praxa/sdk";

async function executeForAgent(toolName: string, input: unknown) {
  const tool = toolsByName.get(toolName);
  if (!tool) return { ok: false, code: "unknown_tool" };

  try {
    return { ok: true, value: await tool.execute(input) };
  } catch (error) {
    if (error instanceof PraxaClientError) {
      return {
        ok: false,
        code: error.problem?.code ?? "praxa_request_failed",
        retryable: error.problem?.retryable ?? false,
      };
    }
    return { ok: false, code: "integration_failed", retryable: false };
  }
}

​

Test the agent boundary

1. Assert the exact 12 registered names and required scopes.
2. Assert unknown names are rejected before execution.
3. Assert malformed inputs fail schema validation before a network call.
4. Assert read-only mode hides every mutating tool.
5. Assert a proposed mutation cannot execute without application approval.
6. Assert an under-scoped or revoked token still fails at the Gateway.
7. Assert tool failures return bounded model-visible errors with no token, provider body, memory text, or internal trace.
8. Assert the model cannot override tenant, owner, scope, purpose, or budget fields that your application owns.

​

Best practices

• Register only the tools relevant to the current task.
• Keep tool descriptions factual and action-specific.
• Separate read tools from mutations in your product policy.
• Cap tool-loop iterations and total elapsed time.
• Forward caller cancellation through AbortSignal.
• Persist mutation idempotency keys before execution.
• Record tool name, policy decision, status, and latency without logging inputs that can contain customer data.
• Treat tool success as the returned contract state, not proof of an external provider effect unless the result contains that evidence.