feat(ai): add LangChain v1 agent middleware - #945

💡 Motivation and Context

LangChain v1 supports middleware as the main way to package agent integrations, but the Python SDK currently only supports callbacks.

This adds posthog.ai.langchain.middleware.PostHogMiddleware, the Python counterpart to PostHog/posthog-js#4556.

Closes #901.

What changed

• Added sync and async middleware hooks for agent, model, and tool activity.
• Kept middleware support in a separate optional module, so the base SDK and existing callback-only imports do not require langchain.
• Reused the existing LangChain callback conversion and capture logic.
• Preserved model and tool return values and exceptions exactly; PostHog capture remains fail-open.
• Kept synchronous delivery off the event-loop thread when Client(sync_mode=True).
• Added private per-invocation state for trace correlation, privacy-safe checkpoint handling, and cleanup after completed runs.
• Added per-tool schema fallback so one unsupported tool does not prevent the remaining telemetry from being captured.
• Added a runnable example and usage guidance.

Use either PostHogMiddleware or CallbackHandler for an agent invocation, not both. Put PostHogMiddleware last in the middleware list so it sees the final model selection and each retry attempt.

On terminal agent failure, LangChain does not call after_agent. In that case, the failed model or tool call is captured without a parent, and no dangling root trace is emitted.

💚 How did you test it?

• LangChain callback and middleware suites: 105 passed, 8 skipped
• Full test suite: 2,712 passed, 15 skipped, 38 subtests passed
• Python 3.10 compatibility
• Built-wheel smoke test with the minimum supported langchain==1.3.9
• Ruff formatting and lint
• Mypy baseline and strict type checks
• Public API snapshot check
• Package build and Twine validation
• Base-package import smoke test without LangChain installed

The middleware tests cover sync and async agent runs, non-blocking async capture, model retries, model and tool failures, returned tool errors, Command results, concurrent invocations, privacy mode, checkpoint cleanup, tool-schema fallback, capture failures, and compatibility with the existing callback integration.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Added a Sampo minor changeset.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Gabriel directed the scope and is the DRI (@gouveags). Codex assisted with implementation, tests, validation, and independent review. No shareable session transcript is available.

The main design choice was to keep middleware support optional and reuse the existing callback capture logic instead of maintaining a second telemetry implementation. Human review is required.