@coinbase/agentkit 0.1.0

package/README.md

@@ -0,0 +1,305 @@
+# Agentkit
+
+AgentKit is a framework for easily enabling AI agents to take actions onchain. It is designed to be framework-agnostic, so you can use it with any AI framework, and wallet-agnostic, so you can use it with any wallet.
+
+## Table of Contents
+
+- [Agentkit](#agentkit)
+- [Getting Started](#getting-started)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Create an AgentKit instance](#1-create-an-agentkit-instance)
+  - [Create an AgentKit instance with a specified wallet provider](#2-create-an-agentkit-instance-with-a-specified-wallet-provider)
+  - [Create an AgentKit instance with a specified action providers](#3-create-an-agentkit-instance-with-a-specified-action-providers)
+- [Wallet Providers](#wallet-providers)
+  - [CdpWalletProvider](#cdpwalletprovider)
+    - [Network Configuration](#network-configuration)
+    - [Configuring from an existing CDP API Wallet](#configuring-from-an-existing-cdp-api-wallet)
+    - [Configuring from a mnemonic phrase](#configuring-from-a-mnemonic-phrase)
+    - [Exporting a wallet](#exporting-a-wallet)
+    - [Importing a wallet from WalletData JSON string](#importing-a-wallet-from-walletdata-json-string)
+  - [ViemWalletProvider](#viemwalletprovider)
+- [Contributing](#contributing)
+
+## Getting Started
+
+*Prerequisites*:
+- [Node.js 18+](https://nodejs.org/en/download/)
+- [CDP Secret API Key](https://docs.cdp.coinbase.com/get-started/docs/cdp-api-keys#creating-secret-api-keys)
+
+## Installation
+
+```bash
+npm install @coinbase/agentkit
+```
+
+## Usage
+
+1. Create an AgentKit instance. If no wallet or action providers are specified, the agent will use the `CdpWalletProvider` and `WalletProvider` action provider.
+
+```typescript
+const agentKit = await AgentKit.from({
+  cdpApiKeyName: "CDP API KEY NAME",
+  cdpApiKeyPrivate: "CDP API KEY PRIVATE KEY",
+});
+```
+
+2. Create an AgentKit instance with a specified wallet provider.
+
+```typescript
+import { CdpWalletProvider } from "@coinbase/agentkit";
+
+const walletProvider = await CdpWalletProvider.configureWithWallet({
+    apiKeyName: "CDP API KEY NAME",
+    apiKeyPrivate: "CDP API KEY PRIVATE KEY",
+    networkId: "base-mainnet",
+});
+
+const agentKit = await AgentKit.from({
+    walletProvider,
+});
+```
+
+3. Create an AgentKit instance with a specified action providers.
+
+```typescript
+import { cdpApiActionProvider, pythActionProvider } from "@coinbase/agentkit";
+
+const agentKit = await AgentKit.from({
+    walletProvider,
+    actionProviders: [
+        cdpApiActionProvider({
+            apiKeyName: "CDP API KEY NAME",
+            apiKeyPrivate: "CDP API KEY PRIVATE KEY",
+        }),
+        pythActionProvider(),
+    ],
+});
+```
+
+4. Use the agent's actions with a framework extension. For example, using LangChain + OpenAI.
+
+*Prerequisites*:
+- [OpenAI API Key](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key)
+- Set `OPENAI_API_KEY` environment variable.
+
+```bash
+npm install @langchain @langchain/langgraph @langchain/openai
+```
+
+```typescript
+import { getLangChainTools } from "@coinbase/agentkit-langchain";
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+import { ChatOpenAI } from "@langchain/openai";
+
+const tools = await getLangChainTools(agentKit);
+
+const llm = new ChatOpenAI({
+    model: "gpt-4o-mini",
+});
+
+const agent = createReactAgent({
+    llm,
+    tools,
+});
+```
+
+## Creating an Action Provider
+
+Action providers are used to define the actions that an agent can take. They are defined as a class that extends the `ActionProvider` abstract class.
+
+```typescript
+import { ActionProvider, WalletProvider, Network } from "@coinbase/agentkit";
+
+// Define an action provider that uses a wallet provider.
+class MyActionProvider extends ActionProvider<WalletProvider> {
+    constructor() {
+        super("my-action-provider", []);
+    }
+
+    // Define if the action provider supports the given network
+    supportsNetwork = (network: Network) => true;
+}
+```
+
+### Adding Actions to your Action Provider
+
+Actions are defined as instance methods on the action provider class with the `@CreateAction` decorator. Actions can use a wallet provider or not and always return a Promise that resolves to a string.
+
+1. Define the action schema. Action schemas are defined using the `zod` library.
+
+```typescript
+import { z } from "zod";
+
+export const MyActionSchema = z.object({
+  myField: z.string(),
+});
+```
+
+2. Define the action.
+
+```typescript
+import { ActionProvider, WalletProvider, Network, CreateAction } from "@coinbase/agentkit";
+
+class MyActionProvider extends ActionProvider<WalletProvider> {
+    constructor() {
+        super("my-action-provider", []);
+    }
+
+    @CreateAction({
+        name: "my-action",
+        description: "My action description",
+        schema: MyActionSchema,
+    })
+    async myAction(args: z.infer<typeof MyActionSchema>): Promise<string> {
+        return args.myField;
+    }
+
+    supportsNetwork = (network: Network) => true;
+}
+
+export const myActionProvider = () => new MyActionProvider();
+```
+
+#### Adding Actions to your Action Provider that use a Wallet Provider
+
+Actions that use a wallet provider can be defined as instance methods on the action provider class with the `@CreateAction` decorator that have a `WalletProvider` as the first parameter.
+
+```typescript
+class MyActionProvider extends ActionProvider<WalletProvider> {
+    constructor() {
+        super("my-action-provider", []);
+    }
+
+    @CreateAction({
+        name: "my-action",
+        description: "My action description",
+        schema: MyActionSchema,
+    })
+    async myAction(walletProvider: WalletProvider, args: z.infer<typeof MyActionSchema>): Promise<string> {
+        return walletProvider.signMessage(args.myField);
+    }
+
+    supportsNetwork = (network: Network) => true;
+}
+```
+
+### Adding an Action Provider to your AgentKit instance. 
+
+This gives your agent access to the actions defined in the action provider.
+
+```typescript
+const agentKit = new AgentKit({
+  cdpApiKeyName: "CDP API KEY NAME",
+  cdpApiKeyPrivate: "CDP API KEY PRIVATE KEY",
+  actionProviders: [myActionProvider()],
+});
+```
+
+## Wallet Providers
+
+Wallet providers give an agent access to a wallet. AgentKit currently supports the following wallet providers:
+
+EVM:
+- [CdpWalletProvider](./src/wallet-providers/cdpWalletProvider.ts)
+- [ViemWalletProvider](./src/wallet-providers/viemWalletProvider.ts)
+
+### CdpWalletProvider
+
+The `CdpWalletProvider` is a wallet provider that uses the Coinbase Developer Platform (CDP) [API Wallet](https://docs.cdp.coinbase.com/wallet-api/docs/welcome).
+
+#### Network Configuration
+
+The `CdpWalletProvider` can be configured to use a specific network by passing the `networkId` parameter to the `configureWithWallet` method. The `networkId` is the ID of the network you want to use. You can find a list of [supported networks on the CDP API docs](https://docs.cdp.coinbase.com/cdp-apis/docs/networks).
+
+```typescript
+import { CdpWalletProvider } from "@coinbase/agentkit";
+
+const walletProvider = await CdpWalletProvider.configureWithWallet({
+    apiKeyName: "CDP API KEY NAME",
+    apiKeyPrivate: "CDP API KEY PRIVATE KEY",
+    networkId: "base-mainnet",
+});
+```
+
+#### Configuring from an existing CDP API Wallet
+
+If you already have a CDP API Wallet, you can configure the `CdpWalletProvider` by passing the `wallet` parameter to the `configureWithWallet` method.
+
+```typescript
+import { CdpWalletProvider } from "@coinbase/agentkit";
+import { Wallet } from "@coinbase/coinbase-sdk";
+const walletProvider = await CdpWalletProvider.configureWithWallet({
+    wallet,
+    apiKeyName: "CDP API KEY NAME",
+    apiKeyPrivate: "CDP API KEY PRIVATE KEY",
+});
+```
+
+#### Configuring from a mnemonic phrase
+
+The `CdpWalletProvider` can be configured from a mnemonic phrase by passing the `mnemonicPhrase` parameter to the `configureWithWallet` method.
+
+```typescript
+import { CdpWalletProvider } from "@coinbase/agentkit";
+
+const walletProvider = await CdpWalletProvider.configureWithWallet({
+    mnemonicPhrase: "MNEMONIC PHRASE",
+});
+```
+
+#### Exporting a wallet
+
+The `CdpWalletProvider` can export a wallet by calling the `exportWallet` method.
+
+```typescript
+import { CdpWalletProvider } from "@coinbase/agentkit";
+
+const walletProvider = await CdpWalletProvider.configureWithWallet({
+    mnemonicPhrase: "MNEMONIC PHRASE",
+});
+
+const walletData = await walletProvider.exportWallet();
+```
+
+#### Importing a wallet from `WalletData` JSON string
+
+The `CdpWalletProvider` can import a wallet from a `WalletData` JSON string by passing the `cdpWalletData` parameter to the `configureWithWallet` method.
+
+```typescript
+import { CdpWalletProvider } from "@coinbase/agentkit";
+
+const walletProvider = await CdpWalletProvider.configureWithWallet({
+    cdpWalletData: "WALLET DATA JSON STRING",
+    apiKeyName: "CDP API KEY NAME",
+    apiKeyPrivate: "CDP API KEY PRIVATE KEY",
+});
+```
+
+### ViemWalletProvider
+
+The `ViemWalletProvider` is a wallet provider that uses the [Viem library](https://viem.sh/docs/getting-started). It is useful for interacting with any EVM-compatible chain.
+
+```typescript
+import { ViemWalletProvider } from "@coinbase/agentkit";
+import { privateKeyToAccount } from "viem/accounts";
+import { baseSepolia } from "viem/chains";
+import { http } from "viem/transports";
+import { createWalletClient } from "viem";
+
+const account = privateKeyToAccount(
+  "0x4c0883a69102937d6231471b5dbb6208ffd70c02a813d7f2da1c54f2e3be9f38",
+);
+
+const client = createWalletClient({
+  account,
+  chain: baseSepolia,
+  transport: http(),
+});
+
+const walletProvider = new ViemWalletProvider(client);
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for more information.

package/dist/action-providers/actionDecorator.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import "reflect-metadata";
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+    /**
+     * The name of the action
+     */
+    name: string;
+    /**
+     * The description of the action
+     */
+    description: string;
+    /**
+     * The schema of the action
+     */
+    schema: z.ZodSchema;
+}
+/**
+ * Metadata key for the action decorator
+ */
+export declare const ACTION_DECORATOR_KEY: unique symbol;
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+    /**
+     * The name of the action
+     */
+    name: string;
+    /**
+     * The description of the action
+     */
+    description: string;
+    /**
+     * The schema of the action
+     */
+    schema: z.ZodSchema;
+    /**
+     * The function to invoke the action
+     */
+    invoke: (...args: any[]) => any;
+    /**
+     * The wallet provider to use for the action
+     */
+    walletProvider: boolean;
+}
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ *   @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ *   public myAction(args: z.infer<typeof myActionSchema>) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+export declare function CreateAction(params: CreateActionDecoratorParams): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => object;

package/dist/action-providers/actionDecorator.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTION_DECORATOR_KEY = void 0;
+exports.CreateAction = CreateAction;
+const wallet_providers_1 = require("../wallet-providers");
+const analytics_1 = require("../analytics");
+require("reflect-metadata");
+/**
+ * Metadata key for the action decorator
+ */
+exports.ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ *   @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ *   public myAction(args: z.infer<typeof myActionSchema>) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+function CreateAction(params) {
+    return (target, propertyKey, descriptor) => {
+        const prefixedActionName = `${target.constructor.name}_${params.name}`;
+        const originalMethod = descriptor.value;
+        const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        descriptor.value = function (...args) {
+            let walletMetrics = {};
+            if (isWalletProvider) {
+                walletMetrics = {
+                    wallet_provider: args[0].getName(),
+                    wallet_address: args[0].getAddress(),
+                    network_id: args[0].getNetwork().networkId,
+                    chain_id: args[0].getNetwork().chainId,
+                    protocol_family: args[0].getNetwork().protocolFamily,
+                };
+            }
+            (0, analytics_1.sendAnalyticsEvent)({
+                name: "agent_action_invocation",
+                action: "invoke_action",
+                component: "agent_action",
+                action_name: prefixedActionName,
+                class_name: target.constructor.name,
+                method_name: propertyKey,
+                ...walletMetrics,
+            });
+            return originalMethod.apply(this, args);
+        };
+        const existingMetadata = Reflect.getMetadata(exports.ACTION_DECORATOR_KEY, target.constructor) || new Map();
+        const metaData = {
+            name: prefixedActionName,
+            description: params.description,
+            schema: params.schema,
+            invoke: descriptor.value,
+            walletProvider: isWalletProvider,
+        };
+        existingMetadata.set(propertyKey, metaData);
+        Reflect.defineMetadata(exports.ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+        return target;
+    };
+}
+/**
+ * Validates the arguments of an action method
+ *
+ * @param target - The target object
+ * @param propertyKey - The property key
+ * @returns An object containing the wallet provider flag
+ */
+function validateActionMethodArguments(target, propertyKey) {
+    const className = target instanceof Object ? target.constructor.name : undefined;
+    const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+    if (params == null) {
+        throw new Error(`Failed to get parameters for action method ${propertyKey} on class ${className}`);
+    }
+    if (params.length > 2) {
+        throw new Error(`Action method ${propertyKey} on class ${className} has more than 2 parameters`);
+    }
+    const walletProviderParam = params.find(param => {
+        if (!param || !param.prototype) {
+            return false;
+        }
+        if (param === wallet_providers_1.WalletProvider)
+            return true;
+        return param.prototype instanceof wallet_providers_1.WalletProvider;
+    });
+    return {
+        isWalletProvider: !!walletProviderParam,
+    };
+}

package/dist/action-providers/actionProvider.d.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet-providers";
+import { Network } from "../network";
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+    name: string;
+    description: string;
+    schema: TActionSchema;
+    invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export declare abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+    /**
+     * The name of the action provider.
+     */
+    readonly name: string;
+    /**
+     * The action providers to combine.
+     */
+    readonly actionProviders: ActionProvider<TWalletProvider>[];
+    /**
+     * The constructor for the action provider.
+     *
+     * @param name - The name of the action provider.
+     * @param actionProviders - The action providers to combine.
+     */
+    constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]);
+    /**
+     * Gets the actions of the action provider bound to the given wallet provider.
+     *
+     * @param walletProvider - The wallet provider.
+     * @returns The actions of the action provider.
+     */
+    getActions(walletProvider: TWalletProvider): Action[];
+    /**
+     * Checks if the action provider supports the given network.
+     *
+     * @param network - The network to check.
+     * @returns True if the action provider supports the network, false otherwise.
+     */
+    abstract supportsNetwork(network: Network): boolean;
+}

package/dist/action-providers/actionProvider.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionProvider = void 0;
+const actionDecorator_1 = require("./actionDecorator");
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+class ActionProvider {
+    /**
+     * The constructor for the action provider.
+     *
+     * @param name - The name of the action provider.
+     * @param actionProviders - The action providers to combine.
+     */
+    constructor(name, 
+    // Update parameter type to match property type
+    actionProviders) {
+        this.name = name;
+        this.actionProviders = actionProviders;
+    }
+    /**
+     * Gets the actions of the action provider bound to the given wallet provider.
+     *
+     * @param walletProvider - The wallet provider.
+     * @returns The actions of the action provider.
+     */
+    getActions(walletProvider) {
+        const actions = [];
+        const actionProviders = [this, ...this.actionProviders];
+        for (const actionProvider of actionProviders) {
+            const actionsMetadataMap = Reflect.getMetadata(actionDecorator_1.ACTION_DECORATOR_KEY, actionProvider.constructor);
+            if (!actionsMetadataMap) {
+                if (!(actionProvider instanceof ActionProvider)) {
+                    console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+                }
+                else {
+                    console.warn(`Warning: ${actionProvider} has no actions.`);
+                }
+                continue;
+            }
+            for (const actionMetadata of actionsMetadataMap.values()) {
+                actions.push({
+                    name: actionMetadata.name,
+                    description: actionMetadata.description,
+                    schema: actionMetadata.schema,
+                    invoke: schemaArgs => {
+                        const args = [];
+                        if (actionMetadata.walletProvider) {
+                            args[0] = walletProvider;
+                        }
+                        args.push(schemaArgs);
+                        return actionMetadata.invoke.apply(actionProvider, args);
+                    },
+                });
+            }
+        }
+        return actions;
+    }
+}
+exports.ActionProvider = ActionProvider;

package/dist/action-providers/basename/basenameActionProvider.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { ActionProvider } from "../actionProvider";
+import { Network } from "../../network";
+import { RegisterBasenameSchema } from "./schemas";
+import { EvmWalletProvider } from "../../wallet-providers";
+/**
+ * Action provider for registering Basenames.
+ */
+export declare class BasenameActionProvider extends ActionProvider {
+    /**
+     * Constructs a new BasenameActionProvider.
+     */
+    constructor();
+    /**
+     * Registers a Basename.
+     *
+     * @param wallet - The wallet to use for the registration.
+     * @param args - The arguments for the registration.
+     * @returns A string indicating the success or failure of the registration.
+     */
+    register(wallet: EvmWalletProvider, args: z.infer<typeof RegisterBasenameSchema>): Promise<string>;
+    /**
+     * Checks if the Basename action provider supports the given network.
+     *
+     * @param network - The network to check.
+     * @returns True if the Basename action provider supports the network, false otherwise.
+     */
+    supportsNetwork: (network: Network) => boolean;
+}
+export declare const basenameActionProvider: () => BasenameActionProvider;