How to add an AI agent to a Gin app

go get github.com/anthropics/anthropic-sdk-go/[email protected]

package main

import (
	"context"
	"encoding/json"
	"errors"
	"sync"

	"github.com/anthropics/anthropic-sdk-go/v2"
	"github.com/anthropics/anthropic-sdk-go/v2/toolrunner"
)

type chatRequest struct {
	Messages []struct {
		Role string `json:"role"`
		Text string `json:"text"`
	} `json:"messages"`
}

// history accepts plain text turns only, so a client cannot forge tool calls or tool results.
func (r chatRequest) history() ([]anthropic.BetaMessageParam, error) {
	n := len(r.Messages)
	if n == 0 || n > 40 || r.Messages[n-1].Role != "user" {
		return nil, errors.New("invalid conversation")
	}
	out := make([]anthropic.BetaMessageParam, 0, n)
	for _, m := range r.Messages {
		if m.Text == "" {
			return nil, errors.New("empty message")
		}
		text := anthropic.NewBetaTextBlock(m.Text)
		switch m.Role {
		case "user":
			out = append(out, anthropic.NewBetaUserMessage(text))
		case "assistant":
			out = append(out, anthropic.BetaMessageParam{OfAssistant: &anthropic.BetaAssistantMessageParam{
				Content: []anthropic.BetaContentBlockParamUnion{text},
			}})
		default:
			return nil, errors.New("invalid role")
		}
	}
	return out, nil
}

// pendingCancels collects the cancellations the model proposed. The runner may run tools in parallel.
type pendingCancels struct {
	sync.Mutex
	ids []string
}

type listOrdersInput struct {
	Status string `json:"status,omitempty" jsonschema:"enum=open,enum=shipped,enum=cancelled"`
}

type cancelOrderInput struct {
	OrderID string `json:"orderId" jsonschema:"required,description=ID of the order to cancel"`
}

func jsonResult(v any) (anthropic.BetaToolResultBlockParamContentUnion, error) {
	data, err := json.Marshal(v)
	return anthropic.BetaToolResultBlockParamContentUnion{OfText: &anthropic.BetaTextBlockParam{Text: string(data)}}, err
}

// newRunner gives the model two tools that close over the authenticated user:
// the model chooses arguments, never whose orders it reads or cancels.
func newRunner(client anthropic.Client, userID string, history []anthropic.BetaMessageParam) (
	*anthropic.BetaToolRunnerStreaming, *pendingCancels, error) {
	pending := &pendingCancels{}
	listOrders, err := toolrunner.NewBetaToolFromJSONSchema("listOrders", "List the signed-in user's recent orders",
		func(ctx context.Context, in listOrdersInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
			orders, err := ListOrders(ctx, userID, in.Status) // your data layer
			if err != nil {
				return anthropic.BetaToolResultBlockParamContentUnion{}, err
			}
			return jsonResult(orders)
		})
	if err != nil {
		return nil, nil, err
	}
	cancelOrder, err := toolrunner.NewBetaToolFromJSONSchema("cancelOrder",
		"Propose cancelling one of the signed-in user's open orders. Nothing changes until the user confirms.",
		func(ctx context.Context, in cancelOrderInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
			order, err := GetOrder(ctx, userID, in.OrderID) // not found unless it belongs to userID
			if err != nil {
				return anthropic.BetaToolResultBlockParamContentUnion{}, err
			}
			if order.Status != "open" {
				return anthropic.BetaToolResultBlockParamContentUnion{}, errors.New("only open orders can be cancelled")
			}
			pending.Lock()
			pending.ids = append(pending.ids, order.ID)
			pending.Unlock()
			return jsonResult(map[string]string{"orderId": order.ID, "status": "waiting for the user to confirm"})
		})
	if err != nil {
		return nil, nil, err
	}
	runner := client.Beta.Messages.NewToolRunnerStreaming([]anthropic.BetaTool{listOrders, cancelOrder},
		anthropic.BetaToolRunnerParams{
			BetaMessageNewParams: anthropic.BetaMessageNewParams{
				Model:     anthropic.ModelClaudeSonnet5_5,
				MaxTokens: 2048,
				System: []anthropic.BetaTextBlockParam{
					{Text: "You help the signed-in user manage their orders. Use the tools; never guess order data."},
				},
				Messages: history,
			},
			MaxIterations: 5, // at most five model calls per request
		})
	return runner, pending, nil
}

package main

import (
	"context"
	"log"
	"net/http"
	"time"

	"github.com/anthropics/anthropic-sdk-go/v2"
	"github.com/gin-gonic/gin"
)

// requireUser rejects signed-out requests and stores the user your session middleware found.
func requireUser(c *gin.Context) {
	userID := currentUserID(c) // your existing session lookup
	if userID == "" {
		c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
		return
	}
	c.Set("userID", userID)
	c.Next()
}

