> ## 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 an agent-framework integration

> Select the Praxa tool, mission, or memory boundary for Vercel AI SDK, OpenAI Agents, LangGraph, MCP hosts, and custom frameworks.

You do not need to replace your existing model loop or memory store. Choose the
smallest Praxa boundary that adds the missing behavior.

## 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 selected framework invokes only the intended Praxa lane and produces independently verified evidence.

## Choose by responsibility

| Your framework needs                    | Add                                            | Tutorial                                          |
| --------------------------------------- | ---------------------------------------------- | ------------------------------------------------- |
| Governed callable operations            | Executable SDK tool definitions or remote MCP  | [Vercel AI SDK](/tutorials/vercel-ai-sdk)         |
| Remote MCP plus existing session recall | Separate execution and memory lanes            | [OpenAI Agents](/tutorials/openai-agents)         |
| Existing cross-thread long-term memory  | Read-only BaseStore adapter                    | [LangGraph](/tutorials/langgraph)                 |
| A generic MCP contract                  | Stable names, schemas, annotations, and scopes | [MCP tools](/tutorials/mcp-tools)                 |
| A custom store                          | <code>MemorySource</code> implementation       | [Memory federation](/tutorials/memory-federation) |
| Budgeted durable orchestration          | <code>PraxaClient</code> mission lifecycle     | [Mission lifecycle](/tutorials/mission-lifecycle) |

```mermaid theme={null}
flowchart TD
  Need{"What is missing?"}
  Need -->|"governed tools"| MCP["MCP or SDK tools"]
  Need -->|"durable mission"| Client["PraxaClient"]
  Need -->|"existing memory recall"| Memory["Memory federation"]
  MCP --> Verify["Scope plus run or receipt verification"]
  Client --> Verify
  Memory --> Recall["Source status plus provenance verification"]
```

## Shared implementation rules

1. Keep model-provider, Praxa, and memory-provider credentials separate.
2. Resolve tenant and subject from authenticated application context.
3. Preserve tool names and MCP annotations exactly.
4. Require approval for consequential operations in the host and at Praxa.
5. Persist one idempotency key per logical mutation.
6. Inspect returned run, event, receipt, or source status independently of the
   model's final text.

## Shared acceptance matrix

Test correct scope, wrong scope, revoked credential, cross-tenant identifier,
exact retry, changed-body conflict, provider outage, and cleanup. A mocked host
test proves adaptation; a live authenticated canary proves the deployed
boundary.

## 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 selected framework invokes only the intended Praxa lane and produces independently verified evidence. 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.