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

# Choose a Praxa framework integration

> Choose the supported Praxa integration boundary for TypeScript, Next.js, Nuxt, Python, Rust, Go, Java, .NET, React Native, SwiftUI, Kotlin, and agent frameworks.

Praxa uses open HTTP, SSE, webhook, OAuth, and MCP contracts. The official
`@praxa/sdk` and `@praxa/cli` packages are TypeScript/Node.js artifacts; other
languages integrate through the public REST plane or through a trusted
application backend.

## Prerequisites

Before you begin, prepare:

* a written success criterion and proof boundary for the integration under test;
* synthetic tenants, subjects, credentials, and lifecycle fixtures;
* redacted observability fields and a secure location for test evidence;
* an owner for rollback, cleanup, and unresolved qualification gaps;
* an acceptance assertion that proves the selected framework matches the API plane, credential boundary, and required acceptance tests.

## Decision matrix

| Stack                     | Recommended integration                                         | Credential location | Guide                                                       |
| ------------------------- | --------------------------------------------------------------- | ------------------- | ----------------------------------------------------------- |
| TypeScript / Node.js      | `@praxa/sdk` for Gateway missions; `fetch` for Execution Fabric | Server              | [TypeScript](/tutorials/typescript)                         |
| Next.js                   | App Router Route Handler or server-only module                  | Server              | [Next.js](/tutorials/nextjs)                                |
| Nuxt                      | Nitro `server/api` handler plus private runtime config          | Server              | [Nuxt](/tutorials/nuxt)                                     |
| Express                   | Validated backend route                                         | Server              | [Express](/tutorials/express)                               |
| Cloudflare Workers / Hono | Worker secret plus bounded handler                              | Worker              | [Cloudflare Workers](/tutorials/cloudflare-workers)         |
| Python                    | HTTPX client or FastAPI backend                                 | Server              | [Python](/tutorials/python) · [FastAPI](/tutorials/fastapi) |
| Rust                      | Reused `reqwest::Client` in Axum or another server              | Server              | [Rust](/tutorials/rust)                                     |
| Go                        | Reused `http.Client` in a backend                               | Server              | [Go](/tutorials/go)                                         |
| Java / Spring             | Spring `RestClient` or `WebClient`                              | Server              | [Spring](/tutorials/java-spring)                            |
| .NET                      | Reused `HttpClient` through dependency injection                | Server              | [.NET](/tutorials/dotnet)                                   |
| React Native / Expo       | Call your authenticated backend                                 | No Praxa key in app | [React Native](/tutorials/react-native)                     |
| SwiftUI                   | `URLSession` to your authenticated backend                      | No Praxa key in app | [SwiftUI](/tutorials/swiftui)                               |
| Android / Kotlin          | Ktor or platform client to your authenticated backend           | No Praxa key in app | [Kotlin](/tutorials/kotlin)                                 |
| Vercel AI SDK             | `createPraxaAgentTools()` adapter                               | Server              | [Vercel AI SDK](/tutorials/vercel-ai-sdk)                   |
| OpenAI Agents / Responses | Remote MCP or function tools                                    | Server              | [OpenAI Agents](/tutorials/openai-agents)                   |
| LangGraph                 | Read-only memory adapter plus explicit namespace resolver       | Server              | [LangGraph](/tutorials/langgraph)                           |

## Choose the API plane first

```mermaid theme={null}
flowchart TD
  Need{"What are you integrating?"}
  Need -->|"Durable task API"| Fabric["Execution Fabric /v1"]
  Need -->|"Mission, tools, capabilities, private query plane"| Gateway["Integration Gateway /v8"]
  Need -->|"Existing provider memory"| Memory["@praxa/sdk/memory"]
  Need -->|"Agent host protocol"| MCP["MCP contracts or remote MCP"]
  Fabric --> Key["Personal server API key"]
  Gateway --> OAuth["Short-lived delegated OAuth"]
  Memory --> Provider["Backend-owned provider clients"]
  MCP --> OAuth
```

Do not mix credentials between planes. A Fabric key does not become a Gateway
OAuth token, and a provider client does not grant Praxa execution authority.

## Mobile and browser rule

React, Vue, Svelte, React Native, SwiftUI, and Kotlin UI code should call your
own authenticated backend. Application bundles can be inspected by users and
attackers; they are not a secret store for Praxa API keys or delegated backend
tokens.

## Shared acceptance matrix

Every framework tutorial ends with the same core proof:

1. Missing application authentication fails before Praxa is called.
2. Invalid or over-limit input fails before Praxa is called.
3. Tenant and owner come from the authenticated session.
4. The backend owns the Praxa credential and idempotency key derivation.
5. Exact retries preserve the logical operation.
6. Changed input under an old key is refused.
7. Revoked and under-scoped credentials fail closed.
8. Foreign identifiers do not disclose another tenant's resource.
9. Admission is followed to terminal readback.
10. Disposable credentials and test data are cleaned up.

<Card title="Test your integration" icon="flask" href="/tutorials/test-your-integration">
  Apply the full package, authorization, replay, isolation, outage, stream,
  webhook, deletion, and cleanup matrix.
</Card>

## Troubleshooting

| Symptom                                       | Resolution                                                                                   |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Dashboard says success but outcome is unknown | Require terminal readback or an explicit incomplete verification state.                      |
| Metrics cannot be correlated                  | Carry safe request, run, event, delivery, trace, and test identifiers across boundaries.     |
| Logs contain sensitive data                   | Stop collection, rotate exposed credentials, and replace raw payloads with bounded metadata. |
| One green test is treated as production proof | Track package, mock, authenticated runtime, deployment, and user verification separately.    |

## Best practices

* Define the expected observable result before running the test.
* Separate positive, denial, isolation, replay, degraded-state, and cleanup lanes.
* Use synthetic data and credential fingerprints rather than secrets.
* Record unresolved checks as pending instead of inferring success.
* Keep rollback and owner information beside the release evidence.

## Optimize for production

* Run cheap contract and fake tests before authenticated canaries.
* Parallelize only independent test lanes and cap external side effects.
* Sample high-volume telemetry while retaining every denial, conflict, and terminal failure.
* Measure pass rate, p50/p95 latency, retry budget, isolation failures, cleanup completion, and time to diagnose.

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 every disposable key and OAuth grant.
2. Remove test endpoints, provider records, candidates, and local artifacts.
3. Close or explicitly record unresolved runs and verification gaps.
4. Publish only redacted results, exact versions, timestamps, and rollback instructions.

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 selected framework matches the API plane, credential boundary, and required acceptance tests. 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?

No. Evidence contains credential fingerprints and safe identifiers, never live credentials or raw sensitive payloads.

### 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 test pass rate, p50/p95 latency, authorization denials, replay conflicts, isolation failures, cleanup completion, and diagnosis time. Alert on authorization bypass, cross-tenant disclosure, repeated conflicts, or cleanup failure.