func registerAgentRoutes(r *gin.Engine, client anthropic.Client) {
	api := r.Group("/api", requireUser)
	api.POST("/agent", agentHandler(client))
	// The only place an order is cancelled: a request the signed-in user confirmed.
	api.POST("/orders/:id/cancel", func(c *gin.Context) {
		if err := CancelOrder(c.Request.Context(), c.GetString("userID"), c.Param("id")); err != nil {
			c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "not found"})
			return
		}
		c.Status(http.StatusNoContent)
	})
}

func agentHandler(client anthropic.Client) gin.HandlerFunc {
	return func(c *gin.Context) {
		var req chatRequest
		if err := c.ShouldBindJSON(&req); err != nil {
			c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": "invalid JSON"})
			return
		}
		history, err := req.history()
		if err != nil {
			c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}
		runner, pending, err := newRunner(client, c.GetString("userID"), history)
		if err != nil {
			c.AbortWithStatus(http.StatusInternalServerError)
			return
		}

		// Canceled when the browser disconnects or the run takes too long.
		ctx, cancel := context.WithTimeout(c.Request.Context(), 2*time.Minute)
		defer cancel()
		send := func(event string, data any) {
			c.SSEvent(event, data) // text/event-stream, data JSON-encoded
			c.Writer.Flush()
		}

		for !runner.IsCompleted() {
			for event, err := range runner.NextStreaming(ctx) {
				if err != nil {
					log.Printf("agent: %v", err)
					send("error", gin.H{"message": "The assistant stopped. Try again."})
					return
				}
				switch e := event.AsAny().(type) {
				case anthropic.BetaRawContentBlockStartEvent:
					if tool, ok := e.ContentBlock.AsAny().(anthropic.BetaToolUseBlock); ok {
						send("tool", gin.H{"name": tool.Name})
					}
				case anthropic.BetaRawContentBlockDeltaEvent:
					if delta, ok := e.Delta.AsAny().(anthropic.BetaTextDelta); ok {
						send("text", gin.H{"text": delta.Text})
					}
				}
			}
		}
		for _, id := range pending.ids {
			send("confirm", gin.H{"orderId": id})
		}
		send("done", gin.H{})
	}
}

func main() {
	r := gin.Default()
	// r.Use(yourSessionMiddleware)
	registerAgentRoutes(r, anthropic.NewClient()) // reads ANTHROPIC_API_KEY

	srv := &http.Server{
		Addr:              ":8080",
		Handler:           http.NewCrossOriginProtection().Handler(r), // rejects cross-site POSTs
		ReadHeaderTimeout: 10 * time.Second,
		// No WriteTimeout: it would cut off agent streams that run for minutes.
	}
	log.Fatal(srv.ListenAndServe())
}

// Posts the conversation, then reads the Server-Sent Events from the response body.
// Expects <div id="agent-log"></div> and <form id="agent-form"><input name="message"></form> in the page.
const messages = [];
const log = document.querySelector("#agent-log");
const form = document.querySelector("#agent-form");
// http.CrossOriginProtection checks Sec-Fetch-Site and Origin, so same-origin fetches need no token.
const headers = { "Content-Type": "application/json" };

function add(text) {
  const p = log.appendChild(document.createElement("p"));
  p.textContent = text;
  return p;
}

function confirmCancel(orderId) {
  const button = log.appendChild(document.createElement("button"));
  button.textContent = "Cancel order " + orderId;
  button.onclick = async () => {
    const res = await fetch("/api/orders/" + encodeURIComponent(orderId) + "/cancel", { method: "POST", headers });
    button.replaceWith(add(res.ok ? "Order " + orderId + " cancelled." : "Cancelling failed."));
  };
}

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  const text = form.elements.message.value.trim();
  if (!text) return;
  form.reset();
  messages.push({ role: "user", text });
  add(text);

  const res = await fetch("/api/agent", { method: "POST", headers, body: JSON.stringify({ messages }) });
  if (!res.ok) {
    add("Request failed (" + res.status + ").");
    messages.pop();
    return;
  }
  let reply = add("");
  let answer = "";
  let buffer = "";
  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += value;
    let end;
    while ((end = buffer.indexOf("\n\n")) >= 0) {
      const frame = buffer.slice(0, end);
      buffer = buffer.slice(end + 2);
      const name = frame.match(/^event: ?(.*)$/m)?.[1];
      const data = JSON.parse(frame.match(/^data: ?(.*)$/m)?.[1] ?? "{}");
      if (name === "text") {
        reply.textContent += data.text;
        answer += data.text;
      } else if (name === "tool") {
        add("Running " + data.name + "...");
        reply = add("");
      } else if (name === "confirm") {
        confirmCancel(data.orderId);
      } else if (name === "error") {
        add(data.message);
      }
    }
  }
  if (answer) messages.push({ role: "assistant", text: answer });
});

<!-- In <head>, before your application's own scripts -->
<script src="/assets/agent-identity.js"><\/script>
<script src="https://embed.bunkhouse.ai/embed.js" data-public-key="pk_YOUR_SITE_PUBLIC_KEY"><\/script>

Read https://api.bunkhouse.ai/agent-trial.md and follow it to run a Bunkhouse agent trial on my dummy Gin page at http://localhost:8080.

Use a page with disposable data: everything the assistant reads is sent to your agent.