Docs/Getting Started/Installation

Installation

Pick the SDK for your language. If you already use OpenTelemetry, you do not need an ANTS package at all: point your OTLP exporter at ANTS Platform (see OpenTelemetry (OTLP)).

Requirements

SDK	Requirement
Python	Python 3.9 or later. The CrewAI integration needs Python 3.10 to 3.13.
JavaScript / TypeScript	Node.js 20 or later
Java	See Java SDK

Python

bash

pip install ants-platform

Optional extras install the libraries an integration needs:

Extra	Installs	Use it with
`ants-platform[openai]`	`openai`	`from ants_platform.openai import openai` (traced drop-in for the OpenAI SDK)
`ants-platform[langchain]`	`langchain`	`from ants_platform.langchain import CallbackHandler`
`ants-platform[crewai]`	`crewai`	`from ants_platform.crewai import EventListener`

bash

pip install "ants-platform[openai]" # or with Poetry poetry add ants-platform

The package also installs the OpenTelemetry API, SDK and OTLP/HTTP exporter it uses to send data.

CrewAI without code changes

With the [crewai] extra installed, set these variables and run your crew as usual. The SDK instruments CrewAI when Python starts.

bash

export ANTS_AUTO_INSTRUMENT=1 export ANTS_AGENT_NAME="research_crew" # optional; defaults to the crew class export ANTS_AGENT_DISPLAY_NAME="Research Crew" # optional

See CrewAI.

JavaScript / TypeScript

bash

npm install ants-platform @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http # or pnpm add ants-platform @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-http

ants-platform bundles the packages below. You can also install them one by one.

Package	Contents
`@antsplatform/tracing`	`startObservation`, `startActiveObservation`, `observe`, `updateActiveTrace`, `updateActiveObservation`
`@antsplatform/otel`	`AntsPlatformSpanProcessor`, which exports spans to ANTS Platform
`@antsplatform/client`	`AntsPlatformClient` for prompts, datasets, scores and media
`@antsplatform/openai`	`observeOpenAI`, which wraps an OpenAI client
`@antsplatform/langchain`	`CallbackHandler` for LangChain

Install openai or @langchain/core yourself if you use those integrations.

typescript

const provider = new NodeTracerProvider({ spanProcessors: [new AntsPlatformSpanProcessor()], }); provider.register(); setAntsPlatformTracerProvider(provider);

Java

The Java SDK is published to Maven Central as ai.agenticants:ants-platform-java. Use the latest version listed there. See Java SDK.

Configuration

The SDKs read their settings from environment variables. Constructor options override them.

Python

Variable	Default	Purpose
`ANTS_PLATFORM_PUBLIC_KEY`	none	Project public key (`pk-ap-...`)
`ANTS_PLATFORM_SECRET_KEY`	none	Project secret key (`sk-ap-...`)
`ANTS_PLATFORM_HOST`	`https://api.agenticants.ai`	Your ANTS Platform host. Always set it.
`ANTS_PLATFORM_TRACING_ENVIRONMENT`	`default`	Environment, in lowercase
`ANTS_PLATFORM_RELEASE`	none	Release or version of your application
`ANTS_PLATFORM_SAMPLE_RATE`	`1.0`	Share of traces to send, from 0 to 1
`ANTS_PLATFORM_TRACING_ENABLED`	`true`	Set to `false` to turn tracing off
`ANTS_PLATFORM_DEBUG`	`false`	Verbose logging
`ANTS_PLATFORM_TIMEOUT`	`5`	Request timeout in seconds
`ANTS_PLATFORM_FLUSH_AT`	OpenTelemetry default	Spans per batch
`ANTS_PLATFORM_FLUSH_INTERVAL`	OpenTelemetry default	Seconds between batches
`ANTS_PLATFORM_MEDIA_UPLOAD_ENABLED`	`true`	Upload images and files found in traces
`ANTS_PLATFORM_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED`	`true`	Capture arguments and return values in `@observe`

The matching constructor options are public_key, secret_key, host, environment, release, sample_rate, tracing_enabled, debug, timeout, flush_at and flush_interval. Other options include mask (a function that redacts data before it is sent) and blocked_instrumentation_scopes.

JavaScript / TypeScript

Variable	Default	Purpose
`ANTS_PLATFORM_PUBLIC_KEY`	none	Project public key
`ANTS_PLATFORM_SECRET_KEY`	none	Project secret key
`ANTS_PLATFORM_BASE_URL`	`https://api.agenticants.ai`	Your ANTS Platform host. Always set it.
`ANTS_PLATFORM_TRACING_ENVIRONMENT`	none (stored as `default`)	Environment, in lowercase
`ANTS_PLATFORM_RELEASE`	none	Release of your application
`ANTS_PLATFORM_TIMEOUT`	`5`	Export timeout in seconds
`ANTS_PLATFORM_FLUSH_AT`, `ANTS_PLATFORM_FLUSH_INTERVAL`	SDK defaults	Batching

⚠

The JS/TS SDK reads ANTS_PLATFORM_BASE_URL, not ANTS_PLATFORM_HOST. The matching option on AntsPlatformSpanProcessor and AntsPlatformClient is baseUrl.

AntsPlatformSpanProcessor also accepts agent, environment, release, mask, shouldExportSpan, additionalHeaders and exportMode (batched or immediate; use immediate in serverless functions).

Verify the installation

python

from ants_platform import AntsPlatform ants = AntsPlatform() print(ants.auth_check()) # True when the keys and host are correct

auth_check() blocks while it calls the API. Use it while setting up, not on every request. To check the installed version: pip show ants-platform.

Upgrading

bash

pip install --upgrade ants-platform npm install ants-platform@latest

Troubleshooting

Problem	Fix
`pip` cannot find a CrewAI version	The `[crewai]` extra needs Python 3.10 to 3.13.
`ModuleNotFoundError: ants_platform`	Install into the same virtual environment that runs your code. The import name uses an underscore: `ants_platform`.
JS: `Cannot find module '@opentelemetry/...'`	Install the OpenTelemetry packages listed above.
Requests time out behind a proxy	Allow outbound HTTPS to your ANTS Platform host.
Data goes to the wrong place	Set `ANTS_PLATFORM_HOST` (Python) or `ANTS_PLATFORM_BASE_URL` (JS/TS).

Next steps

Authentication: manage keys safely.
Quick Start: send your first trace.
Python SDK and JS/TS SDK: full reference.