Python SDK Observability

This page is for Python developers. You learn how tracing works in the armoriq-sdk package, which options and environment variables control it, and which session calls are optional. The SDK builds one OpenTelemetry trace for each session, and sends it to ArmorIQ without telemetry code in your agent.

Install

You need an organization-scoped ArmorIQ API key. The SDK supports Python 3.10 to 3.13.

python -m pip install "armoriq-sdk==0.8.17"

Install an extra for the framework that you use: armoriq-sdk[langchain], armoriq-sdk[strands], or armoriq-sdk[google-adk]. The import package is armoriq_sdk. The OpenTelemetry packages that the SDK needs (opentelemetry-*, version 1.27 up to, but not including, 2) install with it.

Default setup

Tracing is on by default. With a framework adapter you add no tracing code. See Set up tracing for a complete example and Framework support for tested versions.

import os
from armoriq_sdk import ArmorIQClient
from armoriq_sdk.integrations.langchain import ArmorIQLangChain

armoriq = ArmorIQLangChain(
    armoriq_client=ArmorIQClient(api_key=os.environ["ARMORIQ_API_KEY"]),
    mode="sdk",
)
handler = armoriq.for_user("alice@example.com", goal=user_message)
agent_executor.invoke({"input": user_message}, config={"callbacks": [handler]})

Creating an ArmorIQClient also patches the openai and anthropic packages, so that direct calls are traced while a session is active.

Use a session without an adapter

If you call the session API yourself, the session is also the trace. Use it as a context manager. When the block ends, the SDK ends the trace and sends the spans.

from armoriq_sdk import ArmorIQClient, ReportOptions, SessionOptions

client = ArmorIQClient(api_key=os.environ["ARMORIQ_API_KEY"], agent_id="crm-assistant")

tool_name = "crm-mcp__search_contacts"
tool_input = {"query": "Acme"}

with client.start_session(SessionOptions(mode="sdk")) as session:
    session.start_plan(
        [{"name": tool_name, "args": tool_input}],
        goal="Find contacts at Acme",
    )
    decision = session.check(tool_name, tool_input)
    if decision.allowed:
        result = run_the_tool(tool_name, tool_input)
        session.report(tool_name, tool_input, result, ReportOptions(status="success"))

• start_plan(), check(), and report() add the plan, policy, and tool spans for you.
• If the block raises, the trace ends with status error. Otherwise it ends with ok.
• Close the session before you close the client.
• You can call session.close() or session.dispose() instead of the with block. Both are safe to call more than once and never raise.

Optional session calls

None of these calls changes a policy decision. They never raise into your code.

Options

Pass ObservabilityOptions to ArmorIQClient(observability=...).

from armoriq_sdk import ArmorIQClient, ObservabilityOptions

client = ArmorIQClient(
    api_key=os.environ["ARMORIQ_API_KEY"],
    observability=ObservabilityOptions(capture_mode="metadata"),
)

A local capture_mode can only lower what the organization allows. It can never raise it. See Organization controls.

Environment variables

The armoriq export ignores the OTEL_EXPORTER_OTLP_* variables. Only external export reads them. Header values use URL encoding. The full rules for endpoints and headers are in Choose who exports your traces.

What the SDK records

The SDK adds these spans without code from you:

See What data is captured for fields and Data model for the attributes.

How it behaves

• The SDK reads your organization policy first. It fetches the capture policy with your API key. The first span waits for the answer for up to 5 seconds. If the policy is not available, the SDK records nothing until it is.
• Failures are fail-open. A tracing error never changes an allow, hold, or block result, and never raises into your code.
• Closing is bounded. close() makes one final send with a limit of 3 seconds.
• No silent fallback. If an external endpoint is missing or invalid, the SDK exports nothing and logs why. It does not use localhost or ArmorIQ instead.
• Concurrent requests stay apart. The SDK keeps context separate for each task and thread.

Next steps

• Set up tracing
• Choose who exports your traces
• Troubleshoot missing traces