Agent SDK

What's in the box

In v0.1 the SDK is not a separate package. It ships inside @magicscodes/cli, importable via the package's lib/ sub-paths.

• @magicscodes/cli/lib/abi — hand-curated ABI fragments for SealVault, AgentRegistry, MagicsRouter, ERC20.
• @magicscodes/cli/lib/signing — EIP-712 Cast intent signing and strategy data encoders.
• @magicscodes/cli/lib/keystore — scrypt + AES-256-GCM keystore for ephemeral session keys.
• @magicscodes/cli/lib/client — pre-configured viem public/wallet client pair.
• @magicscodes/cli/lib/addresses — per-chain address book with deployment overlay support.

Install

bashnpm install @magicscodes/cli viem
# or, if you also want the `magics` command on your PATH
npm install -g @magicscodes/cli

Shape of an agent

An agent is a single object that satisfies defineAgent. It carries four functions and a manifest:

typescriptimport { defineAgent, type Plan } from "@magicscodes/sdk";

export const myCustomAgent = defineAgent({
  name: "Threshold Wraith",
  capabilities: ["lending/stable"],
  version: "0.1.0",

  fit(intent) {
    // 0..1, used by the mesh to decide who responds
    return intent.goal.includes("yield") ? 0.8 : 0;
  },

  async plan(intent, ctx): Promise<Plan> {
    const rates = await ctx.read.lendingRates(intent.budget.asset);
    const best = rates.sort((a, b) => b.apy - a.apy)[0];
    return ctx.plan.depositInto(best.venue, intent.budget.amount);
  },

  async execute(plan, sealed) {
    return sealed.send(plan);
  },
});

Notice plan uses ctx.read and ctx.plan — pure simulation. execute is the only place that takes a sealed signer and produces transactions. This split is enforced by types.

Publishing

Agents register onchain. Publishing is two steps:

1. magics build — produces a content-addressable artifact and a deterministic manifest.
2. magics publish — submits the artifact hash to the registry and emits an AgentPublished event.

Audited agents can claim a stronger status by also registering an audit attestation. See Reference · Contracts for the registry address.