arkna 4.0.0

Official Python SDK for Arkna — AI agent evidence

arkna

Official Python SDK for ARKNA — AI agent observability and incident intelligence.

ARKNA records every run, step, and tool call your AI agents make, with full context and hash-chained integrity. When something goes wrong, replay the exact run and see what the agent knew at each step.

Installation

pip install arkna

With framework extras:

pip install arkna[langchain]    # LangChain integration
pip install arkna[crewai]       # CrewAI integration
pip install arkna[autogen]      # AutoGen integration

Quick Start

Auto-instrumentation (recommended)

Two lines. All OpenAI and Anthropic calls are captured automatically.

from arkna import init

init(api_key="ark_live_...", agent_name="my-agent")

# Your existing code — no changes needed
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
# ^ This call is automatically recorded by ARKNA

Or via environment variables (no code changes at all):

export ARKNA_API_KEY=ark_live_...
export ARKNA_AGENT_NAME=my-agent

from arkna import init
init()

Manual instrumentation

For full control over what gets recorded:

from arkna import ArknaClient

client = ArknaClient(api_key="ark_live_...", agent_name="my-agent")

run = client.start_run(trigger_type="api", input={"query": "refund policy"})

client.record_step(run["run_id"],
    step_type="reasoning",
    input="User asked about refund policy",
    output="Found 3 relevant documents",
)

client.record_tool_call(run["run_id"],
    tool_name="search_docs",
    input={"query": "refund"},
    output={"results": 3},
    status="success",
)

client.complete_run(run["run_id"], status="completed")

Framework Integrations

LangChain

from arkna import init, ArknaLangChainHandler

init(api_key="ark_live_...", agent_name="my-langchain-agent")
handler = ArknaLangChainHandler()

# Pass as callback to any LangChain chain/agent
result = chain.invoke({"input": "hello"}, config={"callbacks": [handler]})

CrewAI

from arkna import init, ArknaCrewAIHandler

init(api_key="ark_live_...", agent_name="my-crew")
handler = ArknaCrewAIHandler()

AutoGen

from arkna import init, ArknaAutoGenHandler

init(api_key="ark_live_...", agent_name="my-autogen-team")
handler = ArknaAutoGenHandler()

Configuration

Environment Variable	Description
ARKNA_API_KEY	API key (ark_live_...)
ARKNA_AGENT_NAME	Agent name for identification
ARKNA_URL	API endpoint (default: https://api.arkna.com.au)

Requirements

• Python >= 3.9
• requests >= 2.28

License

MIT