Capabilities

A capability is a named piece of work your service offers. It describes the input it accepts, the result it produces, and what it charges. Your handler performs that work. The toolkit supplies the payment and job protocol around it. The service still depends on the external providers and credentials you choose.

The caller's contract

A capability has a stable name, an input schema, and a price or quote rule. The schema describes the input before the caller pays. A useful example lets an agent understand the capability without guessing how to call it.

The handler receives validated input and produces text, artifacts, or both. Completion marks the job's result. A returned artifact should have a useful name and media type so the caller knows how to consume it.

One DVM can expose several capabilities. Keep a capability's name stable when changing its implementation; callers use that name to dispatch work. The SDK reference specifies single- and multi-capability descriptors and the wire format.

Price and cost

The price is what the caller agrees to pay. Your costs include hosting and any external API the handler calls. Those costs can occur even if the job fails and the caller is not charged.

A fixed price covers a known piece of work. An input-dependent quote can state a different amount before the job starts. Work that needs an additional payment must request it through the SDK's payment flow. Pricing and dynamic quotes define the available forms.

A test-spend cap is separate from the published price. It bounds what the agent may spend while proving the service. A successful free local call gives no evidence that the payment configuration works.

State and retries

A handler can keep per-job state or use storage shared across its jobs. The storage's lifetime depends on the host: a development process can discard it on exit; a production service needs durable stores.

A job may resume after interruption. External effects, such as a paid provider request, need an idempotency strategy so resuming work does not repeat the charge. Use the SDK's durable steps and the provider's own idempotency mechanism where available.

The SDK owns payment verification, credit holds, job messages, and receipts. Application storage is not a replacement for its credit ledger. Persistence and the job context define the boundary.

Evidence that the capability works

A handler test checks the input, output, failure behavior, and side effects you control. A live provider check establishes whether a third-party API accepts the request the handler actually sends. A paid call proves the configured payment path as well as the result.

These answer different questions. Mocking a provider cannot establish its current request contract, and a signed receipt cannot establish that an artifact is useful. The installed skill's testing procedure selects the evidence needed for the change.