saf3ai-sdk 0.2.5

Saf3AI SDK for Python
Observability, security scanning, and data lineage for production AI agents

Overview

saf3ai-sdk is the official Python client for the Saf3AI platform. It combines:

1. Observability — Saf3AI-native tracing with rich attributes (conversation IDs, models, usage, lineage).
2. Security — Integration with the Saf3AI Scanner for prompt and optional response analysis, with policy callbacks.
3. Governance — Automatic capture of data sources (HTTP, tools, DB access) onto traces for audit and compliance workflows.

Call init() once at process startup. The SDK detects your agent framework, configures the Saf3AI TraceProvider, connects to your Saf3AI platform account, and enables framework-aware instrumentation.

Table of contents

• Why use this SDK
• Platform capabilities
• Architecture
• Requirements
• Installation
• Quick start
• Configuration
• Supported frameworks
• Observability conventions
• Security scanning
• Production checklist
• API surface
• Troubleshooting
• Recent changes
• Support & license

Why use this SDK

Platform capabilities

Observability

• Saf3AI TraceProvider owned by the SDK (set during init()).
• Trace delivery to your Saf3AI platform workspace.
• Framework tracers: saf3ai-adk, saf3ai-langchain, saf3ai-crewai, saf3ai-rest.
• Optional console export for local development.

Security

• Prompt scanning and optional response scanning via callbacks or direct helpers.
• Policy hooks return allow/block; results can be attached to traces when enabled.

Data lineage

• HTTP — Outbound request sources can be attached to active traces.
• MCP — Tool and resource usage can be attached as lineage entries.
• Databases — Database operations can be captured for governance and compliance contexts.

Architecture

flowchart TB
  classDef box fill:#f8fbff,stroke:#2b5876,stroke-width:1.5px,color:#0f172a;
  classDef platform fill:#eefbf3,stroke:#1f7a4a,stroke-width:1.5px,color:#0f172a;

  subgraph App["Application Layer"]
    A[Your Agent Experience]
  end

  subgraph SDK["Saf3AI SDK Layer"]
    I[Initialize SDK]
    T[Saf3AI TraceProvider]
    F[Framework Integrations]
    G[Security and Governance Controls]
  end

  subgraph Platform["Saf3AI Platform Layer"]
    P[Unified Saf3AI Platform]
  end

  A --> I
  I --> T
  I --> F
  I --> G
  T --> P
  F --> P
  G --> P

  class A,I,T,F,G box;
  class P platform;

Requirements

Installation

pip install saf3ai-sdk

This command installs the version currently published on PyPI. This checkout prepares 0.2.5; to verify it before publication, install it with pip install -e . and check python -m pip show saf3ai-sdk. Once published, deploy the tested version explicitly with pip install saf3ai-sdk==0.2.5.

Development dependencies (formatting, tests, types):

pip install saf3ai-sdk[dev]

Quick start

Initialize before you construct agents or LLM clients.

import os
from saf3ai_sdk import init, get_detected_framework

init(
    agent_id=os.environ["SAF3AI_AGENT_ID"],
    api_key=os.environ["SAF3AI_API_KEY"],
    safeai_collector_agent=os.environ["SAF3AI_COLLECTOR_AGENT"],
    service_name=os.getenv("SAF3AI_SERVICE_NAME"),
    scanner_endpoint=os.getenv("SAF3AI_SCANNER_ENDPOINT"),
    # Only needed when the policy's registered agent identifier differs from agent_id:
    scanner_agent_identifier=os.getenv("SAF3AI_SCANNER_AGENT_IDENTIFIER"),
)

print(get_detected_framework())  # e.g. "adk", "langchain", "crewai", "openai-agents", "autogen", "bedrock", "custom"

For richer configuration, pass an SDKConfig object into init() (see saf3ai_sdk.config.sdk_config).

Configuration

Required parameters or environment

Security: Never commit API keys. Use secret managers or CI-injected variables in production.

Frequently used optional variables

Example: shell

export SAF3AI_API_KEY="your-key"
export SAF3AI_COLLECTOR_AGENT="https://collector.example.com"
export SAF3AI_SCANNER_ENDPOINT="https://scanner.example.com"
export SAF3AI_AGENT_ID="claims-agent-prod"

Supported frameworks

Detection order: ADK -> CrewAI -> LangChain -> OpenAI Agents -> AutoGen -> Bedrock -> custom.

Install only the stack your service imports; the SDK selects the first matching framework.

Observability conventions

• Traces include standardized Saf3AI metadata such as service.name, saf3ai.sdk.version, and environment.
• Conversation stitching uses gen_ai.conversation.id and conversation_id helpers (get_conversation_id_unified, set_conversation_id_unified, reset_conversation).
• Third-party spans may omit conversation attributes; the SDK aligns them with the unified conversation where possible.

Security scanning

Agent-scoped rules in 0.2.5

An agent-scoped rule matches only when the /scan request includes the exact registered identifier as metadata.agent_identifier. Automatic @traceable prompt and response scans now send it. The value comes from scanner_agent_identifier in init() (default: agent_id); @traceable(agent_identifier="...") overrides it for one decorated agent. Use the registered identifier, not a display name or function name. This is especially important when one process hosts multiple agents.

from saf3ai_sdk import init, traceable

init(
    agent_id="it-service-agent",
    api_key="...",  # Load from a secret manager or environment in production.
    safeai_collector_agent="https://your-collector.example",
    scanner_endpoint="https://your-scanner.example",
    scanner_agent_identifier="registered-policy-id",  # Must exactly match the policy identifier.
)

