Custom Action Providers

You can extend the agent wallet with custom actions by implementing the ActionProvider abstract class.

Creating a Custom Provider

import { ActionProvider, type Action } from '@akta/agent-wallet'
import { z } from 'zod'

class MyCustomProvider extends ActionProvider {
  readonly name = 'my-custom-provider'

  getActions(): Action[] {
    return [
      {
        name: 'my_action',
        description: 'Does something custom',
        inputSchema: z.object({
          param: z.string().describe('A required parameter'),
          amount: z.number().optional().describe('An optional amount'),
        }),
        execute: async (args) => {
          const { param, amount } = args as { param: string; amount?: number }

          // Access the AgentKit via this.agentKit
          const { walletSdk, algorand, escrowName } = this.agentKit

          // Use the wallet SDK to perform operations
          // ...

          return JSON.stringify({
            summary: `Did something with ${param}`,
            txIds: [],
          })
        },
      },
    ]
  }
}

Registering the Provider

Pass custom providers to AgentKit.from():

const agentKit = await AgentKit.from({
  walletAppId: BigInt(process.env.WALLET_APP_ID!),
  escrowName: process.env.ESCROW_NAME!,
  walletProvider,
  algorand,
  actionProviders: [
    new WalletInfoActionProvider(),
    new PayActionProvider(),
    new MyCustomProvider(),  // Your custom provider
  ],
})

Provider Context

Inside execute(), you have access to this.agentKit which provides:

Property	Type	Description
walletSdk	WalletSDK	The ARC-58 wallet SDK instance
algorand	AlgorandClient	Algorand client for direct operations
escrowName	string	The agent’s escrow name
walletProvider	WalletProvider	The signing provider (Intermezzo or Local)

Action Schema

Each action defines:

Field	Type	Description
name	string	Unique action identifier
description	string	Human-readable description (shown to the AI)
inputSchema	ZodSchema	Zod schema defining input parameters
execute	function	Async function that performs the action

The inputSchema is automatically converted to JSON Schema for MCP tools and displayed to the AI agent.

Return Format

Actions should return a JSON string with:

{
  summary: string   // Human-readable result description
  txIds: string[]   // Transaction IDs (if any)
}

Wallet Providers

Two wallet providers are available:

IntermezzoWalletProvider (Production)

Signs transactions via HashiCorp Vault. The agent’s private key never leaves Vault.

import { IntermezzoWalletProvider } from '@akta/agent-wallet'

const provider = new IntermezzoWalletProvider({
  apiUrl: 'http://localhost:3100',
  vaultUrl: 'http://localhost:8200',
  roleId: '...',
  secretId: '...',
  keyName: '...',
})

LocalWalletProvider (Development)

Signs with a local mnemonic. Only for development and testing.

import { LocalWalletProvider } from '@akta/agent-wallet'

const provider = new LocalWalletProvider({
  mnemonic: 'your mnemonic ...',
})