New Session

Signature

agentrein.newSession(options?: SessionOptions | string): Promise<Session>

agentrein.new_session(agent_id: str | None = None, intent: str | None = None) -> Session

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.

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.

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.

Returns

interface Session {
  id: string;
  organizationId: string;
  agentId: string;
  intent: string | null;
  status: string;
  isSandbox: boolean;
  createdAt: string;
  updatedAt: string;
}

@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

Example

const session = await agentrein.newSession({
  agentId: 'billing-agent',
  intent: 'Create an invoice for customer cus_xxx and notify them on Slack',
});

session = agentrein.new_session(
    agent_id="billing-agent",
    intent="Create an invoice for customer cus_xxx and notify them on Slack",
)

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.

Getting Started

SDK Reference

Signature

Parameters

Returns

Example

​Signature

​Parameters

​Returns

​Example

Signature

Parameters

Returns

Example