AgentDB with Go

var (
	baseURL   = strings.TrimRight(cmp.Or(os.Getenv("AGENTDB_URL"), "https://app.agentdb.link"), "/")
	apiKey    = os.Getenv("AGENTDB_API_KEY")   // a server-side secret: never in browser code
	workspace = os.Getenv("AGENTDB_WORKSPACE") // ws_...
	apiURL    = baseURL + "/v1/workspaces/" + workspace
)

func init() {
	if apiKey == "" || workspace == "" {
		log.Fatal("Set AGENTDB_API_KEY and AGENTDB_WORKSPACE")
	}
}

// M is a JSON object.
type M = map[string]any

// AgentDBError is an AgentDB error: HTTP status plus the error envelope {code, message, retryable, details}.
type AgentDBError struct {
	Status    int
	Code      string `json:"code"`
	Message   string `json:"message"`
	Retryable bool   `json:"retryable"`
	Details   M      `json:"details"`
}

func (e *AgentDBError) Error() string { return fmt.Sprintf("%d %s: %s", e.Status, e.Code, e.Message) }

// Request holds the optional parts of a call.
type Request struct {
	JSON           any    // sent as application/json
	Body           []byte // sent as application/octet-stream
	IdempotencyKey string
}

// send makes one API call. It sends the key in the Authorization header. It retries 429 and 503
// with Retry-After (or exponential backoff), and network errors when the call is safe to repeat
// (GET, or a write with an Idempotency-Key). It returns the raw response; close its Body.
func send(method, path string, req Request) (*http.Response, error) {
	safeToRepeat := method == "GET" || req.IdempotencyKey != ""
	for attempt := 0; ; attempt++ {
		backoff := time.Duration(500<<attempt) * time.Millisecond
		var body io.Reader
		contentType := ""
		if req.JSON != nil {
			b, err := json.Marshal(req.JSON)
			if err != nil {
				return nil, err
			}
			body, contentType = bytes.NewReader(b), "application/json"
		} else if req.Body != nil {
			body, contentType = bytes.NewReader(req.Body), "application/octet-stream"
		}
		httpReq, err := http.NewRequest(method, apiURL+path, body)
		if err != nil {
			return nil, err
		}
		httpReq.Header.Set("Authorization", "Bearer "+apiKey)
		if contentType != "" {
			httpReq.Header.Set("Content-Type", contentType)
		}
		if req.IdempotencyKey != "" {
			httpReq.Header.Set("Idempotency-Key", req.IdempotencyKey)
		}
		res, err := http.DefaultClient.Do(httpReq)
		if err != nil {
			if safeToRepeat && attempt < 4 {
				time.Sleep(backoff)
				continue
			}
			return nil, err
		}
		if (res.StatusCode == 429 || res.StatusCode == 503) && attempt < 4 {
			res.Body.Close()
			wait := backoff + time.Duration(mathrand.IntN(250))*time.Millisecond
			if seconds, _ := strconv.Atoi(res.Header.Get("Retry-After")); seconds > 0 {
				wait = time.Duration(seconds) * time.Second
			}
			time.Sleep(wait)
			continue
		}
		if res.StatusCode < 200 || res.StatusCode > 299 {
			defer res.Body.Close()
			var envelope struct {
				Error AgentDBError `json:"error"`
			}
			_ = json.NewDecoder(res.Body).Decode(&envelope) // no envelope: keep the defaults
			apiErr := envelope.Error
			apiErr.Status = res.StatusCode
			if apiErr.Code == "" {
				apiErr.Code = "HTTP_ERROR"
			}
			return nil, &apiErr
		}
		return res, nil
	}
}

