[Type Definitions] Types mismatch between `RunResult` and `RunState`

[AndyRightNow]

Please read this first

• Have you read the docs? Agents SDK docs
• Have you searched for related issues? Others may have faced similar issues.

Describe the bug

RunState cannot be used to instantiate a RunResult even with the same generic types.

Debug information

• Agents SDK version: (e.g. v0.0.14)
• Runtime environment (e.g. Node.js 22.16.0)

Repro steps

See TS Playground Reproduction

Updated a more common usage pattern with type inference:

const inferredState = new RunState(anyContext, 'input', agent, 10)

const inferredResult = new RunResult(inferredState)

I believe this would be how the constructors or fromString are used the most.

Expected behavior

There should be no errors.

Possible Fix

Add an extra generic type parameter in RunResult:

TAgentOutputType extends AgentOutputType

[vrtnis]

Thanks for providing the Playground repro (just tried it out). Agree the error messages are unexpected, but (somewhat surprisingly) the two classes are behaving exactly as intended.

RunResult<TContext, TAgent> is meant to be a thin, read‑only view over a finished run. All info about the agent’s output is already encoded in the second type parameter. Because, TAgent itself carries TOutput, adding a third generic type argument would be redundant as every call site would have to repeat the same type twice e.g., RunResult<MyCtx, MyAgent, "text">. Woud also be regressive for inference as TS would struggle to infer 3 independent generics from a single value (and so forcing us to annotate manually)

In the above TS Playground example TS cannot infer that the agent’s concrete output type flows through RunState into RunResult, because RunState was declared more loosely, however, that is deliberate to allow a runner to upgrade/downgrade agents during a long‑lived conversation but it does mean we occasionally need to help the compiler

This is good f/b though - eventually this could be addressd by inference helpers but in the short term maybe a docs push with a short “Type‑inference tips” section that explains when annotations are needed and how to avoid such scenarios.

I did make a new snippet you can try out and the only change from your original file is just one intentional widening cast that lets the compiler know the runner utilities can accept any agent output type (even though your agent still only returns "text").

Revised TS Playground

[AndyRightNow]

Thanks for providing the Playground repro (just tried it out). Agree the error messages are unexpected, but (somewhat surprisingly) the two classes are behaving exactly as intended.

RunResult<TContext, TAgent> is meant to be a thin, read‑only view over a finished run. All info about the agent’s output is already encoded in the second type parameter. Because, TAgent itself carries TOutput, adding a third generic type argument would be redundant as every call site would have to repeat the same type twice e.g., RunResult<MyCtx, MyAgent, "text">. Woud also be regressive for inference as TS would struggle to infer 3 independent generics from a single value (and so forcing us to annotate manually)

In the above TS Playground example TS cannot infer that the agent’s concrete output type flows through RunState into RunResult, because RunState was declared more loosely, however, that is deliberate to allow a runner to upgrade/downgrade agents during a long‑lived conversation but it does mean we occasionally need to help the compiler

This is good f/b though - eventually this could be addressd by inference helpers but in the short term maybe a docs push with a short “Type‑inference tips” section that explains when annotations are needed and how to avoid such scenarios.

I did make a new snippet you can try out and the only change from your original file is just one intentional widening cast that lets the compiler know the runner utilities can accept any agent output type (even though your agent still only returns "text").

Revised TS Playground

Thanks for the updates. The root of my requirement is actually to get the history of a captured state and the only public API I can find is through RunResult.

In fact the logic of getting result.history is quite simple and straightforward so maybe this can justify another feature request to get the history items of a RunState.

[vrtnis]

Thanks for the clarification! you’re right that the only public API for accessing history is currently through RunResult.

Just want to add some context: RunState is intentionally a persistence artefact, and it captures just enough info for the runtime to resume or continue a run. Any (human) readable helpers (history, output, etc.) live on RunResult, which is a thin, read‑only front we could construct at any time, e.g.

import { RunResult } from "@openai/agents-core";
const history = new RunResult(state).history;   

This separation helps keep the persistence format stable while allowing the developer-facing API (i.e., RunResult) to evolve independently.

However, I can definitely see how a first‑class RunState.history could simplify tools that operate on intermediate or paused states. If you think this would be broadly useful, a suggestion would be to please open a feature‑request issue and link back to this thread. That will give the community a chance to weigh in. I’d be happy to submit a PR based on further feedback.

[AndyRightNow]

Thanks for the clarification! you’re right that the only public API for accessing history is currently through RunResult.

Just want to add some context: RunState is intentionally a persistence artefact, and it captures just enough info for the runtime to resume or continue a run. Any (human) readable helpers (history, output, etc.) live on RunResult, which is a thin, read‑only front we could construct at any time, e.g.

import { RunResult } from "@openai/agents-core";
const history = new RunResult(state).history;   

This separation helps keep the persistence format stable while allowing the developer-facing API (i.e., RunResult) to evolve independently.

However, I can definitely see how a first‑class RunState.history could simplify tools that operate on intermediate or paused states. If you think this would be broadly useful, a suggestion would be to please open a feature‑request issue and link back to this thread. That will give the community a chance to weigh in. I’d be happy to submit a PR based on further feedback.

Absolutely, here is the feature request #293