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

# New Session

> Create a new agent session before executing actions.

## Signature

<CodeGroup>
  ```ts TypeScript theme={null}
  agentrein.newSession(options?: SessionOptions | string): Promise<Session>
  ```

  ```python Python theme={null}
  agentrein.new_session(agent_id: str | None = None, intent: str | None = None) -> Session
  ```
</CodeGroup>

<Info>
  The Python signature takes `agent_id` and `intent` directly as arguments — there is no options-object/string overload like the TypeScript version, and no `await` since Python v1 is synchronous.
</Info>

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `agentId` (Python: `agent_id`) | `string` / `str` | No | Developer-defined identifier for the agent. Defaults to a random UUID. |
| `intent` | `string` / `str` | No | Natural language description of what this session is trying to accomplish. Used by drift detection. |

<Info>
  Agents appear in the dashboard's Agents tab automatically, grouped by `agentId`. Use a stable, descriptive `agentId` (for example `billing-agent`) so all of an agent's sessions are grouped together. If you omit `agentId`, a random ID is generated for every session and those sessions are grouped under a single "Unidentified sessions" entry. To add a display name and description to an agent, open it in the dashboard and choose "Claim / Add details". The agentId is case-sensitive: "Billing-Agent" and "billing-agent" are treated as two different agents.
</Info>

## Returns

<CodeGroup>
  ```ts TypeScript theme={null}
  interface Session {
    id: string;
    organizationId: string;
    agentId: string;
    intent: string | null;
    status: string;
    isSandbox: boolean;
    createdAt: string;
    updatedAt: string;
  }
  ```

  ```python Python theme={null}
  @dataclass
  class Session:
      id: str
      organization_id: str
      agent_id: str
      intent: str | None
      status: str
      is_sandbox: bool
      created_at: str
      updated_at: str
  ```
</CodeGroup>

## Example

<CodeGroup>
  ```ts TypeScript theme={null}
  const session = await agentrein.newSession({
    agentId: 'billing-agent',
    intent: 'Create an invoice for customer cus_xxx and notify them on Slack',
  });
  ```

  ```python Python theme={null}
  session = agentrein.new_session(
      agent_id="billing-agent",
      intent="Create an invoice for customer cus_xxx and notify them on Slack",
  )
  ```
</CodeGroup>

<Warning>
  `newSession()` / `new_session()` must always be awaited (TypeScript) and will throw/raise `AgentReinUnavailableError` if authentication with the AgentRein server fails (e.g. invalid API key, server down during token exchange). If auth succeeds but session creation fails due to a network error, an `AxiosError` (TypeScript) or `httpx.HTTPError` (Python) is thrown/raised. A session is required for subsequent `wrap()` and `completeSession()`/`complete_session()` calls.
</Warning>


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