npm package: @strawberryprotocol/str-agentkit-core
Description: Strawberry.fun Agentkit core primitives
Author: Strawberry Dot Fun Team
Latest version: 0.0.1

# Strawberry.fun Agent Kit Core

The Agent Kit Core provides a foundation for building AI agents that can interact with Strawberry.fun Tool Servers and execute various actions. 

This library provides framework-agnostic primitives that are meant to be composable and used via the Agent Kit's framework-specific extensions (e.g. LangChain).

### Installation

```bash
npm install @strawberryprotocol/str-agentkit-core
```

### Basic Usage

```typescript
import { StrawberryAgentkit } from '@strawberryprotocol/str-agentkit-core';

// Configure the agent kit
const agentkit = await StrawberryAgentkit.configure({
  sourceVersion: '1.0.0',
  chain: baseSepolia,
  // Optional: Specify tools to use
  tools: ['contract_address/tool_name'],
  // Optional: Configure MCP servers
  mcpServers: [{ uri: 'http://localhost:3000/sse' }]
});

// Get available actions
const actions = agentkit.getActions();

// Execute an action
const result = await agentkit.run(action, args);

// Clean up
await agentkit.close();
```

### Tool Discovery

The Agent Kit uses an on-chain discovery mechanism to find and load tools. Each Strawberry token contract contains an `apiURI` that points to its MCP server. When you configure the Agent Kit with tool specifications, it:

1. Reads the contract addresses from your tool specifications
2. Queries each contract's `apiURI` to discover its MCP server
3. Connects to each server and loads available tools

### Client Types

The Agent Kit supports two types of clients for interacting with the blockchain:

1. **Public Client**: Used for reading data from the blockchain (e.g., discovering tool servers). A default public client is created if none is provided, using the Base Sepolia RPC URL.

2. **Wallet Client**: Required for operations that need signing (e.g., using gated tools that require signatures). No default wallet client is provided - you must configure one if you want to use tools that require signatures.

Example configuration with both client types:
```typescript
import { StrawberryAgentkit } from '@strawberryprotocol/str-agentkit-core';
import { createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { baseSepolia } from 'viem/chains';

// Create public client for reading from chain
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http("https://your-rpc-url"),
});

// Create wallet client for signing
const account = privateKeyToAccount("your-private-key");
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});

// Configure agentkit with both clients
const agentkit = await StrawberryAgentkit.configure({
  chain: baseSepolia,
  publicClient,  // Optional - defaults to Base Sepolia RPC
  walletClient,  // Required for tools that need signing
  tools: ["0x1234.../gated-tool"],
});
```

#### Tool Specification Format

Tools can be specified in two formats:

```typescript
// 1. Full contract address with specific tool
"0x1234.../echo"  // Only load the "echo" tool from this contract

// 2. Full contract address with wildcard
"0x1234.../*"     // Load all tools from this contract
```

#### Examples

```typescript
import { StrawberryAgentkit } from '@strawberryprotocol/str-agentkit-core';
import { baseSepolia } from 'viem/chains';
import { createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

// Example 1: Basic configuration with default public client
const agentkit1 = await StrawberryAgentkit.configure({
  chain: baseSepolia,
  tools: [
    "0x439cd160C7bb70D1D69F9F71Ef550e287234614B/*"  // Load all tools
  ]
});

// Example 2: Configuration with custom public client
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http("https://your-rpc-url"),
});

const agentkit2 = await StrawberryAgentkit.configure({
  chain: baseSepolia,
  publicClient,
  tools: [
    "0x439cd160C7bb70D1D69F9F71Ef550e287234614B/echo",  // Only load echo tool
    "0x905Ad472d7eeB94ed1Fc29D8ff4B53FD4D5a5Eb4/weatherByLatLng"  // Only allow weather by latlng tool
  ]
});

// Example 3: Configuration with wallet for signing
const account = privateKeyToAccount("0x...");
const walletClient = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http(),
});

const agentkit3 = await StrawberryAgentkit.configure({
  chain: baseSepolia,
  walletClient,
  tools: [
    "0x439cd160C7bb70D1D69F9F71Ef550e287234614B/gated-echo",  // Load gated echo tool that requires signing
  ]
});
```

