Docs/Guides

Guides & Tutorials

These guides walk through real tasks with the ANTS Platform Python SDK (ants-platform). Each one uses only shipped SDK calls and points you to the screens where the results show up.

Start here

Monitor Your First Agent

Install the SDK, trace a small agent end to end, and find the trace in the product.

Debugging AI Agents

Fix missing traces, record errors, find slow steps and turn failures into test cases.

Production Best Practices

Configure environments, sampling, masking and flushing for production services.

Multi-Agent Systems

Trace collaborating agents.

RAG System Monitoring

Trace retrieval and generation steps.

Cost Optimization

Find and reduce AI spend.

Before you start

Every guide assumes the SDK is installed and configured from environment variables.

bash
pip install ants-platform export ANTS_PLATFORM_PUBLIC_KEY="pk-ap-..." export ANTS_PLATFORM_SECRET_KEY="sk-ap-..." export ANTS_PLATFORM_HOST="https://<your-host>"

Create the key pair under Settings > API Keys in your project. The host is the URL of your ANTS Platform app. See API Keys.

⚠

The Python SDK requires an agent_name on the outermost observation of every trace. Open each unit of work with start_as_current_observation(..., as_type="agent", agent_name="..."). Nested observations, @observe() functions and OpenAI drop-in calls inside it inherit the agent name. Without one, the SDK raises ValueError: agent_name is required.

Choose an integration path

PathUse it whenDocs
Python SDK, manual observationsYou want full control over spans, generations and toolsPython SDK
OpenAI drop-in (ants_platform.openai)Your code calls the OpenAI clientPython SDK
LangChain CallbackHandlerYou run LangChain chains or agentsLangChain
CrewAI EventListenerYou run CrewAI crewsCrewAI
OpenTelemetry (OTLP)You already emit OpenTelemetry spansSending Data In

For JavaScript, TypeScript or Java, see the JS/TS SDK and Java SDK pages.

LangChain

python
from ants_platform import AntsPlatform from ants_platform.langchain import CallbackHandler from langchain_openai import ChatOpenAI AntsPlatform() handler = CallbackHandler() llm = ChatOpenAI(model="gpt-4o-mini") llm.invoke( "Say hello", config={ "callbacks": [handler], "metadata": { "ants_platform_agent_name": "hello-agent", "ants_platform_user_id": "demo-user", "ants_platform_session_id": "demo-session", }, }, )

CrewAI

python
from ants_platform import AntsPlatform from ants_platform.crewai import EventListener ants = AntsPlatform() listener = EventListener() result = crew.kickoff() ants.flush()

OpenTelemetry

Point any OTLP/HTTP exporter at https://<your-host>/api/public/otel/v1/traces with an Authorization: Basic <base64(public_key:secret_key)> header. See Sending Data In.

Common patterns

The patterns below assume a client configured from environment variables.

Request and response logging

python
from ants_platform import get_client ants = get_client() def answer(question: str) -> str: with ants.start_as_current_observation( name="answer", as_type="agent", agent_name="support-agent", input=question ) as span: try: output = agent.process(question) except Exception as error: span.update(level="ERROR", status_message=str(error)) raise span.update(output=output) return output

Multi-step workflow

python
from ants_platform import get_client, observe ants = get_client() @observe(name="extract") def extract(query): return step1(query) @observe(name="summarize") def summarize(data): return step2(data) def workflow(query, user_id): with ants.start_as_current_observation( name="workflow", as_type="agent", agent_name="workflow", input=query ) as root: root.update_trace(user_id=user_id, tags=["workflow"]) result = summarize(extract(query)) root.update(output=result) return result

Retries

python
from ants_platform import get_client ants = get_client() def with_retry(operation, attempts=3): with ants.start_as_current_observation(name="retry-operation", as_type="span") as span: for attempt in range(1, attempts + 1): try: result = operation() span.update(output=result, metadata={"attempts": attempt}) return result except Exception as error: if attempt == attempts: span.update( level="ERROR", status_message=str(error), metadata={"attempts": attempt}, ) raise span.update(level="WARNING", status_message=f"attempt {attempt} failed: {error}") time.sleep(attempt)

Call with_retry inside an agent observation so it inherits the agent name.

Where results show up

What you want to seeWhere in the product
Individual traces and their observation treeDiscover AI > Tracing (Traces)
Multi-turn conversations grouped by session_idDiscover AI > Sessions (Sessions)
Spend by model and userGauge AI > Cost Dashboard (Cost & Latency Dashboards)
p95 and p99 latency by modelGauge AI > Latency Dashboard
Usage trendsGauge AI > AI Usage (AI Usage)
Cost and performance per modelGauge AI > Cost Performance Metrics and Latency & Analytics (Cost & Performance Metrics)
Cheaper model recommendationsGauge AI > AI Optimizer (AI Optimizer)
Your own chartsCustom Dashboards

Next steps

© 2026 ANTS Platform, Inc.Docs v1.0 · Last updated June 2026