@traceable(name="it-service")
def answer(prompt: str) -> str:
    return call_your_model(prompt)

Replace the placeholder with the identifier actually registered for your agent, including its exact spelling. In the reported test this was it service agetn; a corrected-looking name would not match that rule. For a multi-agent process, put agent_identifier="..." on each @traceable decorator instead of relying on one process-wide default. Direct scan_prompt() and scan_response() calls still accept metadata={"agent_identifier": "..."}.

Detection and blocking are different. Automatic @traceable scanning records scan results; it does not, by itself, interpret every match as a block. To prevent a prompt reaching the model, register a policy callback that returns False on a block decision. The prompt callback now runs before the decorated function; the response callback runs before its result is returned. A framework adapter callback can scan again, so choose one scan/enforcement path per interaction where possible.

For a custom agent that needs blocking, use create_framework_security_callbacks(framework="custom", agent_identifier=..., on_scan_complete=...) before invoking the decorated function. on_scan_complete(text, scan_results, text_type) should implement your organization's policy and return True to allow or False to block. ADK, LangChain, CrewAI, and REST adapters also support explicit agent identifiers in their callback configuration. Test both a matching rule and a benign prompt before production.

def security_policy(text: str, scan_results: dict, text_type: str) -> bool:
    """text_type is 'prompt' or 'response' where applicable."""
    detections = scan_results.get("detection_results") or {}
    for _, result in detections.items():
        if isinstance(result, dict) and result.get("result") == "MATCH_FOUND":
            return False
    return True

Intentional policy blocks

Intentional policy blocks in custom agents should use the shared SDK exception:

from saf3ai_sdk import PolicyBlocked, traceable

@traceable(name="support-agent")
def answer(prompt: str) -> str:
    if policy_denies(prompt):  # Your application's policy decision.
        raise PolicyBlocked("Request denied by policy", phase="prompt", blocked_by="support-policy")
    return call_your_model(prompt)

Catch PolicyBlocked at the application boundary to return your blocked-request response. Replace any locally defined exception of that name with this import. Both synchronous and asynchronous @traceable functions propagate it while retaining block evidence, without recording a runtime failure. SDK-owned tracing contexts and call_llm_with_saf3ai() follow the same rule. Other exceptions still record errors; matching a threat in Monitor Only does not itself raise PolicyBlocked. When using a third-party tracing context around the SDK, its exception-recording policy remains under that library's control.

Production checklist

• init() called once at cold start, before any tracer-backed client.
• Secrets from environment or vault; never in source control.
• Platform endpoint reachable from runtime network (VPC / egress rules).
• Scanner endpoint and scan flags match organizational policy (prompt-only vs prompt+response).
• Agent identity: capture one /scan request and verify metadata.agent_identifier exactly matches the registered rule identifier for each agent.
• Enforcement: verify that a blocked prompt never enters the model/tool call and a blocked response is never returned to the caller. Automatic scanning alone is observational.
• Failure policy: decide whether a scanner outage should allow or reject requests. Current callback error paths may fail open; test this against your security requirements.
• agent_id / service_name stable per deployment unit for cost and ownership dashboards.
• Log level appropriate (INFO or WARNING in production; DEBUG only when diagnosing).
• Conversation IDs for multi-tenant apps: use explicit session-scoped IDs (reset_conversation() between unrelated chats).

API surface

Full parameter lists and behaviors live in docstrings in saf3ai_sdk/__init__.py and saf3ai_sdk.config.

Troubleshooting

Recent changes

0.2.5 release candidate (publish and deploy separately)

• Agent identity is included in automatic prompt and response scans.
• @traceable prompt-policy callbacks run before agent execution.
• AutoGen and Bedrock automatic scan configuration paths are repaired.
• Public PolicyBlocked preserves intentional block evidence without classifying the rejection as a runtime failure in sync/async decorators, SDK-owned contexts, and the model-call wrapper.
• REST/custom callbacks propagate explicitly raised policy blocks.
• AutoGen accepts generated callback signatures, records completed-scan markers, and enforces response blocks.
• Automatic response scans respect SAF3AI_SCAN_RESPONSES; prompt text and attribute values are no longer printed at INFO level by @traceable.
• Wheel and source archives use core metadata 2.4 for package-tool compatibility.

Local release verification

Run the local regression suite and build both distribution formats before publication:

python -m pytest -q tests
python -m build
python -m twine check dist/*

Tests, caches, and generated packages are intentionally Git-ignored and excluded from distribution archives. Keep the local test suite available in the release workspace; a fresh clone does not include those tests. Release notes remain version-controlled in this README and CHANGELOG.md. The sample-policy checks use mocked scanner/model calls; live framework and scanner validation must be performed against the deployment configuration.

The final local regression run passed 119 tests. Archive-content and installed-wheel smoke checks also verify that the packaged SDK exposes the expected API and reports version 0.2.5. Python 3.9 syntax was checked; the full regression run used Python 3.13 and does not replace runtime checks on your deployment's Python/framework versions.

Support & license

• Issues & features: GitHub Issues
• Email: team@saf3ai.com
• License: MIT

For security-sensitive reports, contact the maintainers directly rather than using public issues until a disclosure process is published.

Saf3AI and the Saf3AI logo are trademarks of their respective owners. This README describes the open-source saf3ai-sdk Python package.