README
¶
agent-go
A basic set of libraries to call LLM models using the OpenAI chat completions API. Still very incomplete and liable to change.
Why yet another set of libraries?
- For learning, best way to understand how this stuff works is to build it yourself.
- To keep it as clean and simple as possible, I'm just adding the functionality which I actually need right now. Existing frameworks seem massively over complicated for what they actually do.
Setup
Make sure you have at least go version 1.25 installed. Clone the repo and run go mod tidy to pull the dependencies. For playwright-go (which is used by the browser tool) you also need to install the drivers and browsers - see https://github.com/playwright-community/playwright-go
To use the weather tool you'll need to set OWM_API_KEY environment variable with the API key obtained from openweathermap.org. You can sign up free for these calls here.
To use the Brave search tool you need to set the BRAVE_API_KEY environment variable with the API key from brave.com. They have now dropped new subscriptions to the free plan though. It seems you can sign up for $5 / month with a $5 monthly credit to cover the first 1000 searches .You can see details on that page.
The tests are using Qwen3.5-9B model which I am running with llama.cpp. There are some notes on getting that setup from unsloth. The bigger Qwen3.5 models are even better if you have enough VRAM. You'll need to set OPENAI_BASE_URL to point to your server endpoint - e.g. export OPENAI_BASE_URL=http://localhost:8080/v1. It should also work with any provider supporting the OpenAI API - just set OPENAI_BASE_URL and OPENAI_API_KEY.
Packages
- llm : Provides a simple wrapper around the openai SDK supporting model selection and chat completions with tool calling and streaming of results. Includes non standard fields to get and send reasoning traces and retrieve llama.cpp timing stats.
- agents : A basic agent implementation supporting setting the system prompt, adding tools and managing the tool call run loop. TODO: add functions to support saving and restoring the message history, pruning the context via sliding window or summarization and prompt templates for dynamic prompt generation.
- scrape : A web page scraper built using the playwright-go and [html-to-markdown](https://github.com/JohannesKaufmann/html-to-markdown}. Uses a headless Firefox instance.
- tools/weather : The classic weather tool example. Uses the openweathermap.org API.
- tools/brave : Web search tool using the Brave search API. Returns a list of 10 links with title and short description.
- tools/browser : Web page open and find tools using the scrape package. Returns the page text formatted with Markdown.
Example programs
- cmd/chat : A simple command line chat app using the llm package.
- cmd/tools : Extends the chat app to use the agents loop with the weather or browser tools.
- cmd/webchat : Web based chat app with Brave search and browser tools.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package agents implements an agent loop with tool calling using llm package to communicate with the model.
|
Package agents implements an agent loop with tool calling using llm package to communicate with the model. |
|
cmd
|
|
|
chat
command
Simple interactive chat example using the llm package.
|
Simple interactive chat example using the llm package. |
|
tools
command
Interactive agent example using the weather or browser tools.
|
Interactive agent example using the weather or browser tools. |
|
webchat
command
Web based chat interface with tool calling
|
Web based chat interface with tool calling |
|
Package llm wraps the openAI SDK to provide a simpler interface to call the chat completions REST API.
|
Package llm wraps the openAI SDK to provide a simpler interface to call the chat completions REST API. |
|
Package scrape provides tools to scrape web page content using Playwright and convert the results to Markdown.
|
Package scrape provides tools to scrape web page content using Playwright and convert the results to Markdown. |
|
tools
|
|
|
brave
Package brave implements a web search tool using the Brave search API - see https://brave.com/search/api/
|
Package brave implements a web search tool using the Brave search API - see https://brave.com/search/api/ |
|
browser
Package browser implements a web page scraper tool using the scrape package.
|
Package browser implements a web page scraper tool using the scrape package. |
|
weather
Package weather implements tools to get the current and forecast weather from https://api.openweathermap.org/
|
Package weather implements tools to get the current and forecast weather from https://api.openweathermap.org/ |