<!--
{
  "availability" : [
    "Xcode: 27.0.0 -",
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: 27.0.0 -",
    "macOS: 27.0.0 -",
    "visionOS: 27.0.0 -",
    "watchOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Evaluations",
  "identifier" : "/documentation/Evaluations/TrajectoryExpectation",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Evaluations"
    ],
    "preciseIdentifier" : "s:11Evaluations21TrajectoryExpectationV"
  },
  "title" : "TrajectoryExpectation"
}
-->

# TrajectoryExpectation

The expected pattern of tool calls for an evaluation.

```
struct TrajectoryExpectation
```

## Overview

```swift
TrajectoryExpectation(ordered: [
    ToolExpectation("authenticate"),
    ToolExpectation("processResults"),
])
```

`TrajectoryExpectation` specifies expected tool-calling behavior across three axes:

- **Ordered**: Tool calls that must occur in a specific sequence. Use [`ToolExpectation`](/documentation/Evaluations/ToolExpectation)
  for single sequential steps, or [`anyOrder(_:)`](/documentation/Evaluations/ToolExpectation/anyOrder(_:)) when multiple tools must
  all be called at a given position but their relative order doesn’t matter.
- **Unordered**: Tool calls that must occur at some point, regardless of when.
- **Disallowed**: Tool calls that must NOT occur.

```swift
TrajectoryExpectation(ordered: [
    ToolExpectation("authenticate"),
    ToolExpectation("processResults"),
])
```

```swift
TrajectoryExpectation(ordered: [
    ToolExpectation("authenticate"),
    .anyOrder([
        ToolExpectation("fetchData"),
        ToolExpectation("fetchMetadata"),
    ]),
    ToolExpectation("processResults"),
], allowsAdditionalToolCalls: false)
```

```swift
TrajectoryExpectation(
    ordered: [
        ToolExpectation("findActivities"),
        ToolExpectation("estimateTravelTime"),
    ],
    unordered: [ToolExpectation("getWeather")],
    disallowed: [ToolExpectation("deleteData")]
)
```

```swift
TrajectoryExpectation(expected: "getWeather", arguments: [
    .exact(argumentName: "location", value: "Paris, France")
])
```

## Topics

### Creating a single-tool expectation

[`init(expected:arguments:)`](/documentation/Evaluations/TrajectoryExpectation/init(expected:arguments:))

Creates a trajectory expectation for a single expected tool call.

[`ToolExpectation`](/documentation/Evaluations/ToolExpectation)

A specification for an expected tool call, or a group of expectations
that can be satisfied in any order.

### Creating multi-tool expectations

[`init(ordered:unordered:allowsAdditionalToolCalls:)`](/documentation/Evaluations/TrajectoryExpectation/init(ordered:unordered:allowsAdditionalToolCalls:))

Creates a trajectory expectation with ordered and unordered requirements,
and controls whether unmatched tool calls are permitted.

[`init(ordered:unordered:disallowed:)`](/documentation/Evaluations/TrajectoryExpectation/init(ordered:unordered:disallowed:))

Creates a trajectory expectation with ordered and unordered requirements,
plus specific tools that the model must not call.

[`init(unordered:)`](/documentation/Evaluations/TrajectoryExpectation/init(unordered:))

Creates a trajectory expectation with only unordered requirements.

### Combining expectations

[`ordered`](/documentation/Evaluations/TrajectoryExpectation/ordered)

Tool call steps that must be satisfied in sequential order.

[`unordered`](/documentation/Evaluations/TrajectoryExpectation/unordered)

Tool calls that must occur at some point, regardless of position.

[`disallowed`](/documentation/Evaluations/TrajectoryExpectation/disallowed)

Tools that the model must NOT call.

[`allowsAdditionalCalls`](/documentation/Evaluations/TrajectoryExpectation/allowsAdditionalCalls)

A Boolean value that indicates whether to allow tool calls that don’t match any expectation.

## Relationships

### Conforms To

[`Escapable`](/documentation/Swift/Escapable)

[`Generable`](/documentation/FoundationModels/Generable)

[`Decodable`](/documentation/Swift/Decodable)

[`ConvertibleFromGeneratedContent`](/documentation/FoundationModels/ConvertibleFromGeneratedContent)

[`ConvertibleToGeneratedContent`](/documentation/FoundationModels/ConvertibleToGeneratedContent)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`Sendable`](/documentation/Swift/Sendable)

[`InstructionsRepresentable`](/documentation/FoundationModels/InstructionsRepresentable)

[`PromptRepresentable`](/documentation/FoundationModels/PromptRepresentable)

[`Copyable`](/documentation/Swift/Copyable)

[`Encodable`](/documentation/Swift/Encodable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)