creating-templates.md

Creating AGK Templates

This guide explains how to create, test, and publish templates for AgenticGoKit (AGK). Templates allow developers to scaffold new projects with pre-configured agents, workflows, and tools.

Overview

An AGK template is simply a directory containing:

1. Code: Source files (Go, Markdown, Configs) that structure the project.
2. agk-template.toml: A manifest file defining metadata, variables, and behavior.

Templates are processed using Go's text/template engine with Sprig functions enabled, allowing for dynamic content generation based on user input.

---

1. Template Structure

A typical template structure looks like this:

my-template/
├── agk-template.toml    # Manifest (REQUIRED)
├── go.mod.tmpl          # Go module file template
├── main.go.tmpl         # Main application code template
├── README.md            # Template documentation
├── .gitignore           # Standard gitignore
└── pkg/                 # Subfolders are fully supported
    └── helper.go.tmpl   # Will be rendered to <project>/pkg/helper.go

File Naming

• Files ending in .tmpl will be processed as templates. The .tmpl extension is removed in the generated project (e.g., main.go.tmpl becomes main.go).
• Files without .tmpl are copied as-is, unless they are binary files or excluded by the manifest.
• You can use template variables in filenames (feature coming soon).

---

2. Configuration (agk-template.toml)

The agk-template.toml file is the heart of your template. It defines how agk init interacts with your template.

Full Schema Example

[template]
name = "my-custom-agent"
version = "1.0.0"
description = "A specialized agent for data analysis"
author = "Jane Doe"
license = "MIT"
min_agk_version = "0.1.0"

# Define variables to ask the user during initialization
[template.variables]
  [template.variables.agent_name]
  type = "string"
  description = "Name of your agent"
  required = true
  default = "MyAgent"

  [template.variables.include_memory]
  type = "bool"
  description = "Enable vector memory?"
  default = true

  [template.variables.model_type]
  type = "choice"
  description = "Primary model to use"
  options = ["gpt-4o", "claude-3-5-sonnet"]
  default = "gpt-4o"

# Control which files are copied
[template.files]
include = ["**/*"]
exclude = [".git", "agk-template.toml", "test-data/**"]

# Commands to run after generation
[template.hooks]
post_create = ["go mod tidy", "go fmt ./..."]

Variable Types

• string: simple text input.
• bool: Yes/No prompt.
• choice: Selection from a list of options.

---

3. Writing Template Files

Use standard Go templating syntax ({{ }}) in your files.

Available Data

The following data is available to your templates:

Variable	Description
.ProjectName	The name of the project folder (e.g., "my-bot")
.Description	Project description provided by CLI flag
.LLMProvider	Selected provider (openai, anthropic, ollama)
.LLMModel	Default model for the provider
.WorkflowName	Name of the workflow (for workflow templates)
.APIKeyEnv	Env var name for the key (e.g., OPENAI_API_KEY)
.AgentType	Agent type string
.Variables	(Planning) Access custom variables defined in TOML

Example: main.go.tmpl

package main

import (
    "log"
    "os"
    "github.com/agenticgokit/agenticgokit"
)

func main() {
    // Project: {{ .ProjectName }}
    // Generated by AGK

    config := agenticgokit.Config{
        Provider: "{{ .LLMProvider }}", // e.g. openai
        Model:    "{{ .LLMModel }}",    // e.g. gpt-4o
    }
    
    // ...
}

Scripting with Sprig

You can use Sprig functions for complex logic:

{{ if eq .LLMProvider "ollama" }}
    // Ollama specific setup
{{ end }}

// Helper: {{ .ProjectName | title }}

---

4. Developing Locally

You can test your template locally without publishing it.

Step 1: Create your template folder

mkdir my-template
cd my-template
# ... create files and agk-template.toml ...

Step 2: Add to local registry

Use agk template add to point AGK to your local folder.

# Add current directory as a template
agk template add . 

# Or specify full path
agk template add /absolute/path/to/my-template

Step 3: Test generation

Try to initialize a project using your template.

cd /tmp
agk init test-project --template my-custom-agent

Note: The --template name must match the name field in your agk-template.toml.

Step 4: Iterate

Make changes to your template files. You typically don't need to re-add the template if you pointed to a local path, but if you cached it, you might need to run add again to update the cache.

---

5. Publishing

To share your template with the community:

1. Host on GitHub: Push your template to a public GitHub repository.
2. Verify Fetch: Test that AGK can fetch it directly from the URL.

   agk template add github.com/username/my-template

3. Submit to Registry:
   • Fork the agk-templates/registry repository.
   • Add your template metadata to index.json.
   • Submit a Pull Request.

Once accepted, users will be able to see your template in agk init --list or use it by name!