Quick Start Guide

Get Saf3AI integrated with your AI agents in just a few minutes. This guide covers the fastest path to protection.

Prerequisites

• Python 3.9+
• An existing AI application using Google ADK, LangChain, or a custom framework
• A Saf3AI account (contact us)

Step 1: Install the SDK

pip install saf3ai-sdk

Step 2: Set Environment Variables

Create a .env file in your project root:

SAF3AI_COLLECTOR_AGENT=https://your-collector-endpoint.com
SAF3AI_SERVICE_NAME=my-agent
SAF3AI_API_KEY=your-api-key-here
SAF3AI_API_KEY_HEADER=X-API-Key
SAF3AI_API_ENDPOINT=https://your-scanner-endpoint.com

Step 3: Initialize the SDK

import os
from dotenv import load_dotenv
from saf3ai_sdk import init

# Load environment variables
load_dotenv()

# Initialize SDK
init(
    service_name=os.getenv("SAF3AI_SERVICE_NAME", "my-agent"),
    framework="adk",  # Use "adk" for Google ADK or "langchain" for LangChain
    agent_id="unique-agent-id",
    api_key=os.getenv("SAF3AI_API_KEY"),
    api_key_header_name=os.getenv("SAF3AI_API_KEY_HEADER", "X-API-Key"),
    safeai_collector_agent=os.getenv("SAF3AI_COLLECTOR_AGENT"),
)

Important: Call init() once at the start of your application, before creating any agents or LLMs.

Step 4: Define a Security Policy

def security_policy(text: str, scan_results: dict, text_type: str) -> bool:
    """
    Return True to allow, False to block.
    """
    detections = scan_results.get("detection_results", {})
    
    # Block if any threat is found
    for threat_type, result in detections.items():
        if result.get("result") == "MATCH_FOUND":
            return False
    
    return True

Step 5: Create Security Callback

For Google ADK

from saf3ai_sdk import create_security_callback
from google.adk.agents import LlmAgent

# Create security callback
security_callback = create_security_callback(
    api_endpoint=os.getenv("SAF3AI_API_ENDPOINT"),
    on_scan_complete=security_policy,
    scan_responses=True,
)

# Create ADK agent with callback
agent = LlmAgent(
    name="my_agent",
    model="gemini-2.5-flash",
    before_model_callback=security_callback,
)

# Use agent
response = agent.run("Hello, how are you?")

For LangChain

from saf3ai_sdk.langchain_callbacks import create_security_callback
from langchain.chat_models import ChatOpenAI
from langchain.chains import ConversationChain

# Create security callback
security_callback = create_security_callback(
    api_endpoint=os.getenv("SAF3AI_API_ENDPOINT"),
    on_scan_complete=security_policy,
    scan_responses=True,
)

# Create LangChain chain with callback
chat = ChatOpenAI(
    openai_api_key=os.getenv("OPENAI_API_KEY"),
    callbacks=[security_callback],
)

chain = ConversationChain(llm=chat)

# Use chain with error handling
try:
    response = chain.run("Hello, how are you?")
except ValueError as e:
    if "cannot assist" in str(e).lower():
        print("Request blocked by security policy")
    else:
        raise

Step 6: View in Dashboard

Once integrated, head to your Saf3AI Dashboard to see:

• Real-time traces of all AI interactions
• Security alerts and blocked threats
• Token usage and cost breakdown
• Performance metrics

What’s Next?

Now that you have basic security set up, explore more features:

• Enable Security Rules - Block prompt injection and data leakage
• Set Up Alerts - Get notified of anomalies
• LangChain Integration - Deep integration with LangChain
• Google ADK Integration - Native Google ADK support
• Custom Frameworks - Build your own integration

Troubleshooting

SDK not initializing

• Check all environment variables are set in .env file
• Verify .env file is in project root
• Ensure load_dotenv() is called before init()

Callbacks not working

• Verify SDK is initialized before creating callbacks
• Check that framework parameter matches your framework (“adk” or “langchain”)
• Verify callbacks are added to agent/chain before invocation

Need help?

• Check our FAQ
• Email info@saf3ai.com