SDK and CLI: How to Instrument and Operate AI Agents with TuringPulse

Instrument, Then Operate

Running AI agents in production requires two distinct capabilities: getting telemetry in, and making sense of that telemetry once it is flowing. TuringPulse separates these concerns cleanly into two tools.

The SDK (Python and TypeScript) is how telemetry gets into TuringPulse. It instruments your agent code — auto-capturing traces, spans, token counts, cost, latency, KPIs, governance decisions, and workflow fingerprints — with minimal code changes. You write agent logic; the SDK handles observability.

The CLI is how you interact with that data after it is flowing. It provides fast, terminal-native access to runs, traces, drift events, anomalies, governance policies, evaluation configs, and alert channels. It does not send traces. It reads, queries, and manages.

These are not competing tools. They are two halves of the same workflow: the SDK is what you put in your agent code, the CLI is what you reach for when you need answers from the terminal.

The SDK: Instrument Your Agents

The SDK is the fastest path from zero to full observability. Install the core package and the framework plugin for your stack, call init(), and every LLM call, tool invocation, and agent step is instrumented automatically.

Python

pip install turingpulse-sdk turingpulse-sdk-openai

from turingpulse_sdk import init, instrument, KPIConfig

init(api_key="sk_...", workflow_name="support-agent")

@instrument(
    name="Support Agent",
    kpis=[KPIConfig(kpi_id="latency_ms", use_duration=True)],
)
async def handle_request(query: str) -> dict:
    ...

TypeScript

npm install @turingpulse/sdk @turingpulse/sdk-openai

import { init, withInstrumentation } from '@turingpulse/sdk';

init({ apiKey: 'sk_...', workflowName: 'support-agent' });

const handleRequest = withInstrumentation(
  async (query: string) => { ... },
  { name: 'Support Agent' }
);

What the SDK Handles

• Traces and spans — every LLM call, tool invocation, and agent step, automatically
• Token counting and cost estimation — prompt/completion tokens and estimated USD cost per call
• Latency — wall-clock duration for every span
• Batching and transport — events batched, compressed, and sent with retries and backoff
• KPI tracking — declarative KPI configs via the @instrument decorator
• Governance — HITL/HATL/HOTL review gates via GovernanceDirective
• Fingerprinting — workflow structure fingerprints for change detection
• Deploy tracking — register_deploy() auto-detects CI/CD environment

Enrich Context

Inside any instrumented function, grab the current execution context to attach model metadata, token counts, costs, and tool call details:

from turingpulse_sdk import current_context

ctx = current_context()
ctx.set_tokens(input_tokens=1500, output_tokens=200)
ctx.set_model("gpt-4o", provider="openai")
ctx.set_cost(0.003)
ctx.add_tool_call("search_api", tool_args={"q": query}, tool_result=results)

Framework Plugins

Framework plugins deliver zero-code instrumentation for framework-specific execution patterns. Install the plugin and the SDK captures everything automatically:

19 Python plugins and 12 TypeScript plugins in total. Install turingpulse-sdk-all in Python to get every plugin at once.

The CLI: Explore and Manage

Once telemetry is flowing via the SDK, you need a way to query it, inspect it, and manage the platform around it. That is the CLI. It gives you fast, structured access to everything in TuringPulse from the terminal — without opening a browser.

Installation

pip install turingpulse-cli
tp auth login

Explore Runs and Traces

# List completed runs for a workflow
tp observe runs list --workflow-id support-agent --status completed

# Get details for a specific run
tp observe runs get run-abc-123

# View the full trace tree
tp observe runs trace run-abc-123

# View metrics for a run
tp observe runs metrics run-abc-123

Drift and Anomalies

# List recent drift events
tp observe drift events

# List recent anomaly events
tp observe anomalies events

# View KPI values
tp observe kpis list

Configuration and Governance

# List KPI rules
tp config kpi-rules list

# List drift detection rules
tp config drift-rules list

# List governance policies
tp governance policies list

# List evaluation configs
tp evals configs list

# List alert channels
tp alerts channels list

Every command outputs structured data that pipes into jq, grep, and other Unix tools. The CLI is the tool you reach for when something is wrong in production and you need answers fast.

SDK + CLI: A Real Workflow

Here is how the SDK and CLI work together in a real team's day-to-day:

1. A Developer Instruments the Agent

The developer adds the SDK to the agent code. The @instrument decorator captures traces, spans, token usage, cost, and latency for every execution. KPI configs track latency against a threshold.

from turingpulse_sdk import init, instrument, KPIConfig

init(api_key="sk_...", workflow_name="support-agent")

@instrument(
    name="Support Agent",
    kpis=[
        KPIConfig(kpi_id="latency_ms", use_duration=True, alert_threshold=5000, comparator="gt"),
    ],
)
async def handle_request(query: str) -> dict:
    ...

2. CI/CD Records the Deployment

The pipeline uses register_deploy() to mark the deployment. It auto-detects the git SHA, branch, and environment from CI variables.

from turingpulse_sdk import register_deploy

register_deploy(
    workflow_id="support-agent",
    auto_detect=True,
    metadata={"deployer": "github-actions", "env": "production"},
)

3. An SRE Investigates a Drift Alert

A drift alert fires. The SRE reaches for the CLI to understand what happened — listing drift events, inspecting the specific run, and tracing its full execution tree.

tp observe drift events
tp observe runs get run-abc-123
tp observe runs trace run-abc-123

4. A Team Lead Reviews Governance

The team lead checks that governance policies and KPI rules are correctly configured before a new workflow goes live.

tp governance policies list
tp config kpi-rules list
tp alerts channels list

The SDK and CLI never overlap. The SDK writes telemetry during agent execution. The CLI reads that telemetry and manages platform configuration. A trace created by the SDK is immediately queryable via the CLI. There is no sync delay and no data gap — they operate on the same data plane.

Unsupported Languages: The REST API

If your agent is written in a language without an SDK — Rust, Go, Java, or others — TuringPulse exposes a REST API that accepts the same event schema the SDKs use internally. You can send telemetry via POST /api/v1/sdk/events with an X-API-Key header. Tenant and project are resolved from the key automatically.

The trade-off is significant: the API gives you raw HTTP access, but you handle serialization, batching, retries, trace-span relationships, cost calculation, and error handling yourself. There are no framework plugins, no automatic tracing, no built-in governance enforcement, and no fingerprinting. For Python and TypeScript agents, the SDK is the right choice in every dimension.