Skip to content

installation.md

Latest commit

 

History

History
353 lines (249 loc) · 8.17 KB

installation.md

File metadata and controls

353 lines (249 loc) · 8.17 KB
Raw
title Installation
description Set up AgenticGoKit and verify your development environment
prev
text link
Getting Started
./README
next
text link
Understanding Agents
./understanding-agents

Installation

Let's get AgenticGoKit installed and running on your system. This guide covers everything you need to start building AI agent systems.

Learning Objectives

By the end of this section, you'll have:

  • AgenticGoKit CLI installed and working
  • Go development environment verified
  • LLM provider configured (OpenAI, Azure OpenAI, or local Ollama)
  • Created and validated your first project

System Requirements

Before we begin, ensure your system meets these requirements:

  • Operating System: Windows 10+, macOS 10.15+, or Linux (Ubuntu 18.04+, CentOS 7+)
  • Go: Version 1.21 or later
  • Memory: At least 4GB RAM (8GB recommended for local LLM usage)
  • Disk Space: 2GB free space for tools and models
  • Network: Internet connection for downloading dependencies and accessing cloud LLM providers

Step 1: Verify Go Installation

First, let's make sure Go is properly installed:

go version

You should see output like:

go version go1.21.0 linux/amd64

If Go isn't installed or is an older version:

Installing Go

Windows:

  1. Download Go from golang.org/dl
  2. Run the installer and follow the prompts
  3. Restart your command prompt/PowerShell

macOS:

# Using Homebrew (recommended)
brew install go

# Or download from golang.org/dl

Linux:

# Ubuntu/Debian
sudo apt update
sudo apt install golang-go

# CentOS/RHEL/Fedora
sudo dnf install golang
# or: sudo yum install golang

Step 2: Install AgenticGoKit CLI

The AgenticGoKit CLI (agentcli) is your main tool for creating and managing agent projects.

Recommended Installation

go install github.com/kunalkushwaha/agenticgokit/cmd/agentcli@latest

Verify Installation

agentcli version

You should see version information like:

agentcli version v0.3.0

Test CLI Commands

Let's verify the main commands are available:

# Show help
agentcli --help

# List available templates
agentcli config template --list

# Show MCP commands
agentcli mcp --help

::: tip Success Indicator If all commands show help text without errors, your CLI installation is working correctly! :::

Step 3: Choose Your LLM Provider

AgenticGoKit supports multiple LLM providers. Choose the option that works best for you:

Option A: OpenAI (Easiest to start)

Pros: Reliable, high-quality responses, easy setup Cons: Requires API key and costs money per request

  1. Get an API key from OpenAI
  2. Set your environment variable:

Windows (PowerShell):

$env:OPENAI_API_KEY = "your-api-key-here"

macOS/Linux (Bash):

export OPENAI_API_KEY="your-api-key-here"

Option B: Azure OpenAI (Enterprise choice)

Pros: Enterprise features, data privacy, reliable Cons: Requires Azure subscription and setup

  1. Set up Azure OpenAI service in Azure portal
  2. Get your endpoint, API key, and deployment name
  3. Set environment variables:

Windows (PowerShell):

$env:AZURE_OPENAI_API_KEY = "your-api-key"
$env:AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com/"
$env:AZURE_OPENAI_DEPLOYMENT = "your-deployment-name"

macOS/Linux (Bash):

export AZURE_OPENAI_API_KEY="your-api-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT="your-deployment-name"

Option C: Ollama (Local, free)

Pros: Free, private, works offline Cons: Requires more setup, uses local resources

  1. Install Ollama:

Windows:

macOS:

# Using Homebrew
brew install ollama

# Or download from ollama.ai

Linux:

curl -fsSL https://ollama.ai/install.sh | sh
  1. Start Ollama service:
# Start Ollama (runs in background)
ollama serve
  1. Download a model:
# Download a lightweight model (recommended for getting started)
ollama pull gemma2:2b

# Or a more capable model (requires more memory)
ollama pull llama3.1:8b
  1. Set environment variable:
export OLLAMA_HOST="http://localhost:11434"

Step 4: Create Your First Project

Let's verify everything works by creating a test project:

# Create a basic agent project
agentcli create test-project --template basic

# Navigate to the project
cd test-project

Examine the Project Structure

Look at what was created:

# List the files
ls -la

# View the main configuration
cat agentflow.toml

You should see:

  • main.go - The main application entry point
  • agentflow.toml - Configuration file for your agents
  • go.mod - Go module file
  • agents/ - Directory containing agent implementations

Validate the Configuration

agentcli validate

You should see:

Status: VALID
Configuration is correct and ready to use.

Step 5: Test Your Setup

Let's run your first agent to make sure everything works:

# Run the agent with a simple message
go run . -m "Hello, can you introduce yourself?"

Expected Output: You should see the agent respond with an introduction. The exact response will vary based on your LLM provider and model.

::: tip Success! If you see a response from your agent, congratulations! Your AgenticGoKit installation is working correctly. :::

Troubleshooting Common Issues

"agentcli: command not found"

Problem: The CLI isn't in your system PATH.

Solution:

  1. Make sure $GOPATH/bin is in your PATH
  2. Check where Go installs binaries: go env GOPATH
  3. Add $GOPATH/bin to your PATH in your shell profile

"provider not registered" error

Problem: Missing plugin imports in your Go code.

Solution: The generated projects include necessary imports, but if you see this error, ensure your main.go includes:

import (
    _ "github.com/kunalkushwaha/agenticgokit/plugins/llm/openai"
    _ "github.com/kunalkushwaha/agenticgokit/plugins/llm/ollama"
    // ... other plugins
)

LLM Connection Issues

OpenAI/Azure OpenAI:

  • Verify your API key is correct
  • Check your internet connection
  • Ensure you have sufficient credits/quota

Ollama:

  • Make sure Ollama service is running: ollama serve
  • Verify the model is downloaded: ollama list
  • Check the host URL is correct

Go Module Issues

If you see Go module errors:

# Clean module cache
go clean -modcache

# Re-download dependencies
go mod download

What You've Learned

✅ Installed AgenticGoKit CLI and verified it's working
✅ Configured an LLM provider for your agents to use
✅ Created your first project using the CLI
✅ Validated your setup by running a test agent
✅ Learned troubleshooting techniques for common issues

Next Steps

Now that AgenticGoKit is installed and working, let's understand what agents are and how they work in the AgenticGoKit framework.

→ Continue to Understanding Agents

::: details Quick Navigation

Previous: Getting Started - Tutorial overview and learning path
Next: Understanding Agents - Core concepts and mental models
Jump to: Your First Agent - Skip concepts and start building

:::

::: details Need More Help?

Still having issues? Here are additional resources:

Want to contribute? Check out our Contributor Guide

Related Documentation:

:::