Metadata-Version: 2.5
Name: testimony-openai-agents
Version: 0.2.1
Summary: Emit a Testimony Record from an OpenAI Agents SDK run. The SDK has the approval gate; this makes the record say who opened it.
Project-URL: Homepage, https://machinetestimony.org
Project-URL: Specification, https://datatracker.ietf.org/doc/draft-clifford-testimony-record/
Project-URL: Source, https://github.com/troybrandonc-bit/machine-testimony/tree/main/adapters/openai-agents
Project-URL: Assessment, https://doi.org/10.5281/zenodo.22290922
Project-URL: Issues, https://github.com/troybrandonc-bit/machine-testimony/issues
Author: Troy Clifford
License: MIT
License-File: LICENSE
Keywords: accountability,agent-governance,ai-agents,approval,article-14,audit-trail,eu-ai-act,human-in-the-loop,openai-agents,provenance,testimony-record
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Legal Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.9
Requires-Dist: openai-agents>=0.2
Description-Content-Type: text/markdown

# Testimony Records from the OpenAI Agents SDK

```
pip install testimony-openai-agents
```

Or one file: copy `testimony_openai_agents.py` and
[`testimony_emit.py`](../../spec/testimony_emit.py) next to your agent. There is
nothing else to install and nothing here depends on OMEM.

```python
from agents import Agent, Runner, function_tool
from testimony_openai_agents import Recorder

def decide(req):
    # req.action, req.arguments, req.risk_class.
    # Your approval UI, queue or ticket goes here. The identity has to come
    # from your authentication layer; this adapter has none to find.
    if req.action == "close_account":
        return req.refuse("a balance is outstanding")
    return req.approve(approver={"id": "r.okonkwo@example.com", "kind": "human"},
                       identity_source="auth-session")

rec = Recorder(
    agent={"id": "support-agent", "kind": "agent"},
    risk={"issue_refund": "high", "close_account": "high",
          "search_docs": "low"},
    decide=decide,
)
result = await rec.run(Runner, agent, "Refund order 8842")
rec.write("record.jsonl")
```

```
$ python3 testimony_validate.py record.jsonl
Conformance: TR-4
```

## This SDK already has the gate. It cannot say who opened it

Unlike the other adapters here, nothing in this one adds an approval boundary.
`needs_approval` on a tool already stops the run, `result.interruptions`
already lists what is waiting, and `state.approve(item)` already lets it
through. That machinery is good and this does not replace it.

What `state.approve(item)` does not take is **a principal.** It records that a
call was approved, not by whom, and any code holding the state can call it,
including the process that proposed the action. So a run where an engineer read
the arguments and decided is indistinguishable afterwards from one where a
script approved everything.

An [assessment of eight agent systems](https://machinetestimony.org/register/)
published in September 2026 recorded exactly that for this SDK: whether an
approval identifies a person, whether the identity comes from the
authentication layer, and whether the agent is prevented from approving its own
action were all **absent**, and in each case because there is nowhere to put
the answer.

This does not fix that by inventing an approver. It fixes it by refusing to
write an approval unless you supply an identity from your own authentication
layer, and by making the omission visible rather than silent.

## Colorado asks for this from 1 January 2027

Proposed Rule 7.7 under Colorado's Automated Decision-Making Technology Act
requires a deployer to retain a record showing, when a human reviews an
automated decision: **the reviewer's identity**, review timestamps, the primary
evidence available to them, whether they **approved, modified or overrode** the
output, and a written justification. The rules were filed on 11 August 2026 and
take effect with the act on 1 January 2027 if adopted. They are not law yet.

A reading of ten widely deployed agent systems found that of the eight which
take or gate consequential actions, **one can identify the person who approved
one**, and that one is the reference implementation of this specification, which
is disclosed rather than left to be found.

### What this SDK can show, measured

On whether a reviewer **modified** an action, this SDK passes by construction
and it is worth being precise about why. It offers approve and reject and no
modify path at all, so a reviewer cannot alter arguments and then allow them and
a different action is necessarily a different call. That is a design decision,
not a missing field, and recording it as a failure would report a defect where
the defect has been made impossible.

What it retains of the material a reviewer saw is the raw tool call, so what was
**eligible** to be shown is recoverable and the rendering is not: two
integrations displaying the same call very differently produce identical
records. And the approval names no person, which is the gap this adapter closes.

Read 9 September 2026 at
[machinetestimony.org/approval-binding/](https://machinetestimony.org/approval-binding/),
with the file and line behind every verdict.

## What it will not do

**It will not fail open.**
[#4845](https://github.com/openai/openai-agents-python/issues/4845) is the
neighbouring mistake in this very SDK, one layer down: a callable
`needs_approval` predicate returned `None` from an unhandled branch, `None`
read as "no approval needed", and the gate opened on the path nobody had
thought about. If your `decide` returns anything that is not a decision this
issued, the run raises and the tool does not execute.

**It will not classify risk from anything the model produced,** let the acting
agent approve its own action, or accept an identity source the model could have
written.

A refusal is passed to `state.reject` with your reason as the rejection
message, so the model is told why rather than told nothing, and it is recorded
with the same standing as a permission.

## Tests

`tests/tests_openai_agents_testimony.py`, 29 checks, against a real `Runner`
with no API key and no network: only the model is scripted, against the SDK's
public `Model` interface. The agent, the Runner, the tool, the interruption,
`to_state` and `approve`/`reject` are all the real ones, because those are what
is under test.

MIT. Copyright 2026 Garnet Taurus Ltd.
The specification: <https://datatracker.ietf.org/doc/draft-clifford-testimony-record/>
