Tutorials

• 1: Getting Started with gomcptest
• 2: Building Your First OpenAI-Compatible Server
• 3: Using the cliGCP Command Line Interface

1 - Getting Started with gomcptest

This tutorial will take you through building and running your first AI agent system with gomcptest. By the end, you’ll have a working agent that can help you manage files and execute commands on your system.

Prerequisites

• Go >= 1.21 installed on your system
• Google Cloud account with access to Vertex AI API
• Google Cloud CLI installed
• Basic familiarity with terminal/command line

Setting up Google Cloud Authentication

Before using gomcptest with Google Cloud Platform services like Vertex AI, you need to set up your authentication.

1. Initialize the Google Cloud CLI

If you haven’t already configured the Google Cloud CLI, run:

gcloud init

This interactive command will guide you through:

• Logging into your Google account
• Selecting a Google Cloud project
• Setting default configurations

2. Log in to Google Cloud

Authenticate your gcloud CLI with your Google account:

gcloud auth login

This will open a browser window where you can sign in to your Google account.

3. Set up Application Default Credentials (ADC)

Application Default Credentials are used by client libraries to automatically find credentials when connecting to Google Cloud services:

gcloud auth application-default login

This command will:

1. Open a browser window for authentication
2. Store your credentials locally (typically in ~/.config/gcloud/application_default_credentials.json)
3. Configure your environment to use these credentials when accessing Google Cloud APIs

These credentials will be used by gomcptest when interacting with Google Cloud services.

Project Setup

1. Clone the repository:

   git clone https://github.com/owulveryck/gomcptest.git
   cd gomcptest
   

2. Build All Components: Compile tools and servers using the root Makefile

   # Build all tools and servers
   make all
   
   # Or build only tools
   make tools
   
   # Or build only servers
   make servers
   

3. Set up your environment: Configure Google Cloud Project

   # Set your project ID (replace with your actual project ID)
   export GCP_PROJECT="your-project-id"
   export GCP_REGION="us-central1"
   export GEMINI_MODELS="gemini-2.0-flash"
   export PORT=8080
   

Step 4: Start Your First AI Agent

Now let’s start the OpenAI-compatible server with the AgentFlow web interface:

cd host/openaiserver
go run . -withAllEvents -mcpservers "../../bin/LS;../../bin/View;../../bin/Bash;../../bin/GlobTool"

⚠️ Note: We’re using the -withAllEvents flag to enable full tool event streaming, which is essential for seeing the real-time tool execution notifications in the AgentFlow UI.

You should see output like:

2024/01/15 10:30:00 Starting OpenAI-compatible server on port 8080
2024/01/15 10:30:00 Registered MCP tool: LS
2024/01/15 10:30:00 Registered MCP tool: View  
2024/01/15 10:30:00 Registered MCP tool: Bash
2024/01/15 10:30:00 Registered MCP tool: GlobTool
2024/01/15 10:30:00 AgentFlow UI available at: http://localhost:8080/ui

Step 5: Have Your First Agent Conversation

1. Open the AgentFlow UI: Navigate to http://localhost:8080/ui in your browser

2. Test basic interaction: Type this message in the chat:

   Hello! Can you help me understand what files are in the current directory?
   

3. Watch the magic happen: You’ll see:

   • The AI agent decides to use the LS tool
   • A blue notification appears showing “Calling tool: LS”
   • The tool executes and shows your directory contents
   • The AI explains what it found

4. Try a more advanced task: Ask the agent:

   Find all .go files in this project and tell me about the project structure
   

   Watch as the agent:

   • Uses GlobTool to find .go files
   • Uses View to examine some files
   • Gives you an analysis of the project structure

Congratulations! 🎉

You’ve just built and run your first AI agent system! Your agent can now:

• ✅ Navigate your file system
• ✅ Read file contents
• ✅ Execute commands
• ✅ Find files matching patterns
• ✅ Provide intelligent analysis of what it discovers

What You’ve Learned

Through this hands-on experience, you’ve:

• Set up authentication with Google Cloud
• Built MCP-compatible tools from source
• Started an OpenAI-compatible server
• Used the AgentFlow web interface
• Watched an AI agent use tools to accomplish real tasks

Next Steps

Now that your agent is working, explore what else it can do:

