Engineering Onchain AI Agents

import OpenAI from "openai";
import { Assistant } from "openai/resources/beta/assistants";
import { tools } from "../tools/allTools.js";
import { assistantPrompt } from "../const/prompt.js";
 
/**
* Creates a new OpenAI assistant configured for blockchain interactions
* @param client The OpenAI client instance to use
* @returns Promise<Assistant> The created assistant instance
* @custom
* - Uses GPT-4 mini model
* - Named "OnchainAIAgent" 
* - Configured with custom instructions from assistantPrompt
* - Tools mapped from tools directory
*/
export async function createAssistant(client: OpenAI): Promise<Assistant> {
  return await client.beta.assistants.create({
    model: "gpt-4o-mini",
    name: "OnchainAIAgent",
    instructions: assistantPrompt,
    tools: Object.values(tools).map((tool) => tool.definition),
  });
}

import OpenAI from "openai";
import { Thread } from "openai/resources/beta/threads/threads";
 
/**
* Creates a new OpenAI conversation thread and optionally adds an initial message
* @param client The OpenAI client instance to use
* @param message Optional initial message to add to the thread
* @returns Promise<Thread> The created thread instance
* @dev If a message is provided, it's added as a user message to the thread
*/
export async function createThread(client: OpenAI, message?: string): Promise<Thread> {
   const thread = await client.beta.threads.create();
 
   if (message) {
       await client.beta.threads.messages.create(thread.id, {
           role: "user",
           content: message,
       });
   }
 
   return thread;
}

import OpenAI from "openai";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";
 
/**
 * Creates and monitors a run for a given thread using the specified assistant.
 * The function polls the run status until completion.
 * @param client - The OpenAI client instance used to make API calls
 * @param thread - The thread object where the run will be created
 * @param assistantId - The ID of the assistant to use for this run
 * @returns A Promise that resolves to the completed Run object
 * @dev Polls every 1 second until the run is no longer in progress or queued
 */
export async function createRun(client: OpenAI, thread: Thread, assistantId: string): Promise<Run> {
    console.log(`Creating run with assistant ${assistantId} for thread ${thread.id}`);
    
    let run = await client.beta.threads.runs.create(thread.id, {
        assistant_id: assistantId
    });
 
    while(run.status === 'in_progress' || run.status === 'queued'){
        await new Promise(resolve => setTimeout(resolve, 1000));
        run = await client.beta.threads.runs.retrieve(thread.id, run.id);
    }
 
    return run;
}

import OpenAI from "openai";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";
import { tools } from "../tools/allTools.js";
 
/**
 * Processes and executes tool calls required by an assistant run.
 * @param run - The current Run instance containing tool calls to be executed
 * @param client - OpenAI client instance for API interactions
 * @param thread - The Thread instance associated with this run
 * @returns Promise resolving to an updated Run instance after tool execution
 * @dev Executes multiple tool calls in parallel using Promise.all
 * @notice If a tool is not found or execution fails, appropriate error handling is performed
 * @notice Tool outputs are automatically converted to strings before submission
 * @notice Empty or failed tool outputs are filtered out before submission
*/
 
export async function handleRunToolCalls(
  run: Run,
  client: OpenAI,
  thread: Thread
): Promise<Run> {
  const toolCalls = run.required_action?.submit_tool_outputs?.tool_calls;
  if (!toolCalls) return run;
 
  const toolOutputs = await Promise.all(
    toolCalls.map(async (tool) => {
      const toolConfig = tools[tool.function.name];
 
      if (!toolConfig) {
        console.error(`Tool ${tool.function.name} Not Found!`);
        return null;
      }
 
      try {
        const args = JSON.parse(tool.function.arguments);
        const output = await toolConfig.handler(args);
        
        console.log(`Tool ${tool.function.name} returned ${output}`);
 
        return {
          tool_call_id: tool.id,
          output: String(output),
        };
      } catch (error) {
        const errorMessage =
          error instanceof Error ? error.message : String(error);
        return {
          tool_call_id: tool.id,
          output: `Error: ${errorMessage}`,
        };
      }
    })
  );
 
  const validOutputs = toolOutputs.filter(
    Boolean
  ) as OpenAI.Beta.Threads.Runs.RunSubmitToolOutputsParams.ToolOutput[];
  if (validOutputs.length === 0) return run;
 
  return client.beta.threads.runs.submitToolOutputsAndPoll(thread.id, run.id, {
    tool_outputs: validOutputs,
  });
}

import OpenAI from "openai";
import { Thread } from "openai/resources/beta/threads/threads";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { handleRunToolCalls } from "./handleRunToolCall.js";
 
