Codex/langgraph agent kernel

.env.example

@@ -1,6 +1,10 @@
 # Common settings
 AGENT_CORE_LLM_TIMEOUT_SECONDS=120
 # AGENT_CORE_LLM_MAX_OUTPUT_TOKENS=4096
+# AGENT_CORE_MODEL_BACKEND=native
+# AGENT_CORE_AGENT_KERNEL_BACKEND=native
+# LangSmith export is disabled by default even if LANGSMITH_TRACING=true.
+# AGENT_CORE_LANGCHAIN_TRACING_ENABLED=false
 
 # OpenAI
 LLM_PROVIDER=openai
@@ -10,6 +14,7 @@ AGENT_CORE_MEMORY_MODEL=gpt-4.1-mini
 
 # Optional dedicated provider for memory/internal synthesis.
 # If omitted, memory synthesis uses the main provider with AGENT_CORE_MEMORY_MODEL.
+# AGENT_CORE_MEMORY_MODEL_BACKEND=native
 #
 # Example: main assistant on Azure Anthropic, memory synthesis on Azure OpenAI.
 # AGENT_CORE_MEMORY_LLM_PROVIDER=azure_openai
@@ -25,6 +30,7 @@ AGENT_CORE_MEMORY_MODEL=gpt-4.1-mini
 
 # Azure OpenAI
 # LLM_PROVIDER=azure_openai
+# AGENT_CORE_MODEL_BACKEND=langchain
 # AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com
 # AZURE_OPENAI_API_KEY=
 # AGENT_CORE_MODEL=<deployment-name>

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+- Added opt-in LangGraph kernels for direct, investigate, and deep-investigate
+  conversation turns behind `CoreSettings.agent_kernel_backend`, using typed
+  internal state, versioned pending graph cursors, and shared native/LangGraph
+  operations while preserving agent-core persistence, budgets, artifacts,
+  traces, and memory contracts. Added deterministic contract parity and opt-in
+  paired real-model kernel evals for tools, pending resume, structured output,
+  investigation synthesis, critique, tokens, latency, persistence, and traces.
+- Added an opt-in LangChain model backend for Azure OpenAI behind the existing
+  `BaseLLMProvider` contract, with shared request normalization, adaptive retry,
+  token usage, tool-call, request-id, and primary/memory provider semantics.
+- Fixed the provider compatibility quickstart to consume typed
+  `LLMCompletionResult` values for plain-text and JSON Schema checks.
+- Added persisted `model_backend` telemetry, explicit opt-in LangSmith tracing,
+  broader Azure provider contract coverage, and an opt-in paid `live_llm` test
+  matrix for native and LangChain model invocation.
+
 - Replaced overflow-driven conversation summaries and separately synthesized
   task state with append-only `ExchangeMemory` and `TurnMemory` journals plus a
   deterministic, rebuildable `SessionView`.

README.md

@@ -91,6 +91,93 @@ Or run a small REPL:
 .venv/bin/python examples/quickstart.py --interactive
 ```
 
+### Optional LangChain model backend for Azure OpenAI
+
+Azure OpenAI can use LangChain for model invocation while the agent loop,
+tools, policies, checkpoints, memory lifecycle, and public provider contract
+remain owned by agent-core. The native SDK backend remains the default.
+
+```bash
+LLM_PROVIDER=azure_openai
+AGENT_CORE_MODEL_BACKEND=langchain
+AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com
+AZURE_OPENAI_API_KEY=...
+AZURE_OPENAI_API_VERSION=2025-01-01-preview
+AGENT_CORE_MODEL=<deployment-name>
+AGENT_CORE_MEMORY_MODEL=<deployment-name>
+
+.venv/bin/python examples/quickstart.py --compat-check
+```
+
+`AGENT_CORE_MEMORY_MODEL_BACKEND` can override the backend for a dedicated
+memory provider. If it is omitted, memory synthesis uses the primary backend;
+`native` and `langchain` can therefore be compared without changing the agent
+or memory contracts. The LangChain backend currently supports Azure OpenAI
+only.
+
+LangSmith tracing is forcibly disabled around LangChain model calls by default,
+including when the process inherits `LANGSMITH_TRACING=true`. A host that has
+reviewed its data-handling requirements can explicitly opt in with
+`AGENT_CORE_LANGCHAIN_TRACING_ENABLED=true`.
+
+Provider telemetry keeps `provider="azure_openai"` stable and records the
+implementation separately as `model_backend="native"` or `"langchain"` in
+completion records, run results, structured-task checkpoints, and conversation
+trace response events.
+
+### Optional LangGraph conversation-agent kernel
+
+The conversation orchestrator can use LangGraph for the internal control flow
+of `direct`, `investigate`, and `deep_investigate` turns. This switch is
+independent from the model backend: native or LangChain model invocation can be
+used with either agent kernel.
+
+```bash
+AGENT_CORE_AGENT_KERNEL_BACKEND=langgraph
+```
+
+The default remains `native`. LangGraph owns the direct model/tool loop plus the
+planning, assistant, tool, reflection/decision, critique, and terminal routes
+for investigation modes. The existing controller operations still implement
+the domain semantics shared by both kernels. Session persistence, pending-tool
+payloads, resume idempotence, budgets, artifacts, traces, and memory commits
+remain owned by agent-core. A versioned graph cursor is stored in pending
+payloads, while the LangGraph graphs are intentionally compiled without their
+own durable checkpointer to avoid two competing state stores.
+
+The same explicit LangSmith privacy boundary applies to graph execution:
+tracing stays disabled unless `AGENT_CORE_LANGCHAIN_TRACING_ENABLED=true`, even
+if the process inherits `LANGSMITH_TRACING=true`.
+
+See [docs/langgraph_migration.md](docs/langgraph_migration.md) for the state and
+transition map, current ownership boundaries, and the remaining full-graph
+migration work.
+
+Paid Azure integration tests are excluded from normal test runs. To execute the
+same behavioral matrix against both backends:
+
+```bash
+AGENT_CORE_RUN_LIVE_LLM_TESTS=1 \
+AGENT_CORE_LIVE_LLM_MODEL=gpt-5.4-mini \
+AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com \
+AZURE_OPENAI_API_KEY=... \
+.venv/bin/python -m pytest -m live_llm -q -s
+```
+
+Use `AGENT_CORE_LIVE_LLM_BACKENDS=native` or `langchain` to test only one
+implementation. The live suite covers reasoning and usage metadata, strict JSON
+Schema output, a complete tool-result roundtrip, and `StructuredTaskRunner`.
+When the LangChain model backend is selected, it also compares native and
+LangGraph direct-agent kernels through the full conversation tool loop,
+validates pending/resume for both kernels, and runs paired investigation and
+deep-investigation scenarios. The extended matrix covers competing-tool
+selection, structured final output, initial planning, reflection, decision,
+final critique, and final synthesis. Lines prefixed with
+`LIVE_KERNEL_EVAL` report per-kernel wall/provider latency, model-call count,
+token usage, selected tools, persistence projections, and trace-event paths.
+Latency and token deltas are observations rather than pass/fail thresholds;
+repeat the paid suite before drawing performance conclusions from them.
+
 See [examples/README.md](examples/README.md) for the pending tool result and
 resume example.
 

agent_core/agent_graph/__init__.py

@@ -0,0 +1,7 @@
+"""Internal agent-kernel implementations.
+
+This package is deliberately not re-exported from :mod:`agent_core`. Its
+types describe the implementation state of the conversation adapter, not a
+public persistence or extension contract.
+"""
+