> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pandaprobe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Give your agent persistent guidance and a bounded reflection checkpoint

PandaProbe Reflect gives your agent a persistent rule filesystem and feedback from evaluated failures. The same agent proposes reusable guidance; independent validation decides which changes become shared rules.

Reflect is included in the Python and TypeScript `pandaprobe` SDKs and integrates with your agent’s existing model, prompts, tools, and tracing.

**1. Install**

This template adds Reflect to an existing LangChain agent. Use Python 3.10+ or Node.js 22+. Choose your package manager:

> [tab] pip
>
> ```bash theme={null}
> pip install "pandaprobe[reflect,langchain]"
> ```

> [tab] uv
>
> ```bash theme={null}
> uv add "pandaprobe[reflect,langchain]"
> ```

> [tab] npm
>
> ```bash theme={null}
> npm install pandaprobe @everruns/bashkit@0.19.0 fs-native-extensions@1.5.1 langchain @langchain/core @langchain/langgraph
> ```

> [tab] yarn
>
> ```bash theme={null}
> yarn add pandaprobe @everruns/bashkit@0.19.0 fs-native-extensions@1.5.1 langchain @langchain/core @langchain/langgraph
> ```

> [tab] pnpm
>
> ```bash theme={null}
> pnpm add pandaprobe @everruns/bashkit@0.19.0 fs-native-extensions@1.5.1 langchain @langchain/core @langchain/langgraph
> ```

The Reflect dependencies provide the embedded shell and filesystem locks. For another framework, choose its [integration guide](https://docs.pandaprobe.com/reflect/integrations/overview.md).

**2. Set credentials**

Use a [PandaProbe account](https://app.pandaprobe.com) with an API key, project, and evaluation access. Your model continues to use its existing provider configuration.

```bash theme={null}
export PANDAPROBE_API_KEY="your-pandaprobe-api-key"
export PANDAPROBE_PROJECT_NAME="support-agent"
```

Self-hosted deployments also set `PANDAPROBE_ENDPOINT` to their API base URL. Reflect reuses the tracing client's configuration.

**3. Add Reflect to your agent**

Pass your existing LangChain factory options as `agent_options` / `agentOptions`: your configured model, prompt, tools, and any checkpointer. The PandaProbe client, user input, and session ID also come from your application.

Reflect adds its filesystem tool and memory instructions. The callback records the execution using the same client.

```python title="Python" theme={null}
from uuid import uuid4

from langchain.agents import create_agent
from pandaprobe import Client
from pandaprobe.integrations.langchain import LangChainCallbackHandler
from pandaprobe.reflect import Reflect


async def run_with_reflect(
    client: Client, agent_options: dict, user_input: str, session_id: str
):
    async with Reflect(client) as reflect:
        agent = reflect.agent(create_agent, **agent_options)
        execution_id = uuid4().hex
        result = await reflect.run(
            agent,
            user_input,
            session_id=session_id,
            execution_id=execution_id,
            config={"callbacks": [LangChainCallbackHandler(client=client)]},
        )
        print(reflect.report(execution_id).model_dump_json(indent=2))
        return result
```

```ts title="TypeScript" theme={null}
import { randomUUID } from "node:crypto";
import { createAgent } from "langchain";
import type { Client } from "pandaprobe";
import { LangChainCallbackHandler } from "pandaprobe/integrations/langchain";
import { Reflect as ReflectRuntime } from "pandaprobe/reflect";

async function runWithReflect(
  client: Client,
  agentOptions: Parameters<typeof createAgent>[0],
  userInput: string,
  sessionId: string,
) {
  const reflect = new ReflectRuntime(client);
  try {
    const agent = await reflect.agent(createAgent, {
      framework: "langchain",
      options: agentOptions,
      invokeOptions: { callbacks: [new LangChainCallbackHandler({ client })] },
    });
    const executionId = randomUUID();
    const result = await reflect.run(agent, userInput, { sessionId, executionId });
    console.log(JSON.stringify(reflect.report(executionId), null, 2));
    return result;
  } finally {
    await reflect.close();
  }
}
```

Call `run_with_reflect(...)` / `runWithReflect(...)` from your application’s async entry point. If you already have a PandaProbe callback, use it in place of the one shown. Your application owns the client and shuts it down when it exits.

**4. Read the result**

`run()` returns the original task result after bounded evaluation and, when a failure notice is produced, a reflection checkpoint. During reflection, the agent inspects evidence and proposes changes to its working rules.

* A healthy task may produce no notice or proposal.
* `report(...)` separates evaluation, reflection, and proposal status.
* Rules and evidence persist under `.pandaprobe/reflect/` by default. Reuse the workspace across restarts.
* Use a unique execution ID for each invocation. Reuse a session ID and native checkpoint for related conversation turns.

> [!NOTE]
>
> This enables proposal generation. Shared rules are accepted only after [independent validation](https://docs.pandaprobe.com/reflect/validation.md). Evaluation and reflection add API/model calls, latency, and cost.

> [!NOTE]
>
> This quickstart shows one example of adding Reflect to a LangChain agent. Explore the [integrations overview](https://docs.pandaprobe.com/reflect/integrations/overview.md) for other supported frameworks, or follow [Custom loops](https://docs.pandaprobe.com/reflect/custom-loops.md) to connect your own agent loop.

> [card] [Validate a proposal](https://docs.pandaprobe.com/reflect/validation.md)
>
> Compare fresh control and candidate executions with your own verifier.

> [card] [Choose your framework](https://docs.pandaprobe.com/reflect/integrations/overview.md)
>
> Follow the setup guide for your agent's native framework.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.