Atlas SDK

Beta Python and TypeScript clients for Atlas chat sessions.

The Atlas SDK is in beta. Methods, payloads, and behavior may change as we work with your team.

The Atlas SDK is a typed client for Atlas chat. Create a session, send a message, and stream events until the run completes.

Python package: arena-physica-atlas (atlas_sdk). TypeScript package: @arena-physica/atlas. Your Arena Physica point of contact will get you set up.

​

Get credentials

The default is M2M: a client ID and client secret. Ask your Arena Physica point of contact for credentials for your Atlas environment. You will be asked to provide the user groups those credentials can access.

Treat the client secret like a password. Keep it in server-side env or a secret store — not in git, and not in a browser or mobile app.

A Bearer token (token / api_key) is also supported. Do not set a token and M2M credentials together.

​

Authenticate

	Python	TypeScript	Env
Client ID	client_id	clientId	ATLAS_CLIENT_ID
Client secret	client_secret	clientSecret	ATLAS_CLIENT_SECRET
Token (optional)	token or api_key	token or apiKey	ATLAS_TOKEN

If you omit constructor credentials, the SDK reads those env vars. Explicit arguments win over env.

M2M credentials are exchanged for an access token (/desktop-config, then Auth0 client_credentials). The client secret is never sent as a Bearer token.

​

Create a client

base_url / baseUrl can be a host (your-atlas-domain) or a full URL. The SDK adds https:// and /api/v1 only when you omit them. Any other path is kept.

​

Python

from atlas_sdk import Atlas

async def main() -> None:
    async with Atlas(
        base_url="https://your-atlas-domain",
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
    ) as atlas:
        session = await atlas.sessions.create()
        sent = await atlas.sessions.send_message(
            session_id=session.id,
            content="Why did this test fail?",
        )
        async for event in atlas.sessions.stream(
            session_id=session.id,
            message_id=sent.message_id,
        ):
            if event.type == "message.delta":
                print(event.delta, end="", flush=True)

​

TypeScript

import { Atlas } from '@arena-physica/atlas'

const atlas = new Atlas({
  baseUrl: 'https://your-atlas-domain',
  clientId: process.env.ATLAS_CLIENT_ID,
  clientSecret: process.env.ATLAS_CLIENT_SECRET,
})

const session = await atlas.sessions.create()
const sent = await atlas.sessions.sendMessage({
  sessionId: session.id,
  content: 'Why did this test fail?',
})

for await (const event of atlas.sessions.stream({
  sessionId: session.id,
  messageId: sent.messageId,
})) {
  if (event.type === 'message.delta') {
    process.stdout.write(event.delta)
  }
}

send_message / sendMessage returns immediately with a message_id. Completion arrives on the stream as run.completed or run.failed.

​

Bearer token

Use this instead of M2M when you already have a user access token. Do not pass token / apiKey together with client_id / clientId.

async with Atlas(
    base_url="https://your-atlas-domain",
    api_key="YOUR_TOKEN",
) as atlas:
    ...

const atlas = new Atlas({
  baseUrl: 'https://your-atlas-domain',
  apiKey: process.env.ATLAS_TOKEN,
})

​

Operations

Python uses snake_case. TypeScript uses camelCase.

Python	TypeScript	HTTP	Path	Purpose
sessions.create	sessions.create	POST	/chat/v2/sessions	Start a chat session
sessions.send_message	sessions.sendMessage	POST	/chat/v2/sessions/{session_id}/messages	Send a message and get message_id
sessions.stream	sessions.stream	GET	/chat/v2/sessions/{session_id}/messages/{message_id}/events	Stream events for that message

create takes no arguments. send_message / sendMessage takes the message text.

​

Events

Every event includes session_id and message_id.

Type	Extra fields	When
run.started		The turn begins
message.started		Assistant text is about to stream
message.delta	delta	Incremental assistant text
reasoning.delta	delta	Incremental reasoning text
tool.started	tool_id, name	A tool call starts
tool.completed	tool_id, error	A tool call finishes
message.completed	content	Full assistant text
run.completed		The turn succeeded
run.failed	error	The turn failed

Ignore unknown event types so later additions do not break your client.

​

Env-only configuration

export ATLAS_CLIENT_ID="..."
export ATLAS_CLIENT_SECRET="..."
# or a user token
export ATLAS_TOKEN="..."

async with Atlas(base_url="your-atlas-domain") as atlas:
    ...

const atlas = new Atlas({ baseUrl: 'your-atlas-domain' })

​

Errors

Missing or mixed credentials raise AtlasAuthError (token and M2M together, or only one of client id / secret).

HTTP failures raise from the underlying client (httpx in Python; Error in TypeScript).

​

Related

• Authentication and Configuration
• Agentic API