/**
 * Handles a run's execution lifecycle, including tool calls and error handling.
 * @param run - The current Run instance to be processed
 * @param client - OpenAI client instance for API interactions
 * @param thread - The Thread instance associated with this run
 * @returns Promise resolving to the assistant's message content or an error message object
 * @dev Continues processing tool calls until completion or failure
 * @notice If the run fails, creates an error message in the thread and returns it
*/
export async function performRun(run: Run, client: OpenAI, thread: Thread) {
    while (run.status === "requires_action") {
        run = await handleRunToolCalls(run, client, thread);
    }
 
    if (run.status === "failed") {
        const errorMessage = `I encountered an error: ${run.last_error?.message || `Unknown Error`}`;
        console.error("Run Failed:", run.last_error);
        await client.beta.threads.messages.create(thread.id, {
            role: 'assistant',
            content: errorMessage
        });
        return {
            type: 'text',
            text: {
                value: errorMessage,
                annotations: []
            }
        }
    }
 
    const messages = await client.beta.threads.messages.list(thread.id);
    const assistantMessage = messages.data.find(message => message.role === "assistant");
 
    return assistantMessage?.content[0] || {
        type: "text",
        text: {
            value: "No Response from Assistant",
            annotations: []
        }
    };
}

import { deployErc20Tool } from "./deployERC20Tool.js";
import { getBalanceTool } from "./getBalance.js";
 
export interface ToolConfig<T = any> {
    definition: {
        type: 'function';
        function: {
            name: string;
            description: string;
            parameters: {
                type: 'object';
                properties: Record<string, unknown>;
                required: string[];
            };
        };
    };
    handler: (args: T) => Promise<any>;
};
 
export const tools: Record<string, ToolConfig> = {
    // Add Tools Here
 
    // READ
    get_balance: getBalanceTool,
}

import { Address } from 'viem';
import { createViemPublicClient } from '../viem/createViemPublicClient.js';
import { ToolConfig } from './allTools.js';
import { formatEther } from 'viem';
 
interface GetBalanceArgs {
    wallet: Address;
}
 
export const getBalanceTool: ToolConfig<GetBalanceArgs> = {
    definition: {
        type: 'function',
        function: {
            name: 'get_balance',
            description: 'Get the balance of a wallet',
            parameters: {
                type: 'object',
                properties: {
                    wallet: {
                        type: 'string',
                        pattern: '^0x[a-fA-F0-9]{40}$',
                        description: 'The wallet address to get the balance of',
                    }
                },
                required: ['wallet']
            }
        }
    },
    handler: async ({ wallet }) => {
        return await getBalance(wallet);
    }
};
 
async function getBalance(wallet: Address) {
    const publicClient = createViemPublicClient();
    const balance = await publicClient.getBalance({ address: wallet });
    return formatEther(balance);
}

import 'dotenv/config';
import OpenAI from "openai";
import readline from 'readline';
import { createAssistant } from './openai/createAssistant.js';
import { createThread } from './openai/createThread.js';
import { createRun } from './openai/createRun.js';
import { performRun } from './openai/performRun.js';
import { Thread } from 'openai/resources/beta/threads/threads';
import { Assistant } from 'openai/resources/beta/assistants';
 
const client = new OpenAI();
 
const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout
});
 
const question = (query: string): Promise<string> => {
    return new Promise((resolve) => rl.question(query, resolve));
};
 
async function chat(thread: Thread, assistant: Assistant): Promise<void> {
    while (true) {
        const userInput = await question('\nYou: ');
 
        if (userInput.toLowerCase() === 'exit') {
            rl.close();
            break;
        }
 
        try {
            await client.beta.threads.messages.create(thread.id, {
                role: "user",
                content: userInput
            });
 
            const run = await createRun(client, thread, assistant.id);
            const result = await performRun(run, client, thread);
 
            if (result?.type === 'text') {
                console.log('\nAlt:', result.text.value);
            }
        } catch (error) {
            console.error('Error during chat:', error instanceof Error ? error.message : 'Unknown error');
            rl.close();
            break;
        }
    }
}
 
async function main(): Promise<void> {
    try {
        const assistant = await createAssistant(client);
        const thread = await createThread(client);
 
        console.log('Chat started! Type "exit" to end the conversation.');
        await chat(thread, assistant);
    } catch (error) {
        console.error('Error in main:', error instanceof Error ? error.message : 'Unknown error');
        rl.close();
        process.exit(1);
    }
}
 
main().catch((error) => {
    console.error('Unhandled error:', error instanceof Error ? error.message : 'Unknown error');
    process.exit(1);
});