• Try the OpenAI Server Tutorial to learn about advanced features
• Read about Creating Custom Tools to extend your agent’s capabilities
• Learn about the Event System to understand how the real-time notifications work

2 - Building Your First OpenAI-Compatible Server

This tutorial will guide you step-by-step through running and configuring the OpenAI-compatible server in gomcptest with the AgentFlow web interface. By the end, you’ll have a working server with a modern UI that provides tool selection, real-time event monitoring, and interactive chat capabilities.

Prerequisites

• Go >= 1.21 installed
• Access to Google Cloud Platform with Vertex AI API enabled
• GCP authentication set up via gcloud auth login
• Basic familiarity with terminal commands
• The gomcptest repository cloned and tools built (see the Getting Started guide)

Step 1: Set Up Environment Variables

The OpenAI server requires several environment variables. Create a .envrc file in the host/openaiserver directory:

cd host/openaiserver
touch .envrc

Add the following content to the .envrc file, adjusting the values according to your setup:

# Server configuration
PORT=8080
LOG_LEVEL=INFO

# GCP configuration
GCP_PROJECT=your-gcp-project-id
GCP_REGION=us-central1
GEMINI_MODELS=gemini-2.0-flash

Note: IMAGE_DIR and IMAGEN_MODELS environment variables are no longer needed for the openaiserver host. Image generation is now handled by the independent tools/imagen MCP server.

Load the environment variables:

source .envrc

Step 2: Start the OpenAI Server with AgentFlow UI

Now you can start the OpenAI-compatible server with the embedded AgentFlow interface:

cd host/openaiserver
go run . -withAllEvents -mcpservers "../bin/GlobTool;../bin/GrepTool;../bin/LS;../bin/View;../bin/Bash;../bin/Replace"

⚠️ Important: We’re using the -withAllEvents flag to enable streaming of all tool execution events. This is essential for the real-time tool monitoring features in AgentFlow.

You should see output indicating that the server has started and registered the MCP tools.

Step 3: Access the AgentFlow Web Interface

Open your web browser and navigate to:

http://localhost:8080/ui

You’ll see the AgentFlow interface with:

• Modern chat interface with mobile-optimized design
• Tool selection dropdown showing all available MCP tools (GlobTool, GrepTool, LS, View, Bash, Replace)
• Model selection with Vertex AI tools support
• Real-time event monitoring for tool calls and responses

Using Tool Selection

1. View Available Tools: Click the “Tools: All” button to see the tool dropdown
2. Select Specific Tools: Uncheck tools you don’t want to use for focused interactions
3. Tool Information: Each tool shows its name and description
4. Apply Selection: Your selection is automatically applied to new conversations

Monitoring Tool Events

As you interact with the AI agent, you’ll see real-time notifications when:

• Tool Calls: Blue notifications appear when the AI decides to use a tool
• Tool Responses: Results are displayed as they complete
• Event Details: Click notifications to see detailed tool arguments and responses

Step 4: Test AgentFlow with Interactive Chat

In the AgentFlow interface, try these interactive examples:

Basic Chat Test

1. Type in the chat input: “Hello, what can you do?”
2. Send the message and observe the response
3. Notice how the AI explains its capabilities and available tools

Tool Interaction Test

1. Ask: “List the files in the current directory”
2. Watch as AgentFlow shows:
   • Tool Call Notification: “Calling tool: LS” appears immediately
   • Tool Call Popup: Shows the LS tool being called with its arguments
   • Tool Response: Displays the directory listing result
   • AI Response: The model interprets and explains the results

Tool Selection Test

1. Click “Tools: All” to open the tool selector
2. Uncheck all tools except “View” and “LS”
3. Ask: “Show me the contents of README.md”
4. Notice how the AI can only use the selected tools (View for reading, LS for listing)

Event Monitoring

Throughout your interactions, observe:

• Real-time Events: Tool calls appear instantly as blue notifications
• Event History: All tool interactions are preserved in the chat
• Detailed Information: Click on tool notifications to see arguments and responses

Step 5: Alternative API Testing (Optional)

You can also test the server programmatically using curl:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "List the files in the current directory"
      }
    ]
  }'

However, the AgentFlow UI provides much richer feedback and interaction capabilities.

What You’ve Learned

In this tutorial, you’ve:

