agentid-sdk 0.1.12

Enterprise Python SDK for AI guardrails, PII protection, and telemetry logging.

agentid-sdk (Python)

1. Introduction

agentid-sdk is the official Python SDK for AgentID, an AI security and compliance System of Record. It lets you enforce guardrails before model execution, capture immutable telemetry for auditability, and integrate security checks into OpenAI and LangChain workflows with minimal code.

2. Installation

pip install agentid-sdk

Optional extras:

pip install "agentid-sdk[pii]"
pip install "agentid-sdk[security]"

3. Prerequisites

1. Create an AgentID account at https://app.getagentid.com.
2. Create an AI system and copy:
   • AGENTID_API_KEY (for example sk_live_...)
   • AGENTID_SYSTEM_ID (UUID)
3. If using OpenAI/LangChain, set:
   • OPENAI_API_KEY

export AGENTID_API_KEY="sk_live_..."
export AGENTID_SYSTEM_ID="00000000-0000-0000-0000-000000000000"
export OPENAI_API_KEY="sk-proj-..."

4. Quickstart

import os
from agentid import AgentID

agent = AgentID()  # auto-loads AGENTID_API_KEY
system_id = os.environ["AGENTID_SYSTEM_ID"]

verdict = agent.guard(
    input="Summarize this support ticket.",
    system_id=system_id,
    model="gpt-4o-mini",
    user_id="quickstart-user",
)
if not verdict.get("allowed", False):
    raise RuntimeError(f"Blocked: {verdict.get('reason')}")

agent.log(
    system_id=system_id,
    input="Summarize this support ticket.",
    output="Summary generated.",
    model="gpt-4o-mini",
    event_id=verdict.get("client_event_id"),
    metadata={"agent_role": "support-assistant"},
)
print("Guard allowed + telemetry logged")

5. Core Integrations

OpenAI Wrapper

import os
from openai import OpenAI
from agentid import AgentID, SecurityBlockError

agent = AgentID(pii_masking=True)
openai = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
secured = agent.wrap_openai(
    openai,
    system_id=os.environ["AGENTID_SYSTEM_ID"],
    user_id="customer-123",
)

try:
    response = secured.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "What is the capital of the Czech Republic?"}],
    )
    print(response.choices[0].message.content)
except SecurityBlockError as exc:
    print("Blocked by AgentID:", exc.reason)

LangChain Integration

pip install agentid-sdk openai langchain langchain-openai

import os
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI
from agentid import AgentID, AgentIDCallbackHandler

agent = AgentID()
handler = AgentIDCallbackHandler(agent, system_id=os.environ["AGENTID_SYSTEM_ID"])

prompt = PromptTemplate.from_template("Answer in one sentence: {question}")
model = ChatOpenAI(model="gpt-4o-mini", api_key=os.environ["OPENAI_API_KEY"])
chain = prompt | model | StrOutputParser()

result = chain.invoke(
    {"question": "What is the capital of the Czech Republic?"},
    config={"callbacks": [handler]},
)
print(result)

Raw Ingest API (Telemetry Only)

import os
from agentid import AgentID

agent = AgentID()
agent.log(
    system_id=os.environ["AGENTID_SYSTEM_ID"],
    event_type="complete",
    severity="info",
    model="gpt-4o-mini",
    input="Raw telemetry prompt",
    output='{"ok": true}',
    metadata={"agent_role": "batch-worker", "channel": "manual_ingest"},
)

6. Advanced Configuration

Custom identity / role metadata

Use user_id for actor identity and metadata for additional context (for example agent_role, environment, trace IDs).

verdict = agent.guard(
    input="Process user request",
    system_id=system_id,
    user_id="service:billing-agent",
)
agent.log(
    system_id=system_id,
    input="Process user request",
    output="Done",
    model="gpt-4o-mini",
    metadata={"agent_role": "billing-agent", "environment": "prod"},
)

Timeouts

agent = AgentID(
    guard_timeout_s=10.0,
    ingest_timeout_s=10.0,
    strict_mode=True,  # fail-closed on connectivity/timeouts
)

Error handling behavior

• guard() returns a verdict (allowed, reason); handle deny paths explicitly.
• Wrapped OpenAI/LangChain flows raise SecurityBlockError when AgentID blocks execution.
• guard() is fail-open by default for connectivity/timeouts (timeout_fallback, guard_unreachable, system_failure_fail_open).
• If strict_mode is not explicitly set in SDK code, runtime behavior follows the system configuration from AgentID (strict_security_mode / failure_mode).
• Set strict_mode=True to fail-closed (network_error_strict_mode / server_error) for high-sensitivity workloads.
• Ingest retries transient failures (5xx/429) and logs warnings if persistence fails.

7. Security & Compliance

• Optional local-first reversible PII masking via PIIManager and pii_masking=True.
• Prompt-injection scanning and policy enforcement run before model dispatch.
• Telemetry logging is async/fire-and-forget to minimize app latency.
• Designed for server, serverless, and background-worker runtimes.
• Supports compliance workflows requiring complete prompt/output traceability.

8. Support

• Dashboard: https://app.getagentid.com
• Repository: https://github.com/ondrejsukac-rgb/agentid/tree/main/python-sdk
• Issues: https://github.com/ondrejsukac-rgb/agentid/issues

9. Publishing Notes (PyPI)

PyPI renders this README.md as package long description.

setup.py projects

from setuptools import setup

with open("README.md", "r", encoding="utf-8") as fh:
    long_description = fh.read()

setup(
    name="agentid-sdk",
    long_description=long_description,
    long_description_content_type="text/markdown",
)

pyproject.toml projects

readme = { file = "README.md", content-type = "text/markdown" }