feat(sdk): add Anthropic SDK integration

[Uchebuzz]

Summary

Adds first-class Anthropic SDK support to the Adrian Python SDK. Every
messages.create call on both anthropic.Anthropic and
anthropic.AsyncAnthropic is now captured automatically as a
PairedEvent and emitted through the hook registry — no changes needed
to user agent code beyond adrian.init().

Changes

• sdk/adrian/anthropic_handler.py (new): message format conversion,
  tool call and usage extraction, PairedEvent assembly, idempotent
  monkey-patch of Messages.create / AsyncMessages.create, and
  anthropic_invocation() / anthropic_invocation_sync() context managers
  for grouping multi-turn calls under a single invocation ID.
• sdk/tests/test_anthropic_handler.py (new): 61 tests covering all
  helper functions, emission, getter lifecycle, the no-package no-op path,
  and both context managers. All pass.
• sdk/adrian/__init__.py: patch_anthropic(), anthropic_invocation,
  and anthropic_invocation_sync exported; _auto_instrument_anthropic()
  wired into init() alongside LangChain auto-instrumentation.
• sdk/pyproject.toml: anthropic optional dependency group added;
  anthropic>=0.40.0 added to [dev] for the test suite.
• examples/anthropic_quickstart.py (new): minimal demo showing single-call
  and multi-turn anthropic_invocation() usage.

Test plan

• uv pip install -e ./sdk[dev,anthropic] then
  pytest sdk/tests/test_anthropic_handler.py -v — 61 tests pass
• pytest sdk/tests/ — no regressions in existing suite
• Run examples/anthropic_quickstart.py against a live backend and
  confirm events appear in the dashboard with correct model, messages,
  and usage fields
• Confirm anthropic_invocation() groups multi-turn calls under a
  shared invocation_id in the dashboard

Checklist

• CLA signed (see CLA.md)
• Tests pass locally
• Docs updated where needed
• British English; no em-dashes; no marketing fluff

[max-c-sa]

Thanks for the PR Uche! I'll leave to the engineers to work with you but huge thanks for taking on Anthropic integration and i'd like to invite you to the private contributors discord community channel. https://discord.gg/zcwYwfdAFz I am 'maxicorbs' DM on there and i'll add you

[yanny-sec]

Thanks for the PR! Currently it's audit-only. Could you add logic to actually hold the tool calls for HITL and Block modes? You can use the TS OpenAI or Python LangChain integrations for reference.

[Uchebuzz]

Thanks for the PR! Currently it's audit-only. Could you add logic to actually hold the tool calls for HITL and Block modes? You can use the TS OpenAI or Python LangChain integrations for reference.

Okay, I will look into this and fix thank you

[yanny-sec]

I've merged #78 which modularises the existing LangChain integration from __init__.py to its own langchain_handler.py file. You should rebase from main later.

[Uchebuzz]

I've merged #78 which modularises the existing LangChain integration from __init__.py to its own langchain_handler.py file. You should rebase from main later.

thanks for the heads up, rebased onto main 👍

still investigating this....

Quick question before I do the gate: the Anthropic SDK has no tool-execution step to intercept like LangChain's BaseTool.invoke, the only hook point is the return of messages.create(), where the model hands back tool_use blocks. So when a verdict says block, how do you want it to surface?

• Rewrite the response swap the blocked tool_use block for a [BLOCKED] text block, so the caller just sees no tool call (matches the LangChain behavior),
  or
• Raise an error — hard-stop the whole call.

[yanny-sec]

I've merged #78 which modularises the existing LangChain integration from __init__.py to its own langchain_handler.py file. You should rebase from main later.

thanks for the heads up, rebased onto main 👍

still investigating this....

Quick question before I do the gate: the Anthropic SDK has no tool-execution step to intercept like LangChain's BaseTool.invoke, the only hook point is the return of messages.create(), where the model hands back tool_use blocks. So when a verdict says block, how do you want it to surface?