1. Set up the environment for the OpenAI-compatible server with AgentFlow UI
2. Built and registered MCP tools
3. Started the server with embedded web interface
4. Accessed the modern AgentFlow web interface
5. Used interactive tool selection and monitoring
6. Experienced real-time tool event notifications
7. Tested both UI and API interactions

Key AgentFlow Features Demonstrated

• Tool Selection: Granular control over which tools are available to the AI
• Real-time Events: Live monitoring of tool calls and responses
• Event Notifications: Visual feedback for tool interactions
• Mobile Optimization: Responsive design that works on all devices
• Interactive Chat: Modern conversation interface with rich formatting

Next Steps

Now that you have a working AgentFlow-enabled server, you can:

• Explore Advanced Features: Learn more about AgentFlow’s capabilities
• Configure Advanced Settings: Check out the OpenAI Server Configuration Guide
• Create Custom Tools: Follow the Custom Tool Creation Guide
• Experiment with Models: Try different Gemini models and Vertex AI tools
• Mobile Usage: Install AgentFlow as a Progressive Web App on your mobile device

For detailed information about tool selection, event monitoring, and other AgentFlow features, see the comprehensive AgentFlow Documentation.

3 - Using the cliGCP Command Line Interface

This tutorial guides you through setting up and using the cliGCP command line interface to interact with LLMs and MCP tools. By the end, you’ll be able to run the CLI and perform basic tasks with it.

Prerequisites

• Go >= 1.21 installed on your system
• Access to Google Cloud Platform with Vertex AI API enabled
• GCP authentication set up via gcloud auth login
• The gomcptest repository cloned and tools built (see the Getting Started guide)

Step 1: Understand the cliGCP Tool

The cliGCP tool is a command-line interface similar to tools like Claude Code. It connects directly to the Google Cloud Platform’s Vertex AI API to access Gemini models and can use local MCP tools to perform actions on your system.

Step 2: Build the cliGCP Tool

First, build the cliGCP tool if you haven’t already:

cd gomcptest
make all  # This builds all tools including cliGCP

If you only want to build cliGCP, you can run:

cd host/cliGCP/cmd
go build -o ../../../bin/cliGCP

Step 3: Set Up Environment Variables

The cliGCP tool requires environment variables for GCP configuration. You can set these directly or create an .envrc file:

cd bin
touch .envrc

Add the following content to the .envrc file:

export GCP_PROJECT=your-gcp-project-id
export GCP_REGION=us-central1
export GEMINI_MODELS=gemini-2.0-flash

Note: IMAGEN_MODELS and IMAGE_DIR are no longer needed for the cliGCP host. Image generation is available through the independent tools/imagen MCP server.

Load the environment variables:

source .envrc

Step 4: Run the cliGCP Tool

Now you can run the cliGCP tool with MCP tools:

cd bin
./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./dispatch_agent -glob-path ./GlobTool -grep-path ./GrepTool -ls-path ./LS -view-path ./View;./Bash;./Replace"

You should see a welcome message and a prompt where you can start interacting with the CLI.

Step 5: Simple Queries

Let’s try a few simple interactions:

> Hello, who are you?

You should get a response introducing the agent.

Step 6: Using Tools

Now let’s try using some of the MCP tools:

> List the files in the current directory

The CLI should call the LS tool and show you the files in the current directory.

> Search for files with "go" in the name

The CLI will use the GlobTool to find files matching that pattern.

> Read the README.md file

The CLI will use the View tool to show you the contents of the README.md file.

Step 7: Creating a Simple Task

Let’s create a simple task that combines multiple tools:

> Create a new file called test.txt with the text "Hello, world!" and then verify it exists

The CLI should:

1. Use the Replace tool to create the file
2. Use the LS tool to verify the file exists
3. Use the View tool to show you the contents of the file

What You’ve Learned

In this tutorial, you’ve:

1. Set up the cliGCP environment
2. Run the CLI with MCP tools
3. Performed basic interactions with the CLI
4. Used various tools through the CLI to manipulate files
5. Created a simple workflow combining multiple tools

Next Steps

Now that you’re familiar with the cliGCP tool, you can:

• Explore more complex tasks that use multiple tools
• Try using the dispatch_agent for more complex operations
• Create custom tools and use them with the CLI
• Experiment with different Gemini models

Check out the How to Configure the cliGCP Tool guide for advanced configuration options.