Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

📦Build a Talus Agent Package in Move

Audience: Nexus adopters and integrators.

Goal: Create and validate a Talus Agent Package (TAP) Move package from the CLI scaffold, then hand the artifact to the dedicated binding and execution guides.

Prerequisites

  • A configured CLI and operator-supplied network objects file; see Developer Setup. For network-facing Move dependencies, use the reviewed nexus-interface, nexus-primitives, nexus-tool, nexus-registry, nexus-workflow, and nexus-scheduler Move Registry packages. Keep Move.lock and the selected network's published-address records together; use the public Nexus Move Packages source only for offline inspection or provenance.

  • A dotted Tool FQN such as example.taluslabs.transfer@1 and a design for the Agent-owned package state it will mutate.

  • Registered Tools and public references for the target deployment; do not assume an example FQN is live.

Create the CLI scaffold

Use nexus tap scaffold to create the package structure rather than copying a hand-written package listing from this guide:

PACKAGE_NAME=my-tap
nexus tap scaffold --name "$PACKAGE_NAME"
CONFIG="./$PACKAGE_NAME/skill.tap.json"
nexus tap validate-skill --config "$CONFIG"

The scaffold is the source of the package manifest, skill configuration, and generated file layout. Validation is intentionally the last network-independent step here: the scaffolded DAG still contains placeholder Tool references until you complete Configure DAG and Skill. Do not run publish-skill from an untouched scaffold, because package publication occurs before DAG publication and a later DAG failure can leave the package published. This guide does not promise a complete hand-written package implementation because Move APIs, package addresses, and deployment objects must match the selected network.

Preserve the package boundary

The TAP package owns its application state and may embed an Agent. Nexus owns the durable workflow lifecycle: Task creates an Occurrence, dispatch creates an Execution, and ExecutionPayment settles the run. Agent and skill metadata are recorded through Agent Registry APIs; the package should not recreate scheduler state or retired queue helpers.

For a standard on-chain Tool, the public entry begins with UIDRequirements, then OnchainToolResult, package state and declared inputs, and ends with &mut TxContext. An authorized Tool is prefixed by ProvenValue<AgentVertexAuthorization>. The Tool satisfies the registered requirement, builds one TaggedOutput from the supplied NexusValue payloads, and finalizes the result through the public on-chain-result surface. Treat these as interface patterns; validate the exact signature against the registered Tool schema and public references before compiling.

Test Task creation and inspection with an extension

Keep the released TAP manifest's edition = "2024". Put module-extension tests in a sibling consumer package such as move-tests/, whose Move.toml opts into the alpha edition required by extensions:

Add move-tests/tests/task_extension.move. This extension constructs the minimal stable Task wrapper and exposes only the identity and TaskStatus shapes that local application tests need:

Call those helpers through the module they extend in move-tests/tests/task_tests.move:

Run the isolated harness against the selected dependency graph:

The fixture does not recreate scheduler storage: it has no TaskInnerV1, authorization, payment reserve, schedule, occurrence records, or lifecycle transitions. Existing nexus_scheduler::task constructors and inspectors remain local stubs and abort when called in a Move unit test. Use the extension only for application logic that needs a Task identity or status value, and use a Testnet integration transaction to create and inspect a real Task. This package is intentionally Nexus-free, so its plain sui move test gate is safe. See Local Move tests with module extensions for the full evidence boundary.

Test a published Nexus function in a separate local package

Keep tests that call a published Nexus function out of move-tests/: the plain Move VM sees the interface stub and should report ELocalExecutionUnavailable. Create a second sibling package, move-tests-published/, for the released published-bytecode harness. This is an explicit local test arrangement, not a second TAP application track:

Use an alpha-edition test package so the extension can construct the smallest value needed by the published data API:

Add tests/data_extension.move:

Add tests/data_tests.move and call the published functions directly:

Run only this package with the released binary from Developer Setup:

The harness reads the selected public Nexus bytecode and overlays only the test extension in memory. It needs network read access to published bytecode, but no wallet, signer, gas, publication, registration, or scheduling. A green result proves the exercised published data call and local arrangement; it does not prove that the TAP package, Tool, DAG, or skill has been published or bound. Keep sui move test --path move-tests for the Nexus-free Task value-shape test and use a Testnet transaction for live Nexus behavior.

Verify the scaffolded artifact

  1. Validate the scaffolded skill and inspect every referenced Tool FQN, schema, and selected mode.

  2. Record the validated skill.tap.json path and the package/DAG files that still need deployment-specific Tool references.

  3. Stop before publication. Configuring the real DAG, publishing the package and DAG, binding the artifact to an Agent, and creating Task → Occurrence → Execution evidence require additional command inputs and are covered by the linked follow-up guides.

Expected artifacts here are the local scaffolded package and a metadata-valid skill.tap.json; no package or DAG has been published yet. Test-only helpers belong only in test modules and are not production API guidance.

Failures and recovery

  • Tool schema or FQN mismatch: correct the package/registration contract or use a new versioned dotted FQN; do not force an incompatible DAG binding.

  • Authorization failure: verify the exact Agent, skill, vertex, recipient, and requirement proof before changing package state.

  • Settlement or ToolCashier gap: inspect the durable Task/Occurrence/Execution evidence. There is no generic high-level non-expired reconciliation command; use the public references and approved integration boundary rather than improvising a transaction.

Next

Continue with Configure DAG and Skill, Publish, Register, Bind, and Execute and Verify Transfer.

Last updated