LangChain Agent

This example shows how to add Kyvvu compliance logging to a LangChain agent. The short version: you don't add decorators to anything. Instead, you pass a KyvvuLangChainHandler as a callback when invoking the agent, and LangChain's callback system takes care of the rest.

The full source is in examples/langchain-agent/ in the platform repo.

---

How it works

LangChain has a built-in callback system that fires events at every stage of execution: when the LLM is called, when a tool runs, when a chain starts and ends, and so on. KyvvuLangChainHandler implements LangChain's BaseCallbackHandler interface and translates these events into Kyvvu log entries.

The result is that every LLM call, tool invocation, and routing decision your LangChain agent makes is automatically captured — without touching your agent's logic at all.

Compare the two integration approaches:

	Decorator pattern	LangChain handler
What you instrument	Individual methods	The agent.invoke() call
Step types	You assign them (LLM_CALL, TOOL_CALL, ...)	Handler maps LangChain events automatically
Code changes	@kv.log_step(...) on each method	One line: config={"callbacks": [self.handler]}
Best for	Custom Python agents you control	LangChain chains, agents, and executors

---

Installation

The LangChain integration requires a few extra dependencies:

pip install langchain langchain-openai langchain-core numexpr

The integration itself ships with the SDK — no separate install needed.

---

Setup

Import KyvvuLangChainHandler instead of the base Kyvvu class:

from kyvvu.integrations.langchain import KyvvuLangChainHandler

Instantiate it with the same agent registration fields you'd pass to kv.register_agent(). The handler registers the agent automatically when it is created:

handler = KyvvuLangChainHandler(
    api_key=os.getenv("KV_DEMO_API_KEY"),
    api_url=os.getenv("KV_DEMO_API_URL", "http://localhost:8000"),
    agent_key="langchain-math-agent_1",
    name="LangChain Math Agent",
    purpose="Solves mathematical problems using LangChain and calculator tools",
    owner_id="[email protected]",
    risk_classification="limited",
    environment="development",
    metadata={
        "agent_type": "langchain_zero_shot_react",
        "tools": ["calculator"],
        "llm_provider": "openai",
        "framework": "langchain",
    },
)

That's the entire Kyvvu setup. The handler is now ready to attach to any LangChain invocation.

---

Building the LangChain agent

The rest is standard LangChain. Here's a ReAct agent with a calculator tool:

from langchain_core.prompts import PromptTemplate
from langchain.agents import AgentExecutor, create_react_agent
from langchain_core.tools import Tool
from langchain_openai import ChatOpenAI
import numexpr as ne

# LLM
llm = ChatOpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    model="gpt-4o-mini",
    temperature=0.0,
)

# Tool
def calculator(expression: str) -> str:
    try:
        return str(ne.evaluate(expression.strip()))
    except Exception as e:
        return f"Error: {e}"

tools = [
    Tool(
        name="Calculator",
        func=calculator,
        description=(
            "For mathematical calculations. "
            "Input: a valid expression like '2+2' or '5*7-3'."
        ),
    )
]

# ReAct prompt
template = """Answer the following questions as best you can.
You have access to the following tools:

{tools}

Use this format:
Question: the input question
Thought: think about what to do
Action: one of [{tool_names}]
Action Input: the input to the action
Observation: the result
... (repeat as needed)
Thought: I now know the final answer
Final Answer: the final answer

Begin!
Question: {input}
Thought:{agent_scratchpad}"""

prompt = PromptTemplate.from_template(template)
agent  = create_react_agent(llm, tools, prompt)

executor = AgentExecutor(
    agent=agent,
    tools=tools,
    handle_parsing_errors=True,
)

Nothing Kyvvu-specific here. This is a standard LangChain agent that would work fine without any compliance logging.

---

Attaching the handler

The only Kyvvu-specific line in your entire execution path is passing the handler as a callback:

result = executor.invoke(
    {"input": "What is 25 * 17 + 143?"},
    config={"callbacks": [handler]}   # ← this is it
)

