> For the complete documentation index, see [llms.txt](https://docs.talus.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talus.network/reference/move/nexus_workflow/execution.md).

# execution

* [Struct `CommittedToolResult`](#struct-committedtoolresult)
* [Struct `CommittedToolResultLeaderRecord`](#struct-committedtoolresultleaderrecord)
* [Struct `CommittedToolResultKey`](#struct-committedtoolresultkey)
* [Struct `OnchainToolResultKey`](#struct-onchaintoolresultkey)
* [Struct `ExecutionPaymentInsufficientSettlementFieldKey`](#struct-executionpaymentinsufficientsettlementfieldkey)
* [Struct `ExecutionPaymentInsufficientSettlement`](#struct-executionpaymentinsufficientsettlement)
* [Struct `DAGExecution`](#struct-dagexecution)
* [Struct `DAGExecutionInnerV1`](#struct-dagexecutioninnerv1)
* [Struct `AgentGrantFieldKey`](#struct-agentgrantfieldkey)
* [Struct `DagExecutionPaymentFieldKey`](#struct-dagexecutionpaymentfieldkey)
* [Struct `TerminalErrEvalRecord`](#struct-terminalerrevalrecord)
* [Struct `SubmissionFailureRecord`](#struct-submissionfailurerecord)
* [Struct `WalkRequestAuthority`](#struct-walkrequestauthority)
* [Enum `DAGWalk`](#enum-dagwalk)
* [Enum `WalkRequestAuthorityPhase`](#enum-walkrequestauthorityphase)
* [Constants](#constants)
* [Function `has_vertex_authorization_grant`](#function-has_vertex_authorization_grant)
* [Function `assert_complete_authorization_bindings`](#function-assert_complete_authorization_bindings)
* [Function `interface_version`](#function-interface_version)
* [Function `task_id`](#function-task_id)
* [Function `occurrence_id`](#function-occurrence_id)

### Struct `CommittedToolResult`

A tool result committed for a walk and held until payment settlement, tracking the accepted output, primary and secondary failure evidence, and per-leader gas records.

```move
public struct CommittedToolResult has store
```

<details>

<summary>Fields</summary>

`expected_vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)`variant:` [`nexus_interface::graph::OutputVariant`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_OutputVariant)`variant_ports_to_data: sui::vec_map::VecMap<`[`nexus_interface::graph::OutputPort`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_OutputPort)`,` [`nexus_primitives::data::NexusData`](/reference/move/nexus_primitives/data.md#nexus_primitives_data_NexusData)`>failure_evidence_kind: std::option::Option<`[`nexus_interface::verifier::FailureEvidenceKind`](/reference/move/nexus_interface/verifier.md#nexus_interface_verifier_FailureEvidenceKind)`>primary_failure_evidence_kind: std::option::Option<`[`nexus_interface::verifier::FailureEvidenceKind`](/reference/move/nexus_interface/verifier.md#nexus_interface_verifier_FailureEvidenceKind)`>secondary_failure_evidence_kind: std::option::Option<`[`nexus_interface::verifier::FailureEvidenceKind`](/reference/move/nexus_interface/verifier.md#nexus_interface_verifier_FailureEvidenceKind)`>current_leader_cap_id: sui::object::IDhas_finalized_onchain_payload: boolleader_records: sui::vec_map::VecMap<sui::object::ID,` [`nexus_workflow::execution::CommittedToolResultLeaderRecord`](#nexus_workflow_execution_CommittedToolResultLeaderRecord)`>`

</details>

#### Struct `CommittedToolResultLeaderRecord`

Per-leader commit metadata lives inside [`CommittedToolResult`](#nexus_workflow_execution_CommittedToolResult) because settlement must atomically inspect the accepted payload and all submitted gas charges for a walk.

```move
public struct CommittedToolResultLeaderRecord has copy, drop, store
```

<details>

<summary>Fields</summary>

`commit_tx_digest: vector<u8>recipient: addresscommit_gas_charge: std::option::Option<u64>settlement_gas_charge: std::option::Option<u64>`

</details>

#### Struct `CommittedToolResultKey`

Dynamic field key for a walk's committed tool result awaiting settlement.

```move
public struct CommittedToolResultKey has copy, drop, store
```

<details>

<summary>Fields</summary>

`walk_index: u64`

</details>

#### Struct `OnchainToolResultKey`

Dynamic field key for the per-walk on-chain result object ID; [`CommittedToolResultKey`](#nexus_workflow_execution_CommittedToolResultKey) cannot be reused because committed outputs and pre-commit result IDs have different lifecycles.

```move
public struct OnchainToolResultKey has copy, drop, store
```

<details>

<summary>Fields</summary>

`walk_index: u64`

</details>

#### Struct `ExecutionPaymentInsufficientSettlementFieldKey`

Dynamic field key for the record of walks blocked because the execution payment cannot cover their pending gas charges.

```move
public struct ExecutionPaymentInsufficientSettlementFieldKey has copy, drop, store
```

<details>

<summary>Fields</summary>

</details>

#### Struct `ExecutionPaymentInsufficientSettlement`

The set of walk indices whose settlement is blocked by insufficient execution payment.

```move
public struct ExecutionPaymentInsufficientSettlement has drop, store
```

<details>

<summary>Fields</summary>

`walks: vector<u64>`

</details>

#### Struct `DAGExecution`

Runtime execution of \[DAG] comprises walking the graph by evaluating vertices and following the edges.

```move
public struct DAGExecution has key
```

<details>

<summary>Fields</summary>

`id: sui::object::UID`

</details>

#### Struct `DAGExecutionInnerV1`

Version one stored layout for \[[`DAGExecution`](#nexus_workflow_execution_DAGExecution)].

```move
public struct DAGExecutionInnerV1 has store
```

<details>

<summary>Fields</summary>

`dag: sui::object::ID`DAG executed by this object.`entry_group:` [`nexus_interface::graph::EntryGroup`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_EntryGroup)Entry group selected when the execution starts.`invoker: address`Address that invoked the DAG.`created_at: u64`Clock timestamp when the execution was created.`priority_fee_percentage: u64`The normalized priority fee applied to the execution payment.`agent_id: sui::object::ID`Agent identity pinned by the resolved execution target.`skill_id: u64`Skill identity pinned by the resolved execution target.[`interface_version`](#nexus_workflow_execution_interface_version)`:` [`nexus_interface::version::InterfaceVersion`](/reference/move/nexus_interface/version.md#nexus_interface_version_InterfaceVersion)Interface version pinned for this execution.[`task_id`](#nexus_workflow_execution_task_id)`: sui::object::ID`Task that produced this execution.[`occurrence_id`](#nexus_workflow_execution_occurrence_id)`: u64`Scheduled occurrence identity within the Task.`last_request_for_execution_emitted_at_digest: vector<u8>`Digest of the latest transaction that emitted an off-chain Tool request. Empty until the first \[`RequestWalkExecutionEvent`] is emitted. Helps us guarantee that when a tx is over it will have emitted only valid events, not ones that were superseded by a newer request for execution. This would happen if e.g. two on-chain tools were invoked in a single tx. It's still possible, but thanks to emitted request tracking and this field we can skip emitting events for all but the last tool(s).`last_request_for_execution_leaders: vector<sui::object::ID>`Assigned leaders for the latest emitted \[RequestWalkExecutionEvent]. Persist the assignment rather than recomputing it from the live registry so later submissions are checked against the original request leaders.`network: sui::object::ID`Leader network whose capabilities authorize request handling and result submission for this DAG. Only `CloneableOwnerCap<leader_cap::OverNetwork>` values bound to this ID carry that authority.`evaluations: sui::object_table::ObjectTable<`[`nexus_interface::graph::Vertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_Vertex)`,` [`nexus_interface::graph::VertexEvaluations`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_VertexEvaluations)`>`Submitted values that are fed to the relevant input ports. Dynamic object fields so that they can be queried.`terminal_records: sui::vec_map::VecMap<u64,` [`nexus_workflow::execution::TerminalErrEvalRecord`](#nexus_workflow_execution_TerminalErrEvalRecord)`>`Authoritative per-walk `_err_eval` records keyed by walk index.`submission_failure_records: sui::vec_map::VecMap<u64, vector<`[`nexus_workflow::execution::SubmissionFailureRecord`](#nexus_workflow_execution_SubmissionFailureRecord)`>>`Persisted per-walk leader submission-failure records keyed by walk index.`pending_retry_handoff_cap_ids: sui::vec_map::VecMap<u64, sui::object::ID>`While a dedicated retry handoff is pending, only this cap may submit the affected walk.`walk_request_authorities: sui::vec_map::VecMap<u64,` [`nexus_workflow::execution::WalkRequestAuthority`](#nexus_workflow_execution_WalkRequestAuthority)`>`Authoritative per-walk primary/secondary ownership and takeover state.`pending_payment_settlements: sui::vec_map::VecMap<`[`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)`,` [`nexus_workflow::execution_failure::VertexPaymentSettlement`](/reference/move/nexus_workflow/execution_failure.md#nexus_workflow_execution_failure_VertexPaymentSettlement)`>`Tool payment settlement directives keyed by evaluated runtime vertex.`walks: vector<`[`nexus_workflow::execution::DAGWalk`](#nexus_workflow_execution_DAGWalk)`>`Concurrent \[[`DAGWalk`](#nexus_workflow_execution_DAGWalk)] values and their lifecycle states.`active_walks: u64`Count of walks currently waiting for a vertex result.`pending_abort_walks: u64`Count of walks whose abort is waiting on other active walks to settle.`pending_settlement_walks: u64`Count of walks with a committed result waiting for explicit settlement.`successful_walks: u64`Count of walks that reached an end state successfully.`failed_walks: u64`Count of walks that failed without aborting the whole execution.`aborted_walks: u64`Count of walks that terminally aborted the execution.`consumed_walks: u64`Count of walks consumed while waiting for converged inputs or spawned branches.`cancelled_walks: u64`Count of walks cancelled after another walk failed or aborted.

</details>

#### Struct `AgentGrantFieldKey`

Dynamic field key for a per-vertex agent authorization grant stored on an execution, discriminated by grant kind.

```move
public struct AgentGrantFieldKey has copy, drop, store
```

<details>

<summary>Fields</summary>

`vertex: std::ascii::Stringkind: vector<u8>`

</details>

#### Struct `DagExecutionPaymentFieldKey`

Dynamic object field key for the execution's attached TAP payment object.

```move
public struct DagExecutionPaymentFieldKey has copy, drop, store
```

<details>

<summary>Fields</summary>

</details>

#### Struct `TerminalErrEvalRecord`

The authoritative record of a walk's terminal `_err_eval` outcome, capturing the failing vertex, leader, failure class, resolved post-failure action, and the evidence hash used to converge duplicate submissions.

```move
public struct TerminalErrEvalRecord has copy, drop, store
```

<details>

<summary>Fields</summary>

`walk_index: u64vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)`leader: addressfailure_class:` [`nexus_workflow::execution_failure::WorkflowFailureClass`](/reference/move/nexus_workflow/execution_failure.md#nexus_workflow_execution_failure_WorkflowFailureClass)`outcome: std::option::Option<`[`nexus_interface::graph::PostFailureAction`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_PostFailureAction)`>reason: std::ascii::Stringvariant_ports_to_data: sui::vec_map::VecMap<`[`nexus_interface::graph::OutputPort`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_OutputPort)`,` [`nexus_primitives::data::NexusData`](/reference/move/nexus_primitives/data.md#nexus_primitives_data_NexusData)`>err_eval_hash: vector<u8>`

</details>

#### Struct `SubmissionFailureRecord`

A record of one leader's failed submission for a walk, naming the failed leader, the winning leader that took over if any, and the evidence hash.

```move
public struct SubmissionFailureRecord has copy, drop, store
```

<details>

<summary>Fields</summary>

`walk_index: u64vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)`failed_leader: addresswinning_leader: std::option::Option<address>reason: std::ascii::Stringerr_eval_hash: vector<u8>`

</details>

#### Struct `WalkRequestAuthority`

Per-walk ownership state assigning a primary and secondary leader cap to the walk's requested vertex, its current authority phase, and whether a secondary takeover has been recorded.

```move
public struct WalkRequestAuthority has copy, drop, store
```

<details>

<summary>Fields</summary>

`vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)`primary_cap_id: sui::object::IDsecondary_cap_id: sui::object::IDphase:` [`nexus_workflow::execution::WalkRequestAuthorityPhase`](#nexus_workflow_execution_WalkRequestAuthorityPhase)`takeover_recorded: bool`

</details>

#### Enum `DAGWalk`

Each \[DAGWalk] represents a unique path through the \[DAG].

```move
public enum DAGWalk has copy, drop, store
```

<details>

<summary>Variants</summary>

Variant `Activenext_vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)Vertex that should be executed next.`timeout_ms: u64`Timeout for the walk, taken from the tool configuration.`requires_vertex_authorization_grant: bool`Whether this on-chain vertex requires an execution-child workflow authorization grant before it can be scheduled.`created_at: u64`Timestamp at which the current request stage began. Invocation authorization and executable Tool work are separate stages, so this value advances when authorization creates the executable request. Expiry is evaluated as \`created\_at + 2 × timeout\_ms\`.Variant `PendingSettlementnext_vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)Committed vertex waiting for payment settlement.`timeout_ms: u64`Timeout for the walk, taken from the tool configuration.`requires_vertex_authorization_grant: bool`Whether this on-chain vertex requires an execution-child workflow authorization grant before it can be scheduled.`created_at: u64`Creation timestamp used to determine pending-settlement expiry as \`created\_at + 2 × timeout\_ms\`.Variant `Successful`Variant `Failed`Variant `Consumedat_vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)Variant `Aborted`A walk is aborted when `_err_eval` resolves to `Terminate`. If an execution already contains an aborted walk, later active walks are still allowed to submit results but once they do, they are marked as \[`DAGWalk::Cancelled`].`at_vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)Variant `PendingAbort`A walk is pending abort after double timeout when its vertex payment has been unlocked, but other active walks still need to settle.`at_vertex:` [`nexus_interface::graph::RuntimeVertex`](/reference/move/nexus_interface/graph.md#nexus_interface_graph_RuntimeVertex)Variant `Cancelled`

</details>

#### Enum `WalkRequestAuthorityPhase`

The stage of leader ownership for a walk request: the primary leader's exclusive window, the secondary leader's takeover window, or a retry handed off exclusively to the secondary.

```move
public enum WalkRequestAuthorityPhase has copy, drop, store
```

<details>

<summary>Variants</summary>

Variant `PrimaryWindow`Variant `SecondaryWindow`Variant `SecondaryOnlyRetry`

</details>

#### Constants

```move
#[error, test_only]
const EAgentMismatch: vector<u8> = b"Provided Agent object does not match agent execution config";
```

```move
#[error, test_only]
const EAgentVertexAuthorizationAlreadyExists: vector<u8> = b"Workflow agent vertex authorization already exists";
```

```move
#[error, test_only]
const EAgentVertexAuthorizationToolNotCapFirst: vector<u8> = b"On-chain tool is not registered for workflow authorization";
```

```move
#[error, test_only]
const ENotEntryGroup: vector<u8> = b"Provided entry group is not this DAG's entry group";
```

```move
#[error, test_only]
const EExpectedGasChargeOverflow: vector<u8> = b"Expected committed result gas charge overflow";
```

```move
#[error]
const ENotAnEntryVertex: vector<u8> = b"This vertex is not in the entry group";
```

```move
#[error]
const ENotAnEntryVertexPort: vector<u8> = b"This vertex-port pair is not in the entry group";
```

```move
#[error]
const EWalkAlreadyRequested: vector<u8> = b"Walk already has active request authority";
```

```move
#[error]
const ENetworkMismatch: vector<u8> = b"Provided network ID does not match expected network ID";
```

```move
#[error]
const EExpectedOffchainTool: vector<u8> = b"Expected an off-chain tool";
```

```move
#[error]
const EExpectedOnchainTool: vector<u8> = b"Expected an on-chain tool";
```

```move
#[error]
const EWalkNotActive: vector<u8> = b"The walk must be active to do this";
```

```move
#[error]
const EPermissionlessSettlementNotReady: vector<u8> = b"Committed tool result is not ready for permissionless settlement";
```

```move
#[error]
const EExpiredWalkHasOnchainToolResult: vector<u8> = b"Expired walk has an on-chain tool result and must be consumed before abort";
```

```move
#[error]
const ECommittedToolResultMissing: vector<u8> = b"Committed tool result is missing";
```

```move
#[error]
const EWalkDoesNotExpectThisVertex: vector<u8> = b"The client provided vertex that the walk does not expect";
```

```move
#[error]
const EInvokedVertexNotEvaluated: vector<u8> = b"The invoked vertex has not been evaluated";
```

```move
#[error]
const EInvocationLockMissing: vector<u8> = b"Tool execution requires an exact Invocation lock";
```

```move
#[error]
const EEntryGroupWrongNumberOfInputs: vector<u8> = b"Entry group input does not have the expected number of vertices";
```

```move
#[error]
const EExecutionMismatch: vector<u8> = b"Provided execution ID does not match expected execution ID";
```

```move
#[error]
const ECommittedToolResultLeaderMismatch: vector<u8> = b"Committed tool result leader cap does not match provided leader cap";
```

```move
#[error]
const ECommittedToolResultGasChargeAlreadySubmitted: vector<u8> = b"Committed tool result gas charge was already submitted";
```

```move
#[error]
const ECommittedToolResultGasChargeOverflow: vector<u8> = b"Committed tool result gas charge is not representable";
```

```move
#[error]
const ECommittedToolResultDigestMismatch: vector<u8> = b"Committed tool result transaction digest does not match";
```

```move
#[error]
const EDAGMismatch: vector<u8> = b"Provided DAG ID does not match expected DAG ID";
```

```move
#[error]
const EDAGEntryGroupResultsInNoWork: vector<u8> = b"The DAG is likely misconfigured as there are no walks to spawn";
```

```move
#[error]
const EMultipleForEachInputs: vector<u8> = b"A runtime vertex may receive at most one ForEach input";
```

```move
#[error]
const EMissingVertexAuthorizationBinding: vector<u8> = b"A required vertex authorization binding is missing";
```

```move
#[error]
const EUnexpectedVertexAuthorizationBinding: vector<u8> = b"A vertex authorization binding does not name a required DAG vertex";
```

```move
#[error]
const ERequiredVertexAuthorizationGrantMissing: vector<u8> = b"An admitted execution is missing a required vertex authorization grant";
```

```move
#[error]
const EExecutionNotAborted: vector<u8> = b"The execution is not aborted yet";
```

```move
#[error]
const EUnreachable: vector<u8> = b"unreachable!";
```

```move
#[error]
const ETerminalErrEvalConflict: vector<u8> = b"Duplicate terminal _err_eval does not match the accepted terminal record";
```

```move
#[error]
const EWalkAuthorityMissing: vector<u8> = b"Walk authority is not assigned";
```

```move
#[error]
const ERetryHandoffSubmitterMismatch: vector<u8> = b"Retry handoff submitter does not match the assigned primary leader";
```

```move
#[error]
const EExecutionNotSuccessful: vector<u8> = b"The execution is not finished successfully";
```

```move
#[error]
const EExecutionNotFinished: vector<u8> = b"The execution is not finished";
```

```move
#[error]
const EExecutionPaymentMissing: vector<u8> = b"TAP execution payment is missing";
```

```move
#[error]
const EExecutionPaymentAlreadyExists: vector<u8> = b"TAP execution payment already exists";
```

```move
#[error]
const EExecutionPaymentRefillNotAllowed: vector<u8> = b"TAP execution payment refill is not allowed in this execution state";
```

```move
#[error]
const EExecutionPaymentHasLocks: vector<u8> = b"TAP execution payment has locks";
```

```move
#[error]
const EWorksheetRequiredStampMissing: vector<u8> = b"Worksheet is missing a required stamp";
```

```move
#[error]
const EWorksheetUnexpectedStampCount: vector<u8> = b"Worksheet contains extra or duplicate-unchecked stamps";
```

```move
#[error]
const EOnchainToolResultAlreadyExists: vector<u8> = b"On-chain tool result already exists for this walk";
```

```move
#[error]
const EOnchainToolResultMissing: vector<u8> = b"On-chain tool result is missing for this walk";
```

```move
#[error]
const EOnchainToolResultMismatch: vector<u8> = b"On-chain tool result does not match the stored walk result ID";
```

```move
const MAX_LOOP_ITERATIONS: u64 = 255;
```

```move
const WALK_STATUS_ACTIVE: u8 = 0;
```

```move
const WALK_STATUS_PENDING_ABORT: u8 = 1;
```

```move
const WALK_STATUS_SUCCESSFUL: u8 = 2;
```

```move
const WALK_STATUS_FAILED: u8 = 3;
```

```move
const WALK_STATUS_ABORTED: u8 = 4;
```

```move
const WALK_STATUS_CONSUMED: u8 = 5;
```

```move
const WALK_STATUS_CANCELLED: u8 = 6;
```

```move
const WALK_STATUS_PENDING_SETTLEMENT: u8 = 7;
```

#### Function `has_vertex_authorization_grant`

Whether an agent vertex authorization grant is stored for the given runtime vertex.

```move
public fun has_vertex_authorization_grant(execution: &nexus_workflow::execution::DAGExecution, vertex: nexus_interface::graph::RuntimeVertex): bool
```

#### Function `assert_complete_authorization_bindings`

Verifies that authorization bindings exactly cover the vertices that need them.

A binding is required for every \[`Vertex`] whose onchain \[`ToolRegistry`] definition requires workflow authorization. Bindings for any other vertex are rejected, including names that are absent from the \[`DAG`]. Exact coverage makes missing authorization unreachable after execution admission.

```move
public fun assert_complete_authorization_bindings(dag: &nexus_interface::dag::DAG, tool_registry: &nexus_tool::tool_registry::ToolRegistry, bindings: &sui::vec_map::VecMap<nexus_interface::graph::Vertex, sui::object::ID>)
```

#### Function `interface_version`

Interface version pinned when \[[`DAGExecution`](#nexus_workflow_execution_DAGExecution)] was created.

```move
public fun interface_version(self: &nexus_workflow::execution::DAGExecution): nexus_interface::version::InterfaceVersion
```

#### Function `task_id`

Returns the Task that produced this execution.

```move
public fun task_id(self: &nexus_workflow::execution::DAGExecution): sui::object::ID
```

#### Function `occurrence_id`

Returns the scheduled occurrence identity.

```move
public fun occurrence_id(self: &nexus_workflow::execution::DAGExecution): u64
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.talus.network/reference/move/nexus_workflow/execution.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.