feat(ai): add LangChain v1 agent middleware

[gouveags]

Problem

@posthog/ai supports LangChain through its callback handler, but it does not expose a middleware-native integration for LangChain v1 agents. Users adopting the v1 middleware API therefore have no first-party middleware for capturing agent traces, model generations, and tool spans.

Closes #2907.

Changes

• Add createPostHogMiddleware at @posthog/ai/langchain/middleware.
• Reuse the existing callback handler's provider, token, privacy, and event normalization.
• Keep @posthog/ai/langchain callback-only, so existing users do not need the optional langchain runtime.
• Cover real agent tool loops, failures, privacy, concurrency, explicit trace IDs, and callback-only module loading.

import { createAgent } from 'langchain'
import { createPostHogMiddleware } from '@posthog/ai/langchain/middleware'

const agent = createAgent({
  model,
  tools,
  middleware: [createPostHogMiddleware({ client: posthog })],
})

Use either the callback or the middleware, not both, to avoid duplicate events. On a terminal agent failure, LangChain does not invoke afterAgent; the failed model or tool event is still captured, but no root trace is emitted.

Release info Sub-libraries affected

Libraries affected

• All of them
• posthog-js (web)
• posthog-js-lite (web lite)
• posthog-node
• posthog-react-native
• @posthog/react-native-plugin
• @posthog/react
• @posthog/ai
• @posthog/convex
• @posthog/next
• @posthog/nextjs-config
• @posthog/nuxt
• @posthog/openfeature-node-provider
• @posthog/openfeature-web-provider
• @posthog/rollup-plugin
• @posthog/webpack-plugin
• @posthog/types
• @posthog/browser-common

Checklist

• Tests for new code
• Accounted for the impact of any changes across different platforms
• Accounted for backwards compatibility of any changes (no breaking changes!)
• Took care not to unnecessarily increase the bundle size

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Gabriel directed the contribution. I used Codex for implementation, test design, and independent review. The middleware lives in a separate subpath so callback-only users do not load the optional langchain runtime, while event normalization continues to use the existing callback handler. A public session link is unavailable in this environment.

[gouveags]

@greptileai review

[greptile-apps]

Prompt To Fix All With AI

### Issue 1
packages/ai/src/langchain/middleware/index.ts:129
**Explicit trace breaks parent linkage**

When `traceId` is configured, the callback fallback assigns that trace ID as each model or tool event's `$ai_parent_id`, while the emitted agent root has a distinct generated `$ai_span_id`, causing the child events to detach from the agent root in the trace hierarchy.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(ai): add LangChain v1 agent middlew..." | Re-trigger Greptile}

[gouveags]

@greptileai review

[greptile-apps]

_{Reviews (2): Last reviewed commit: "fix(ai): preserve middleware trace hiera..." | Re-trigger Greptile}

[marandaneto]

Automated advisory code review.

[marandaneto]

blocking: Preserve custom agent state in traces — LangChain projects lifecycle-hook state through this middleware schema, which only declares the _posthog* fields plus built-ins. With a custom createAgent({ stateSchema }), fields such as tenant or workflow context remain in the agent result but are silently absent from $ai_input_state and $ai_output_state; a custom-state probe reproduced the omission.

[marandaneto]

blocking: Normalize tools before capture — request.tools contains DynamicStructuredTool instances, so standard tool(...) values serialize in $ai_tools as a generic {"type":"not_implemented","id":["langchain","tools","DynamicStructuredTool"]}, losing the actual name, description, and schema. Normalize these instances to capture-ready definitions before passing them to the callback handler.

[marandaneto]

thanks @gouveags
pinging @PostHog/team-ai-observability to double check this