#### How It Works

1. **Contract Discovery**: When you initialize the Agent Kit, it looks at each contract address in your tool specifications.

2. **API URI Resolution**: For each contract, it calls the `apiURI()` function to get the MCP server URL:
   ```solidity
   // On the contract
   function apiURI() public view returns (string memory)
   ```

3. **Server Connection**: The Agent Kit connects to each discovered MCP server using the Model Context Protocol.

4. **Tool Loading**: It then loads the available tools from each server, filtering them based on your tool specifications:
   - If you specified a specific tool (e.g., "contract/echo"), only that tool is loaded
   - If you used a wildcard (e.g., "contract/*"), all tools from that contract are loaded

5. **Tool Availability**: The loaded tools become available through the `getActions()` method and can be executed using `run()`.

This discovery mechanism allows for dynamic tool loading based on on-chain registries, making tools automatically discoverable as long as they're properly registered in a Strawberry token contract.

### Argument Signing

The Agent Kit supports EIP-712 typed data signing for tool arguments. This allows tools to verify the authenticity and integrity of arguments passed to them.

#### EIP-712 Domain

Each tool uses the following EIP-712 domain for signing:

```typescript
const domain = {
  name: "Strawberry.fun",
  version: "1",
  chainId: 84532, // Base Sepolia
  verifyingContract: "0x..." // Optional: Contract address of the tool
};
```

#### Argument Type Conversion

Tool arguments are automatically converted from JSON Schema types to EIP-712 types:

| JSON Schema Type | EIP-712 Type |
|-----------------|--------------|
| string          | string       |
| number/integer  | uint256      |
| boolean         | bool         |

Example:
```typescript
// Tool argument schema
const schema = {
  type: "object",
  properties: {
    message: { type: "string" },
    amount: { type: "number" },
    isActive: { type: "boolean" }
  }
};

// Generated EIP-712 types
const types = {
  ToolArgs: [
    { name: "message", type: "string" },
    { name: "amount", type: "uint256" },
    { name: "isActive", type: "bool" }
  ]
};
```

#### Signing Arguments

You can sign tool arguments using the provided utilities:

```typescript
import { StrawberryAgentkit } from '@strawberryprotocol/str-agentkit-core';
import { createWalletClient } from 'viem';

// Create a wallet client
const wallet = createWalletClient({
  account,
  chain: baseSepolia,
  transport: http()
});

// Configure the agent kit
const agentkit = await StrawberryAgentkit.configure({
  chain: baseSepolia,
  tools: ["0x.../tool"]
});

// Get an action
const action = agentkit.getActions()[0];

// Sign and execute with arguments
const args = {
  message: "Hello World",
  amount: 123,
  isActive: true
};

const result = await agentkit.run(action, args, {
  signer: wallet // Optional: If provided, arguments will be signed
});
```

#### Verifying Signatures

Tools can verify the signatures of received arguments:

```typescript
import { verifyToolArgumentSignature } from '@strawberryprotocol/str-agentkit-core';

// In your tool implementation
const isValid = await verifyToolArgumentSignature(
  domain,
  schema,
  args,
  signature,
  signerAddress
);
```

This signing mechanism ensures:
1. Argument integrity (arguments haven't been tampered with)
2. Authenticity (arguments were signed by a known address)
3. Type safety (arguments match the expected schema)

### Key Components

#### `StrawberryAgentkit` Class

The main class that manages connections to MCP servers and handles action execution. It provides:

- MCP server discovery and connection management
- Action registration and execution
- Tool management and filtering
- Argument signing and verification

### Development

```bash
npm install
npx jest 
```

## License

MIT License