> 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/talus-docs-v2.1.0/guides/agent-usage/agent-builder-guide.md). # Choose an Agent Architecture {% hint style="info" %} **Audience:** Junior Nexus developers choosing an Agent architecture before writing packages or scheduling work. **Goal:** Choose the smallest Agent, Tool, funding, scheduling, and authorization model that safely produces the durable artifacts your application needs. {% endhint %} Use this page before scaffolding. It is a decision guide: after you choose a path, follow the linked task guide for exact commands and verification.
Choose an Agent boundary before publishing a DAG

Phase 1: Choose an Agent boundary before publishing a DAG.

Bind a Task and create its execution payment

Phase 2: Bind a Task and create its execution payment.

Resolve an exact Invocation through ToolCashier

Phase 3: Resolve an exact Invocation through ToolCashier.

The architecture figure separates the builder’s identity choice from the durable runtime path: the deployment-operator-provisioned, registry-owned default executor, a registry Agent with named SkillRecords, and a Talus Agent Package (TAP) with package-specific state all converge on Task, Occurrence, Execution, and payment. The dashed branch is the exact policy-backed Invocation and receipt path. If a hosted view omits those fields, verify them through matching CLI/SDK object reads and transaction effects instead of treating the UI projection as a second payment model. ### Prerequisites * Complete [Developer Setup](/talus-docs-v2.1.0/guides/getting-started/setup.md) with the pinned CLI, authenticated network objects, signer, and SUI address-balance funding. * Know which Tool FQNs and DAG schemas exist on the target network; inspect them rather than assuming example Tools are deployed. * Decide which application state or assets, if any, must remain under package-specific Move authorization. #### Choose the identity and state boundary | Need | Choose | Durable result | Continue with | | ------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | Run a published DAG without a custom identity | The registry-owned default Agent and an address-controlled Task | Task → Occurrence → Execution evidence tied to the selected DAG | [Schedule an Asset-Management Flow](/talus-docs-v2.1.0/guides/agent-usage/schedule-asset-management-flow.md) | | Reuse named skills under one on-chain identity | A registry Agent with `SkillRecord`s | Agent identity, active skill revision, DAG/payment/schedule requirements | [Build an Agent Package](/talus-docs-v2.1.0/guides/agent-usage/build-agent-package.md) | | Keep application assets and an Agent inside one Move package | A Talus Agent Package (TAP) | Package state plus embedded Agent and package-specific authority | [Scaffold a TAP](/talus-docs-v2.1.0/guides/tap-development/scaffold-and-package.md) | Choose a TAP only when the package must enforce state or custody invariants that generic Nexus objects cannot enforce. An Agent is an identity/custody handle; its active skill metadata lives in `AgentRegistry`. **Default-DAG prerequisite** The default-Agent row assumes the deployment operator has already bootstrapped the registry-owned default DAG executor. Before choosing `--dag-id`, run `nexus tap default-agent show --json` and record the configured Agent/skill and runtime-selected target. If readback reports `AgentRegistry missing default agent` or the on-chain lookup raises `EDefaultDagExecutorMissing`, hand setup to the deployment operator; builders do not create this shared executor through a normal Task command. #### Choose the Tool boundary | Work | Choose | Security boundary | | --------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | | External API, model, or off-chain computation | Off-chain HTTP Tool | HTTPS transport, optional RegisteredKey or External verification, runtime-held secrets | | Atomic on-chain state change | Standard on-chain Tool | Registered schema and witness; any compatible caller can invoke unless the package adds authority checks | | Agent-asset mutation | WorkflowAuthorization on-chain Tool | Recipient-bound `AgentVertexAuthorization` plus package-specific capability, sender, amount, and state checks | Fixed Tools record required FQNs in a skill and make registration check that each FQN is registered at transaction time; they do not independently prove DAG membership, stored registry-ID correspondence, or asset authority. Read back the selected DAG vertex, Tool ID, registry ID, and schema after binding. Build the chosen Tool through [Tool Development](/talus-docs-v2.1.0/guides/tool-development.md) before binding its FQN into a DAG. #### Choose who funds each run * **User-funded:** the submitting signer funds `TaskPaymentReserve` from an address balance and is the address-controlled Task's controller; unused scheduled funds return through the recorded `refund_recipient` path, which may be a different UserFunded beneficiary. * **Agent-funded:** the matching `AgentPaymentVault` funds the reserve, subject to the skill's `max_budget_mist`; unused funds return to that Agent vault. Both paths still use the submitter's SUI address balance or an explicit gas coin for immediate transaction gas. Tool charges, eligible Leader reimbursement, and priority charges settle inside `ExecutionPayment`; they are not the same as submission gas. > **Before executing a workflow:** Verify that the selected client, generated bindings, package IDs, and transaction effects agree with the target network. When a hosted projection omits Invocation fields, use direct object/effect reads rather than substituting a FQN, cashier candidate, or UI label. **Verify the settlement outcome** Create a Task, observe its Occurrence, follow the linked Execution, inspect the `ExecutionPayment` lock and exact Invocation, settle the Occurrence, and reconcile the Task reserve before closing. The caller may choose an accepted policy after skill and DAG checks pass, while the Tool owner controls which policies the ToolCashier accepts. Read [Invocation policy and settlement model](/talus-docs-v2.1.0/concepts/06-payment-vaults-reserves-and-settlement.md#invocation-policy-and-settlement-model) before choosing FixedPrice, including price zero, FiniteCredits, TimePass, or a custom policy. Record the Invocation ID, lock, settlement/refund receipt, and transaction effects; do not treat a ToolCashier capability as a general execution grant. #### Choose timing and lifecycle * Use `--now` for an immediately eligible Occurrence under a Task. * Use standalone future Occurrences for known one-off times. * Use one lazy Recurrence for bounded periodic work. Every path is Task → Occurrence → Execution. Existing Tasks pin the resolved Agent, skill, interface revision, inputs, and authorization. Close scheduled Tasks before updating that Skill; new work cannot select an obsolete revision. #### Verification checklist 1. Inspect every Tool FQN, schema, verifier support, and registration state. 2. Validate the DAG and confirm every entry/default/output port matches those live schemas. 3. Read back the Agent skill’s active revision, payment policy, schedule policy, input commitment, and fixed Tools. 4. Create one Task and record its controller, funding source, reserve, and first Occurrence. 5. Follow the Execution, inspect each `ExecutionPaymentVertexLock` with its exact Invocation ID and lock/settlement receipt, settle the Occurrence, and verify the Task reserve/refund state before calling the flow complete. 6. If a hosted projection omits Invocation reads, use selected-build help, matching bindings, direct object reads, and transaction effects; record the projection gap rather than accepting weaker identity evidence. #### Common mistakes and recovery * **Choosing a TAP for metadata only:** use a registry Agent unless package-owned state or authority is required. * **Treating a fixed Tool as authorization:** add an authorized Tool entry and package checks; do not move real assets through the disposable Standard-mode tutorial. * **Updating a Skill with live Tasks:** the registry can advance or deactivate the active contract while older Tasks remain open; those Tasks keep their snapshot and may become stale or inactive at admission. Close an idle old Task and create new Tasks from the new revision when the workflow must adopt it. * **Assuming examples are deployed:** replace example FQNs and schemas with inspected network records before DAG validation. * **Closing before settlement:** finish the Execution, resolve its exact Invocation, settle the Occurrence, and reconcile the reserve before closing the Task. #### Next Continue with [Build an Agent Package](/talus-docs-v2.1.0/guides/agent-usage/build-agent-package.md) for a registry Agent, [Scaffold a TAP](/talus-docs-v2.1.0/guides/tap-development/scaffold-and-package.md) for package-owned state, or [Schedule an Asset-Management Flow](/talus-docs-v2.1.0/guides/agent-usage/schedule-asset-management-flow.md) for a default-Agent DAG. --- # 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/talus-docs-v2.1.0/guides/agent-usage/agent-builder-guide.md?ask=&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.