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

# Installation

> Install the AgentRein SDK and configure your API key.

## Install

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install agentrein
  ```

  ```bash Python theme={null}
  pip install agentrein
  ```
</CodeGroup>

## Import

The TypeScript SDK ships as a dual CJS/ESM package.

<CodeGroup>
  ```ts TypeScript theme={null}
  import { AgentRein } from 'agentrein';
  ```

  ```python Python theme={null}
  from agentrein import AgentRein
  ```
</CodeGroup>

## Initialize

<CodeGroup>
  ```ts TypeScript theme={null}
  const agentrein = new AgentRein({
    apiKey: process.env.AGENTREIN_API_KEY,
    serverUrl: 'https://api.agentrein.com', // optional, this is the default
    failureMode: 'open',                     // optional, 'open' | 'closed'
  });
  ```

  ```python Python theme={null}
  import os
  from agentrein import AgentRein

  agentrein = AgentRein(
      api_key=os.environ["AGENTREIN_API_KEY"],
      server_url="https://api.agentrein.com",  # optional, this is the default
      failure_mode="open",                      # optional, "open" | "closed"
  )
  ```
</CodeGroup>

### Options

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `apiKey` (Python: `api_key`) | `string` / `str` | Yes | — | Your organization API key from the dashboard |
| `serverUrl` (Python: `server_url`) | `string` / `str` | No | `https://api.agentrein.com` | AgentRein backend URL |
| `failureMode` (Python: `failure_mode`) | `'open' \| 'closed'` | No | `'open'` | `open` — SDK continues if backend is unreachable. `closed` — throws/raises `AgentReinUnavailableError` |

## Environment Variable

```bash theme={null}
AGENTREIN_API_KEY=ar_live_your_key_here
```

***

## Sandbox Mode

Use sandbox mode during development to test your agent logic without executing
real actions on GitHub, Stripe, Slack, or any other connector.

### Setup

1. Go to **Dashboard → Settings → API Keys** and create a new key with **Sandbox** enabled.
   Your key will have the prefix `ar_test_`.

2. Set your environment variable:

```bash theme={null}
AGENTREIN_API_KEY=ar_test_your_key_here
```

3. Use the SDK exactly as you would in production — no code changes needed:

<CodeGroup>
  ```ts TypeScript theme={null}
  const agentrein = new AgentRein({
    apiKey: process.env.AGENTREIN_API_KEY, // ar_test_ key
  });

  const session = await agentrein.newSession({ agentId: 'my-agent' });
  const agentOctokit = agentrein.wrap(octokit, session, { connector: 'github' });

  // This will NOT create a real GitHub issue
  const issue = await agentOctokit.issues.create({
    owner: 'my-org',
    repo: 'my-repo',
    title: 'Test issue',
  });

  console.log(issue.id);        // sim_id_1234567890
  console.log(issue.html_url);  // https://sandbox.agentrein.com

  await agentrein.completeSession(session);
  ```

  ```python Python theme={null}
  import os
  from agentrein import AgentRein
  from github import Github

  agentrein = AgentRein(api_key=os.environ["AGENTREIN_API_KEY"])  # ar_test_ key

  gh = Github(os.environ["GITHUB_TOKEN"])
  repo = gh.get_repo("my-org/my-repo")

  session = agentrein.new_session(agent_id="my-agent")
  agent_repo = agentrein.wrap(repo, session, connector="github")

  # This will NOT create a real GitHub issue
  issue = agent_repo.create_issue(title="Test issue")

  print(issue.id)         # sim_id_1234567890
  print(issue.html_url)   # https://sandbox.agentrein.com

  agentrein.complete_session(session)
  ```
</CodeGroup>

<Note>
  Sandbox sessions appear in your dashboard under the **Sandbox** filter tab,
  clearly marked with a "Simulated" badge. Switch to your `ar_live_` key
  when you are ready for production — no other code changes needed.
</Note>

<Warning>
  `rollbackSession()` (Python: `rollback_session()`) in sandbox mode converts actions whose status is `SUCCESS` or `PENDING_APPROVAL` to `ROLLED_BACK`; `FAILED` and `ROLLBACK_FAILED` actions are left untouched. No real compensation runs. A session with no SUCCESS action cannot be rolled back; the request is rejected.
</Warning>

<Info>
  The Python SDK (v1) is synchronous and supports sync connector clients only (Stripe, PyGithub, `slack_sdk`, `simple-salesforce`, and similar) — there is no `await` anywhere in the Python SDK.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.