// call makes one API call and returns the "data" part of the answer.
func call(method, path string, req Request) (M, error) {
	res, err := send(method, path, req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()
	var envelope struct {
		Data M `json:"data"`
	}
	err = json.NewDecoder(res.Body).Decode(&envelope)
	return envelope.Data, err
}

	schema, err := call("GET", "/object-types", Request{})
	if err != nil {
		log.Fatal(err)
	}
	var names []string
	for _, o := range schema["objects"].([]any) {
		names = append(names, o.(M)["name"].(string))
	}
	fmt.Println("Objects:", strings.Join(names, ", "))

	ada, err := call("POST", "/records", Request{
		JSON:           M{"object": "contact", "data": M{"name": "Ada Lovelace", "email": "ada-" + run + "@example.com", "score": 72}},
		IdempotencyKey: randomUUID(), // safe to retry: the same key never writes twice
	})
	if err != nil {
		log.Fatal(err)
	}
	adaID := ada["id"].(string)
	fmt.Println("Created", adaID, "version", ada["version"])

	record, err := call("GET", "/records/"+adaID, Request{})
	if err != nil {
		log.Fatal(err)
	}
	data := record["data"].(M)
	fmt.Println(data["name"], data["email"], "version", record["version"])

	// updateRecord reads, changes and writes with the current version.
	// On VERSION_CONFLICT it reads again and retries.
	updateRecord := func(id string, change func(data M) M) (M, error) {
		for i := 1; ; i++ {
			current, err := call("GET", "/records/"+id, Request{})
			if err != nil {
				return nil, err
			}
			updated, err := call("PATCH", "/records/"+id, Request{JSON: M{"version": current["version"], "data": change(current["data"].(M))}})
			var apiErr *AgentDBError
			if errors.As(err, &apiErr) && apiErr.Code == "VERSION_CONFLICT" && i < 3 {
				continue
			}
			return updated, err
		}
	}

	updated, err := updateRecord(adaID, func(data M) M { return M{"score": data["score"].(float64) + 10} })
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Score", updated["data"].(M)["score"], "version", updated["version"])

	_, err = call("PATCH", "/records/"+adaID, Request{JSON: M{"version": 1, "data": M{"score": 0}}}) // stale version
	var conflict *AgentDBError
	if errors.As(err, &conflict) && conflict.Code == "VERSION_CONFLICT" {
		fmt.Println("Conflict: the record is now at version", conflict.Details["current_version"])
	} else if err != nil {
		log.Fatal(err)
	}

	// queryAll returns every record that matches, page by page (limit up to 200; follow next_cursor).
	queryAll := func(object string, where M, sort []M, pageSize int) ([]M, error) {
		var out []M
		cursor := ""
		for {
			query := M{"object": object, "where": where, "sort": sort, "limit": pageSize}
			if cursor != "" {
				query["cursor"] = cursor
			}
			page, err := call("POST", "/query", Request{JSON: query})
			if err != nil {
				return nil, err
			}
			for _, r := range page["records"].([]any) {
				out = append(out, r.(M))
			}
			cursor, _ = page["next_cursor"].(string) // null on the last page
			if cursor == "" {
				return out, nil
			}
		}
	}

	good, err := queryAll(
		"contact",
		M{"all": []M{{"field": "score", "op": "gte", "value": 70}, {"field": "email", "op": "neq", "value": "nobody@example.com"}}},
		[]M{{"field": "score", "order": "desc"}},
		2,
	)
	if err != nil {
		log.Fatal(err)
	}
	for _, c := range good {
		fmt.Println(c["data"].(M)["score"], c["data"].(M)["name"])
	}

	company, err := call("POST", "/records", Request{JSON: M{"object": "company", "data": M{"name": "Example Ltd " + run}}})
	if err != nil {
		log.Fatal(err)
	}
	_, err = call("POST", "/links", Request{
		JSON:           M{"relationship": "works_at", "source_record_id": adaID, "target_record_id": company["id"]},
		IdempotencyKey: fmt.Sprintf("link-%s-%s", adaID, company["id"]),
	})
	if err != nil {
		log.Fatal(err)
	}
	related, err := call("GET", "/records/"+adaID+"/related?relationship=works_at", Request{})
	if err != nil {
		log.Fatal(err)
	}
	var employers []string
	for _, r := range related["records"].([]any) {
		employers = append(employers, r.(M)["data"].(M)["name"].(string))
	}
	fmt.Println("Ada works at", strings.Join(employers, ", "))

	content := []byte("Meeting notes for Ada (" + run + ")\n")
	// 1. Announce the file, 2. send the raw bytes, 3. attach it to a record.
	file, err := call("POST", "/files", Request{JSON: M{"filename": "notes.txt", "content_type": "text/plain", "size": len(content)}})
	if err != nil {
		log.Fatal(err)
	}
	fileID := file["id"].(string)
	if _, err := call("PUT", "/files/"+fileID+"/content", Request{Body: content}); err != nil {
		log.Fatal(err)
	}
	if _, err := call("POST", "/attachments", Request{JSON: M{"file_id": fileID, "record_id": adaID}}); err != nil {
		log.Fatal(err)
	}
	// Download with the key (server side) ...
	download, err := send("GET", "/files/"+fileID+"/content", Request{})
	if err != nil {
		log.Fatal(err)
	}
	back, err := io.ReadAll(download.Body)
	download.Body.Close()
	if err != nil {
		log.Fatal(err)
	}
	// ... or make a signed link that expires, for an <img> or a download button in your page.
	link, err := call("POST", "/files/"+fileID+"/links", Request{JSON: M{"expires_in_seconds": 600}})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Signed link until", link["expires_at"])

	_, err = call("GET", "/records/rec_doesnotexist", Request{})
	var apiErr *AgentDBError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.Status, apiErr.Code, apiErr.Message) // 404 NOT_FOUND ...
		if apiErr.Retryable {
			fmt.Println("Safe to retry later")
		}
	} else if err != nil {
		log.Fatal(err) // a network error, not an AgentDB answer
	}

	key := randomUUID() // one key per intention; reuse it only to retry the same request
	request := M{"object": "contact", "data": M{"name": "Mary Somerville", "email": "mary-" + run + "@example.com"}}
	first, err := call("POST", "/records", Request{JSON: request, IdempotencyKey: key})
	if err != nil {
		log.Fatal(err)
	}
	retry, err := call("POST", "/records", Request{JSON: request, IdempotencyKey: key}) // e.g. after a timeout
	if err != nil {
		log.Fatal(err)
	}
	if first["id"] == retry["id"] {
		fmt.Println("Same record, written once")
	} else {
		fmt.Println("Duplicate!")
	}

go run .