print(result["output"])
# → "The answer is 568"

From that single line, Kyvvu receives log entries for:

• The LangChain chain starting (START_NODE)

• The LLM reasoning about the problem (LLM_CALL)

• The decision to use the Calculator tool (DECISION)

• The Calculator tool executing 25 * 17 + 143 (TOOL_CALL)

• The LLM formatting the final answer (LLM_CALL)

• The chain completing (END_NODE)

All without any changes to the agent itself.

---

Full agent class

Putting it together as a self-contained class, the pattern is: store the handler as an instance attribute, build your LangChain executor normally, and pass the handler in config at invocation time.

import os
from typing import Optional
from langchain_core.prompts import PromptTemplate
from langchain.agents import AgentExecutor, create_react_agent
from langchain_core.tools import Tool
from langchain_openai import ChatOpenAI
from kyvvu.integrations.langchain import KyvvuLangChainHandler
import numexpr as ne


class LangChainMathAgent:

    def __init__(self):
        # Kyvvu: one handler per agent, created at init
        self.handler = KyvvuLangChainHandler(
            api_key=os.getenv("KV_DEMO_API_KEY"),
            api_url=os.getenv("KV_DEMO_API_URL", "http://localhost:8000"),
            agent_key="langchain-math-agent_1",
            name="LangChain Math Agent",
            purpose="Solves mathematical problems using LangChain and calculator tools",
            owner_id="[email protected]",
            risk_classification="limited",
            environment="development",
        )

        # LangChain: standard setup, nothing Kyvvu-specific
        llm   = ChatOpenAI(api_key=os.getenv("OPENAI_API_KEY"), model="gpt-4o-mini", temperature=0.0)
        tools = [Tool(name="Calculator", func=lambda expr: str(ne.evaluate(expr.strip())),
                      description="Evaluates mathematical expressions.")]

        template = """..."""  # ReAct prompt as above
        prompt   = PromptTemplate.from_template(template)
        agent    = create_react_agent(llm, tools, prompt)

        self.executor = AgentExecutor(agent=agent, tools=tools, handle_parsing_errors=True)
        self.current_solution: Optional[str] = None

    def solve(self, problem: str) -> str:
        result = self.executor.invoke(
            {"input": problem},
            config={"callbacks": [self.handler]}  # attach Kyvvu here
        )
        self.current_solution = result.get("output", "")
        return self.current_solution


if __name__ == "__main__":
    agent = LangChainMathAgent()
    print(agent.solve("What is 25 * 17 + 143?"))
    print(agent.solve("What is the square root of 144?"))

---

What the dashboard shows

Each solve() call produces a separate task in the Kyvvu dashboard. Navigate to Logs and open a task to see the full step sequence. Because LangChain's ReAct loop can iterate — reasoning, calling a tool, observing the result, reasoning again — tasks may have a variable number of steps depending on how many iterations the agent needed. All of them are captured.

If you have step_execution policies configured, they are evaluated against each logged step as it arrives. If the agent calls an external tool without a prior PII_CHECK step and you have a policy requiring one, an incident is created immediately.

---

Comparison with the decorator pattern

If you're choosing between the two approaches for a new project:

Use @kv.log_step decorators when you're building a custom Python agent and want explicit control over what gets logged and how it's classified. You decide exactly which methods are steps and what node type each one is.

Use KyvvuLangChainHandler when you're building with LangChain and want zero-touch logging. The handler maps LangChain's native events to Kyvvu node types automatically — you don't manage step types, task IDs, or sequencing at all.

Both approaches produce the same audit trail structure in Kyvvu. The choice is about how much control you want versus how little code you want to write.

---

Next steps

• Copilot Studio: For Microsoft Copilot Studio agents, see Copilot Studio Integration — a dedicated API endpoint handles the logging without any SDK at all

• Policies: A task_execution policy is particularly useful with LangChain agents — you can assert things about the complete task (e.g., "the agent must have used at least one tool") rather than individual steps