Skip to content

getting-started.md

Latest commit

 

History

History
243 lines (172 loc) · 6.53 KB

getting-started.md

File metadata and controls

243 lines (172 loc) · 6.53 KB
Raw

Getting Started

Welcome to AgenticGoKit! You'll build and run your first AI agent in just 5 minutes.

AgenticGoKit is a production-ready framework for building AI agents in Go. An agent is a program that takes user input, thinks about it (optionally with tools and memory), and returns a response from an LLM.

Installation

# Install the library
go get github.com/agenticgokit/agenticgokit/v1beta

# Set your LLM provider API key
export OPENAI_API_KEY="sk-..."          # OpenAI
export OLLAMA_HOST="http://localhost:11434"  # Ollama (local)

For Ollama, install from ollama.com and pull a model:

ollama pull llama2

Your First Agent

Step 1: Create Your Agent

Create a file called main.go:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/agenticgokit/agenticgokit/v1beta"
)

func main() {
    // Set your LLM API key (or use environment variables)
    os.Setenv("OPENAI_API_KEY", "your-api-key-here")

    // Create an agent
    agent, err := v1beta.NewChatAgent("Assistant",
        v1beta.WithLLM("openai", "gpt-4"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // Run the agent
    result, err := agent.Run(context.Background(), "What is Go?")
    if err != nil {
        log.Fatal(err)
    }

    // Print the result
    fmt.Println("Response:", result.Content)
    fmt.Println("Success:", result.Success)
}

Step 2: Run It

go run main.go

Output:

Response: Go is a statically typed, compiled programming language developed at Google...
Success: true

Congratulations! You just built your first AgenticGoKit agent! 🎉

🎯 What Just Happened?

Agent

An Agent is your interface to an LLM. You create it once with configuration (which model, what to remember, which tools to use), then call it repeatedly.

agent, err := v1beta.NewChatAgent("Assistant", v1beta.WithLLM("openai", "gpt-4"))
// Result: An Agent that uses OpenAI's GPT-4 model

Run

Run executes the agent with user input and waits for the complete response.

result, err := agent.Run(context.Background(), "Your question here")
// Returns: Complete response + metadata (tokens used, execution time, etc.)

Result

The Result contains:

  • Content - The LLM's response text
  • Success - Whether execution succeeded
  • Duration - How long it took
  • TokensUsed - LLM tokens consumed
  • Memory - Whether memory was used
  • Other metadata
if result.Success {
    fmt.Println(result.Content)      // The response
    fmt.Println(result.TokensUsed)   // Cost indicator
}

Memory

By default, agents remember the conversation. Each agent automatically stores interactions using an embedded memory provider (chromem). Call the same agent multiple times and it remembers what you said.

result1, _ := agent.Run(ctx, "My name is Alice")
result2, _ := agent.Run(ctx, "What is my name?")
// Result2 will answer: "Your name is Alice" ← From memory!

If you prefer stateless agents (no memory), you can disable it—see Memory & RAG.

🔧 Common Customizations

Use a Different Model

// Use GPT-3.5-turbo instead
agent, err := v1beta.NewChatAgent("Assistant",
    v1beta.WithLLM("openai", "gpt-3.5-turbo"),
)

// Or use Ollama locally
agent, err := v1beta.NewChatAgent("Assistant",
    v1beta.WithLLM("ollama", "llama2"),
)

Add a Custom System Prompt

agent, err := v1beta.NewBuilder("Assistant").
    WithPreset(v1beta.ChatAgent).
    WithConfig(&v1beta.Config{
        SystemPrompt: "You are a friendly pirate",
    }).
    Build()

result, _ := agent.Run(ctx, "Hello!")
// Response: "Ahoy, matey! What be bringin' ye to these waters?"

Set a Timeout

agent, err := v1beta.NewChatAgent("Assistant",
    v1beta.WithLLM("openai", "gpt-4"),
    v1beta.WithAgentTimeout(15 * time.Second), // Max 15 seconds
)

Want more control? See the Configuration Guide for all builder options, presets, and advanced settings.

⚡ What's Next?

The agent you just built is functional but basic. Here's what you can add depending on your needs:

🌊 Real-Time Streaming

Display responses token-by-token as they're generated (instead of waiting for the complete response).

→ Streaming Guide

🔄 Multi-Agent Workflows

Build pipelines where multiple agents work together (one researches, another writes, another reviews).

→ Workflows Guide

🛠️ Tool Integration

Give agents the ability to call external APIs, databases, file systems, etc. via the Model Context Protocol (MCP).

→ Tool Integration

💾 Memory & RAG

Enable agents to store and retrieve custom knowledge, documents, and long-term facts.

→ Memory & RAG

📊 Observability & Tracing

Get complete visibility into agent execution with distributed tracing, workflow tracking, and LLM call metrics.

→ Observability Guide

🎨 Custom Logic

Write handlers to control exactly how agents process input (bypass LLM for certain queries, apply custom rules, etc.).

→ Custom Handlers

📊 Deeper Configuration

Fine-tune temperature, max tokens, timeouts, caching, and more.

→ Configuration Guide

📚 Suggested Learning Path

We recommend exploring in this order:

  1. ✅ You are here: Getting Started (5 min) - Build and run an agent
  2. Core Concepts (15 min) - Understand agents, handlers, tools, and memory
  3. Pick your path:
  4. Explore examples - See complete projects in examples/
  5. Troubleshoot - Visit Troubleshooting if something breaks

🆘 Need Help?

Ready to learn more? Continue to Core Concepts →