testneo-agent-sdk 0.1.1

TestNeo Agent SDK — emit agent_run_summary.v1 and ingest into TestNeo (framework adapters optional).

TestNeo Agent SDK

Official Python SDK to emit agent_run_summary.v1 and ingest into TestNeo.

Verification (PASS / WARN / BLOCK) stays on the server. This package never implements the gate.

Your agent / framework
      → TestNeo SDK (or thin adapter)
      → agent_run_summary.v1
      → POST ingest
      → TestNeo Verify / Eval

Install

pip install testneo-agent-sdk
# optional: pip install "testneo-agent-sdk[langgraph]"

10-minute generic path

# Production (default in SDK if unset)
export TESTNEO_BASE_URL=https://app.testneo.ai
# Local / self-hosted instead:
# export TESTNEO_BASE_URL=http://127.0.0.1:8001

export TESTNEO_API_KEY=...          # app.testneo.ai → Settings → API Keys
export TESTNEO_PROJECT_ID=15        # your project id

from testneo_agent import TestNeo, refund_policy_v2

sdk = TestNeo.from_env()

with sdk.run(goal="Refund order 430") as run:
    run.authorization("READ_WRITE")
    cid = run.tool_called("search_policy_kb", operation="READ", target="policy_refund_v2")
    run.retrieval(
        doc_id="policy_refund_v2",
        snippet="Full refunds only within 30 days of purchase.",
        score=0.88,
        emit_action=False,
    )
    run.tool_completed(call_id=cid, result_summary="matched policy_refund_v2")
    run.confirmation(True)
    run.set_gate_contract(refund_policy_v2(order_id=430))
    run.set_claim("Full refund within 30 days per policy v2.")
# __exit__ builds summary + ingests (TESTNEO_AUTO_INGEST=true by default)

Then open Agent Verification → Verify and select the ingested run.

Framework adapters (P0)

Thin translators only — no HTTP, no gate logic.

Adapter	Import
Generic	from testneo_agent.adapters import GenericAdapter
LangGraph / LangChain	from testneo_agent.adapters import LangGraphAdapter
CrewAI	from testneo_agent.adapters import CrewAIAdapter
AutoGen / AG2	from testneo_agent.adapters import AutoGenAdapter

from testneo_agent import TestNeo
from testneo_agent.adapters import LangGraphAdapter

sdk = TestNeo.from_env()
with sdk.run(goal="...", source="langgraph", auto_ingest=True) as run:
    adapter = LangGraphAdapter()
    adapter.bind(run)
    for ev in graph_stream_events:  # your native events
        adapter.on_native_event(ev)
    adapter.finish(final_message)

Architecture

See docs/architecture/TESTNEO_AGENT_SDK_ADAPTERS_PLAN.md.

Layer	Responsibility
TestNeoRun	Public instrumentation API
Adapters	Native events → internal events
Aggregator	Internal events → agent_run_summary.v1
Client	Ingest (+ optional post-agent-gate)

Config

Env	Purpose
TESTNEO_BASE_URL	API host — https://app.testneo.ai (prod) or self-hosted / http://127.0.0.1:8001 (local)
TESTNEO_API_KEY	Bearer token
TESTNEO_PROJECT_ID	Project id
TESTNEO_AUTO_INGEST	default true
TESTNEO_AUTO_VERIFY	default false (ingest ≠ gate)
TESTNEO_SDK_STRICT	raise on SDK errors
TESTNEO_SDK_DEBUG	debug logs (secrets masked)

Tests

cd packages/testneo-agent-sdk
pip install -e ".[dev]"
pytest -q

Non-goals

• Do not modify the verification engine from this package
• Do not hand-build agent_run_summary.v1 in the happy path
• Adapters must not import the HTTP client