Agents

type Agent = {
  /** Stable user-provided identifier (e.g., "research-bot"). */
  id: string;
  /** "active" — at least one activated (non-revoked) signer is attached.
   *  "no_permissions" — no activated signer yet. */
  status: "no_permissions" | "active";
  mode: "test" | "live";
  /** ISO 8601 timestamp. */
  created_at: string;
  /** Account slug the agent belongs to. Use to build dashboard deep-links
   *  (e.g., guide the user to grant a permission). */
  account_slug: string;
  /** Count of non-revoked, activated signers. */
  active_signers: number;
  /** Count of non-revoked, not-yet-activated signers. */
  pending_signers: number;
  /** Wallets this agent has active permission to spend from. Empty array
   *  if no active grants. Pick one for `tally.payments.create({ wallet })`. */
  wallets: Array<{
    address: string;
    display_name: string;
    role_label: string | null;
    max_per_tx_usdc: string;
    daily_cap_usdc: string | null;
  }>;
};

type AgentUpsertInput = {
  /** User-provided stable string identifier. */
  id: string;
};

const agent = await tally.agents.upsert({ id: "research-bot" });

const agents = await tally.agents.list();

const agent = await tally.agents.get("research-bot");

await tally.agents.delete("retired-bot");

const REQUIRED_AGENTS = ["research-bot", "summarizer", "publisher"] as const;

for (const id of REQUIRED_AGENTS) {
  await tally.agents.upsert({ id });
}

const agent = await tally.agents.get("research-bot");

if (agent.status === "no_permissions") {
  // Surface to the end user: they need to grant permission via the dashboard.
  return;
}

// agent.status === "active" → safe to call tally.payments.create