> ## 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.

# Reflect runtime

> Run the agent, evaluate evidence, continue reflection, and inspect outcomes

Reflect coordinates **Detect → Notify → Reflect → Validate** around an explicit agent invocation. Your agent receives failure evidence and proposes filesystem changes; independent validation determines whether they become accepted rules.

`run` returns the original task result after evaluation and any triggered reflection. It does not replace the task answer with the reflection answer. Task exceptions propagate. Validation settles separately so replay can acquire resources released by the task.

Native agent construction attaches the supplied `reflect_bash` tool and memory instructions. A generic asynchronous callback receives an `Invocation` and must pass its instructions/tool to the model and enforce phase permissions itself. See the [quickstart](https://docs.pandaprobe.com/reflect/quickstart.md), [native integrations](https://docs.pandaprobe.com/reflect/integrations/overview.md), and [custom loop guide](https://docs.pandaprobe.com/reflect/custom-loops.md).

Use unique execution IDs and related-work session IDs. Importing Reflect alone starts no work; constructing it opens its configured persistent workspace. Close Reflect and then the tracing client. An externally supplied platform client remains caller-owned.

`agent(...)` and `tool(...)` construct synchronously; `run(...)`, `bash(...)`, and settlement operations are awaited. `submit_traces(...)` and `validate(...)` return scheduled asyncio Tasks. Use `async with Reflect(client)` or `await reflect.aclose()`.

## On this page

[Reflect](#reflect).

## Example

This function wraps an already configured native agent or an async `Invocation` callback. The agent must include its tracing integration; use a [framework guide](https://docs.pandaprobe.com/reflect/integrations/overview.md) to construct one with Reflect tooling.

```python theme={null}
from pandaprobe import Client
from pandaprobe.reflect import Reflect, ReflectConfig


async def run_support(build_agent):
    client = Client()
    try:
        async with Reflect(client, config=ReflectConfig(workspace="./agent-memory")) as reflect:
            agent = build_agent(reflect, client)  # Your traced native factory.
            result = await reflect.run(agent, "Help with my return.", session_id="customer-42")
            for proposal in reflect.proposals():
                print(proposal.id, proposal.status)
            return result
    finally:
        client.shutdown()
```

## `Reflect`

```python theme={null}
from pandaprobe.reflect import Reflect
```

[Source declaration](https://github.com/chirpz-ai/pandaprobe-sdk/blob/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python/src/pandaprobe/reflect/runtime.py#L44)

### Constructor

```text theme={null}
Reflect(
  client: Client | None=None,
  *,
  config: ReflectConfig | None=None,
  api: PlatformClient | None=None,
  replay=None,
  cases=None,
)
```

| Parameter | Type | Default / passing |
| - | - | - |
| `client` | `Client \| None` | `None` |
| `config` | `ReflectConfig \| None` | `None`; keyword only |
| `api` | `PlatformClient \| None` | `None`; keyword only |
| `replay` | `Not annotated` | `None`; keyword only |
| `cases` | `Not annotated` | `None`; keyword only |

### Fields and properties

| Name | Type | Default / contract |
| - | - | - |
| `client` | `Not annotated` | Instance value; Instance attribute. |
| `config` | `Not annotated` | Instance value; Instance attribute. |
| `workspace` | `Not annotated` | Instance value; Instance attribute. |
| `api` | `Not annotated` | Instance value; Instance attribute. |
| `validator` | `Not annotated` | Instance value; Instance attribute. |

### Methods

> [accordion] execution
>
> Explicit application boundary; framework callbacks do not define it.
>
> ```text theme={null}
> execution(*, session_id: str, execution_id: str | None=None, completed: bool=True) -> Execution
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `session_id` | `str` | Required; keyword only |
> | `execution_id` | `str \| None` | `None`; keyword only |
> | `completed` | `bool` | `True`; keyword only |

> [accordion] bash
>
> The single supplied tool, bound to this instance and invocation context.
>
> ```text theme={null}
> async bash(command: str) -> str
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `command` | `str` | Required |

> [accordion] tool
>
> Returns the supplied tool in a generic or native framework format. The generic tool accepts a command string and must run inside an active Reflect boundary.
>
> ```text theme={null}
> tool(framework: str='generic') -> Any
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `framework` | `str` | `'generic'` |

> [accordion] agent
>
> Builds a supported native agent with Reflect tools and memory integration. Pass the framework’s factory/constructor and its native options; do not also add reflect\_bash manually.
>
> ```text theme={null}
> agent(factory, *args: Any, **kwargs: Any) -> Any
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `factory` | `Not annotated` | Required |
> | `args` | `Any` | Additional arguments |
> | `kwargs` | `Any` | Additional arguments |

> [accordion] submit\_traces
>
> Schedules evaluation for completed trace references; identities must belong to the same project. Reusing a trace under a different execution ID is rejected.
>
> ```text theme={null}
> submit_traces(
>   trace_ids: list[str],
>   *,
>   execution_id: str,
>   session_id: str,
>   completed: bool=True,
> ) -> asyncio.Task[EvaluationOutcome]
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `trace_ids` | `list[str]` | Required |
> | `execution_id` | `str` | Required; keyword only |
> | `session_id` | `str` | Required; keyword only |
> | `completed` | `bool` | `True`; keyword only |

> [accordion] wait\_export
>
> Wait for SDK export separately from persistence and evaluation.
>
> ```text theme={null}
> async wait_export(*, timeout: float=30) -> None
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `timeout` | `float` | `30`; keyword only |

> [accordion] settle\_evaluation
>
> Waits for evaluation evidence for this execution. A caller wait deadline can leave the underlying run pending.
>
> ```text theme={null}
> async settle_evaluation(execution_id: str, *, timeout: float | None=None) -> EvaluationOutcome
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `execution_id` | `str` | Required |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] resume\_evaluations
>
> Resumes persisted pending evaluation work after restart; known evaluation IDs are polled instead of recreated.
>
> ```text theme={null}
> resume_evaluations() -> list[asyncio.Task[EvaluationOutcome]]
> ```

> [accordion] continue\_reflection
>
> Uses the supplied host continuation when evaluation has produced a failure notice. Delayed feedback does not automatically restart an agent.
>
> ```text theme={null}
> async continue_reflection(
>   execution_id: str,
>   continuation: Callable[[Invocation], Awaitable[Any]],
>   *,
>   input: Any=None,
>   previous_result: Any=None,
> ) -> ProposalOutcome
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `execution_id` | `str` | Required |
> | `continuation` | `Callable[[Invocation], Awaitable[Any]]` | Required |
> | `input` | `Any` | `None`; keyword only |
> | `previous_result` | `Any` | `None`; keyword only |

> [accordion] report
>
> Returns the execution’s task, evaluation, reflection, and proposal outcomes. Does not infer business success from task completion.
>
> ```text theme={null}
> report(execution_id: str) -> ExecutionReport
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `execution_id` | `str` | Required |

> [accordion] proposals
>
> Returns persisted proposals, including their lifecycle state and decision evidence.
>
> ```text theme={null}
> proposals() -> list[RuleProposal]
> ```

> [accordion] settle\_reflection
>
> Waits for an already scheduled reflection checkpoint. A caller wait timeout is distinct from the checkpoint’s execution deadline.
>
> ```text theme={null}
> async settle_reflection(execution_id: str, *, timeout: float | None=None) -> ProposalOutcome
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `execution_id` | `str` | Required |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] run
>
> Invoke the developer's agent, then offer it a bounded reflection checkpoint.
>
> ```text theme={null}
> async run(agent: Any, input: Any, *, session_id: str, execution_id: str | None=None, **kwargs: Any) -> Any
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `agent` | `Any` | Required |
> | `input` | `Any` | Required |
> | `session_id` | `str` | Required; keyword only |
> | `execution_id` | `str \| None` | `None`; keyword only |
> | `kwargs` | `Any` | Additional arguments |

> [accordion] settle\_validation
>
> Wait separately, after the host releases resources replay may need.
>
> ```text theme={null}
> async settle_validation(*, timeout: float | None=None) -> bool
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `timeout` | `float \| None` | `None`; keyword only |

> [accordion] validate
>
> Schedule independent replay. Never await this while holding task resources.
>
> ```text theme={null}
> validate(proposal_id: str, *, cases, replay) -> asyncio.Task
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `proposal_id` | `str` | Required |
> | `cases` | `Not annotated` | Required; keyword only |
> | `replay` | `Not annotated` | Required; keyword only |

> [accordion] trial\_execution
>
> Fresh explicit trial exposure; no candidate enters ordinary accepted views.
>
> ```text theme={null}
> trial_execution(proposal_id: str, *, arm: str, session_id: str | None=None) -> Execution
> ```
>
> | Parameter | Type | Default / passing |
> | - | - | - |
> | `proposal_id` | `str` | Required |
> | `arm` | `str` | Required; keyword only |
> | `session_id` | `str \| None` | `None`; keyword only |

> [accordion] aclose
>
> Cancels owned work, bounds the shutdown wait, and closes an owned platform client. It does not close a caller-supplied platform client or the tracing client.
>
> ```text theme={null}
> async aclose() -> None
> ```

***

Signatures and fields are generated from the [SDK source](https://github.com/chirpz-ai/pandaprobe-sdk/tree/92d8c37fba00e87ac6f0104cd293990aa5d5e621/libraries/python). See the [import index](https://docs.pandaprobe.com/reference/python/overview.md#public-import-index) for available entry points.


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