• Rewrite the response swap the blocked tool_use block for a [BLOCKED] text block, so the caller just sees no tool call (matches the LangChain behavior),
  or
• Raise an error — hard-stop the whole call.

To keep it consistent with the other integrations let's go for the [BLOCKED] text block, that way the model will know something stopped its action too.

[Uchebuzz]

Thanks for the review — pushed the fix.

The handler now actually holds tool calls instead of just auditing them. On the async path, each tool_use block waits for its classifier verdict, and under BLOCK/HITL a halted call is rewritten into a [BLOCKED by security policy] text block so the model can see its action was stopped (kept consistent with the LangChain gate). Fail-closed behaviour matches langchain_handler, and I've rebased onto main including #78.

A couple of things I'd like your call on:

• Scoped to async AsyncMessages for now; sync Messages.create is still audit-only. Happy to add sync parity if you want it in this PR.
• _should_halt is duplicated locally so the Anthropic module doesn't import the LangChain one — glad to share it via a common home instead if you'd prefer.

Added 18 tests, including an end-to-end emit→gate check.

[yanny-sec]

Thanks for the review — pushed the fix.

The handler now actually holds tool calls instead of just auditing them. On the async path, each tool_use block waits for its classifier verdict, and under BLOCK/HITL a halted call is rewritten into a [BLOCKED by security policy] text block so the model can see its action was stopped (kept consistent with the LangChain gate). Fail-closed behaviour matches langchain_handler, and I've rebased onto main including #78.

A couple of things I'd like your call on:

• Scoped to async AsyncMessages for now; sync Messages.create is still audit-only. Happy to add sync parity if you want it in this PR.
• _should_halt is duplicated locally so the Anthropic module doesn't import the LangChain one — glad to share it via a common home instead if you'd prefer.

Added 18 tests, including an end-to-end emit→gate check.

That's a good shout, _should_halt can and should be modularised. One more thing that's missing, LangChain integration currently exposes on_verdict, on_block, on_audit as notification callbacks for the developer. To maintain feature parity with the LangChain integration, sync Messages.create should also be gated.

[Uchebuzz]

Okay — will do all three: modularise should_halt, fire the on_verdict/on_block/on_audit callbacks for Anthropic events, and gate sync Messages.create too. Pushing shortly.

[Uchebuzz]

Pushed all three:

1. should_halt modularised — moved into ws.py as a public helper (next to policy_active/block_timeout, mirroring the TS core shouldHalt); both handlers import it now, no LangChain dependency.
2. on_verdict/on_block/on_audit fire for Anthropic — the handler was emitting straight to the hook registry and bypassing the callback handler's event map (which those callbacks key on). Emission now delegates to the callback handler, so the notification callbacks reach the developer with parity.
3. Sync Messages.create gated — emit + gate are bridged onto the WS event loop via run_coroutine_threadsafe (matching _sync_gate); the caller blocks for the verdict, and it degrades to audit-only when gating isn't possible.

Tests: should_halt cases relocated to test_ws.py; added callback-parity tests (block/audit tiers) and sync-gate tests. Full suite green; ruff + basedpyright clean.

[yanny-sec]

Thanks, all three items are addressed: should_halt is shared via ws.py, the on_verdict / on_block / on_audit callbacks now fire for Anthropic events, and sync Messages.create gates. I confirmed the callback parity and sync gating locally.

One change before merge: the sync bridge fails open where it should fail closed.

In sdk/python/adrian/anthropic_handler.py, _emit_and_gate_sync L656-662, a bridge/gate exception is logged and then control falls through to return response, so under BLOCK a halted tool call is let through:

            except Exception:
                logger.exception("Anthropic sync gate bridge failed; emitting audit-only")

    _schedule_emit(response, kwargs)
    return response

langchain_handler._sync_gate fails closed at the same point (L639-640: except Exception: return True) - please match, rewriting to [BLOCKED] on error under BLOCK. (Same function: the loop-less path at L661-662 also degrades to audit-only, where LangChain uses asyncio.run(_async_gate(...)) at L644.)