gogentic

gogentic

Agentic LLM applications in Go.

gogentic is a library for building LLM agents: assistants that call tools, hand work to other assistants, produce typed results, and run against any of a dozen providers behind one interface. It is used in production and its API is stable.

It began as a fork of langchaingo, and has since diverged around stronger tool/assistant abstractions, schema generation, Agent Skills, MCP, and multi-tenant model routing.

go get github.com/effective-security/gogentic

What it gives you

Quick start

1. Describe your providers in llm.yaml:

default_provider: OPENAI
providers:
  - name: OPENAI
    token: env://OPENAI_API_KEY
    default_model: gpt-5.1
    available_models: [gpt-5.1, gpt-5.1-mini]
    open_ai:
      api_type: OPENAI
assistant_models:
  default: [OPENAI/gpt-5.1]
  researcher: [OPENAI/gpt-5.1]

2. Define the shape of the answer and run an assistant:

package main

import (
    "context"
    "fmt"

    "github.com/effective-security/gogentic/assistants"
    "github.com/effective-security/gogentic/chatmodel"
    "github.com/effective-security/gogentic/pkg/llmfactory"
    "github.com/effective-security/gogentic/pkg/llmutils"
    "github.com/effective-security/gogentic/pkg/prompts"
    "github.com/effective-security/gogentic/store"
)

// The output type: jsonschema tags are the model's instructions.
type Answer struct {
    Text    string   `json:"text"    jsonschema:"required,title=Text,description=The answer."`
    Sources []string `json:"sources" jsonschema:"title=Sources,description=URLs backing the answer."`
}

func (a Answer) GetContent() string { return llmutils.ToJSON(a) }

func main() {
    fac, err := llmfactory.Load("llm.yaml")
    if err != nil {
        panic(err)
    }

    agent := assistants.NewAssistant[Answer](fac,
        prompts.NewPromptTemplate("You are a concise research assistant.", nil),
        assistants.WithMessageStore(store.NewMemoryStore()),
    ).
        WithName("researcher"). // binds to assistant_models.researcher
        WithDescription("Answers factual questions and cites sources.")

    // Every run needs a ChatContext: user/org/chat/run identity.
    chatCtx := chatmodel.NewChatContext("user-123", "", nil)
    ctx := chatmodel.WithChatContext(context.Background(), chatCtx)

    var out Answer
    resp, err := agent.Run(ctx, &assistants.CallInput{
        Input: "What is the capital of the largest country in Europe?",
    }, &out)
    if err != nil {
        panic(err)
    }

    fmt.Println(out.Text)
    fmt.Println("tokens:", resp.Usage.ModelUsage)
}

Add a tool

A tool is a name, a description, a JSON Schema, and a string → string call. Keep the real logic in a typed Run and let Call adapt the model's JSON:

type Request struct {
    City string `json:"city" jsonschema:"required,title=City,description=City name."`
}

type Result struct {
    TempC float64 `json:"temp_c"`
}

func (r *Result) GetContent() string { return llmutils.ToJSON(r) }

type Tool struct{ params *jsonschema.Schema }

func New() (*Tool, error) {
    sc, err := schema.New(reflect.TypeOf(Request{}))
    if err != nil {
        return nil, errors.Wrap(err, "failed to create schema")
    }
    return &Tool{params: sc.Parameters}, nil
}

func (t *Tool) Name() string                   { return "get_weather" }
func (t *Tool) Description() string            { return "Current temperature for a city." }
func (t *Tool) Parameters() *jsonschema.Schema { return t.params }

func (t *Tool) Run(ctx context.Context, req *Request) (*Result, error) {
    return &Result{TempC: 21.5}, nil
}

func (t *Tool) Call(ctx context.Context, input string) (string, error) {
    var req Request
    if err := json.Unmarshal(llmutils.CleanJSON([]byte(input)), &req); err != nil {
        return "", errors.WithStack(chatmodel.ErrFailedUnmarshalInput)
    }
    out, err := t.Run(ctx, &req)
    if err != nil {
        return "", err
    }
    return out.GetContent(), nil
}

agent = agent.WithTools(weatherTool)

Tools requested in the same LLM turn run concurrently, and a tool error is handed back to the model rather than aborting the run. See Tools.

Orchestrate several agents

Wrap an assistant as a tool and give it to a supervisor. Context, callbacks and call options flow down; token usage rolls up.

researchTool, err := assistants.NewAssistantTool[chatmodel.InputRequest](researcher)
if err != nil {
    return err
}

supervisor := assistants.NewAssistant[chatmodel.OutputResult](fac, supervisorPrompt,
    assistants.WithCallback(callbacks.NewScratchpad(callbacks.ModeVerbose)),
    assistants.WithMaxToolCalls(8),
).
    WithName("supervisor").
    WithTools(researchTool, coderTool)

See Orchestration.

Expose it over MCP

tr := stdio.NewStdioServerTransport()
srv := mcp.NewServer(tr, mcp.WithName("my-agents"), mcp.WithVersion("1.0.0"))

if err := srv.Serve(); err != nil {
    return err
}
if err := researcher.RegisterMCP(srv); err != nil { // as an MCP prompt
    return err
}
if err := weatherTool.RegisterMCP(srv); err != nil { // as an MCP tool
    return err
}
if err := tr.Start(ctx); err != nil {
    return err
}

See MCP.

Load skills from disk

Drop SKILL.md files in a directory; only their names and descriptions enter the prompt, and the model loads full instructions on demand via activate_skill.

skills:
  enable_default_skills: true
  paths: [./skills]

agent = agent.WithSkills(fac.Skills("researcher"))

See Skills.

Documentation

Full documentation is in Documentation/:

• Architecture — package map and the anatomy of one run
• Assistants · Tools · Orchestration
• LLM Factory · LLM Providers
• Structured Output · Prompts
• Memory and Chat Context · Skills · MCP
• Observability
• Code Map — navigation index, also for AI agents

Package-level godoc is available for every package: go doc github.com/effective-security/gogentic/assistants.

Contributing

make generate   # regenerate mocks for changed interfaces
make test       # run the suite
make lint       # final check

Read AGENTS.md for error handling, testing and documentation conventions, and Documentation/codemap.md for the invariants the agent loop depends on.

See ROADMAP.md for planned work.

License

Apache 2.0