Skip to main content
The tally.agents resource manages agent identities — the things you run that spend money. See Agents (concept) for the model.

​
Types

​
Agent

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;
  }>;
};

​
AgentUpsertInput

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

​
Methods

​
agents.upsert(input)

Creates an agent if it doesn’t exist; returns the existing record if it does. Idempotent — safe to run on every deploy. 
const agent = await tally.agents.upsert({ id: "research-bot" });
Parameters
FieldTypeDescription
input.idstringStable identifier. Must be unique within the API key’s (account, mode).
Returns: Promise<Agent>. For a freshly registered agent, status will be "no_permissions" and both signer counts will be 0 until a user authorizes a grant. See Permissions for the grant flow. Throws
ErrorWhen
ValidationErrorThe id is missing, empty, or fails server-side format checks.
AuthenticationErrorThe API key is missing, revoked, or out of its rotation grace window.

​
agents.list()

Returns every agent in the API key’s (account, mode). 
const agents = await tally.agents.list();
Returns: Promise<Agent[]>. No pagination today — accounts with hundreds of agents will get the full list. Cursor-paginated variant is on the roadmap; until it lands, this is a single round-trip. Throws: AuthenticationError if the API key is invalid.

​
agents.get(id)

Fetches a single agent by id. 
const agent = await tally.agents.get("research-bot");
Parameters
FieldTypeDescription
idstringThe agent’s stable identifier. URL-encoded automatically.
Returns: Promise<Agent>. Throws
ErrorWhen
NotFoundErrorNo agent with that id exists in this (account, mode).
AuthenticationErrorThe API key is invalid.

​
agents.delete(id)

Soft-deletes an agent. The DB row stays in place so historical transactions keep their attribution; future list() / get() responses hide it. 
await tally.agents.delete("retired-bot");
The 409 has_active_grants enforcement makes consent ordering explicit: an agent with active spending power isn’t quietly removed from view while still attached to a Privy wallet. Revoke its permissions first, then retry. Resurrection is supported: re-running tally.agents.upsert({ id }) with the same id clears deletedAt and brings the agent back with no transaction history loss. Throws
ErrorWhen
NotFoundErrorNo agent with that id exists (or already soft-deleted).
ConflictErrorerr.code === "has_active_grants" — agent still has non-revoked permissions. Revoke them first.
AuthenticationErrorThe API key is invalid.

​
Patterns

​
Idempotent registration on deploy

Because upsert is idempotent, the cleanest pattern is to register every agent your service needs at startup: 
const REQUIRED_AGENTS = ["research-bot", "summarizer", "publisher"] as const;

for (const id of REQUIRED_AGENTS) {
  await tally.agents.upsert({ id });
}
If you change REQUIRED_AGENTS in a later deploy, the new entries get registered automatically and existing ones are unchanged.

​
Checking grant status before sending a payment

Agent.status reflects whether any wallet has authorized this agent to spend. Use it as a gate before invoking spend-related flows: 
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
Note status: "active" only confirms the agent has some grant; it doesn’t tell you which wallets or what allowance remains. For that, today you have to either attempt the payment and branch on the error, or check the dashboard.

​
Not yet in the SDK

  • agents.delete(id) — soft-delete an agent. Tracked in BUILD_LOG.md.
  • agents.list({ limit, starting_after }) — cursor pagination.
  • tally.permissions.list({ agent_id }) — per-grant inspection (allowance, policy summary, wallet). Currently dashboard-only.
When those land, the docs sweep notes in mintlify-docs/permissions.mdx get removed.