stemedb/docs/references/go-adk

ADK-Go Reference Documentation

Google ADK-Go integration patterns and agent examples for Episteme.

---

Overview

The Google Agent Development Kit (ADK) for Go enables building AI agents that can use tools to interact with external systems. These guides show how to integrate ADK-Go agents with Episteme for knowledge graph-powered AI applications.

---

Core Reference

• Reference Guide - Complete ADK-Go integration documentation
• Research Notes - Research and design considerations

---

Agent Examples

Basic Agents

• Chatbot Agent - Simple conversational agent with Episteme integration
• Sales Agent - Sales automation with knowledge graph lookups

Advanced Agents

• Researcher Agent - Research assistant with claim tracking and validation
• Multi-Chatters Agent - Multi-agent conversation system
• Planning Facilitator - Planning and coordination agent

---

Key Concepts

Tool Integration

ADK-Go agents use "tools" to interact with Episteme:

// Query knowledge graph
func QueryKnowledge(ctx context.Context, subject, predicate string, lens string) (string, error) {
    resp, err := episteme.Query(ctx, &QueryParams{
        Subject:   subject,
        Predicate: predicate,
        Lens:      lens,
    })
    return formatForAgent(resp), nil
}

// Assert new facts
func AssertFact(ctx context.Context, subject, predicate, object string) error {
    return episteme.Assert(ctx, &AssertionRequest{
        Subject:    subject,
        Predicate:  predicate,
        Object:     ObjectText(object),
        Confidence: 0.9,
    })
}

Agent Patterns

1. Query-First: Agents query Episteme before making decisions
2. Claim-Backed: Agents cite sources from knowledge graph
3. Conflict-Aware: Agents surface disagreement instead of hiding it
4. Auditable: All agent queries tracked in audit trail

---

Integration Guide

Prerequisites

go get google.golang.org/genai
go get github.com/orchard9/stemedb-go/steme

Basic Setup

import (
    "google.golang.org/genai"
    "github.com/orchard9/stemedb-go/steme"
)

// Initialize Episteme client
signer, _ := steme.GenerateSigner()
episteme := steme.NewClient("http://localhost:18180", signer)

// Create agent with tools
agent := genai.NewAgent(
    genai.WithModel("gemini-2.0-flash"),
    genai.WithTools(
        QueryKnowledgeTool(episteme),
        AssertFactTool(episteme),
    ),
)

→ Full Integration Guide

---

Use Cases

Agent Type	Use Case	Example
Chatbot	Customer support with knowledge base	Answer questions with cited sources
Researcher	Literature review and synthesis	Track conflicting studies, surface disagreement
Sales Agent	Lead qualification and outreach	Query customer history, log interactions
Planning Facilitator	Project planning and coordination	Track decisions, maintain context across sessions
Multi-Chatters	Multi-agent collaboration	Agents share knowledge graph, resolve conflicts

---

Best Practices

1. Query Before Assert

Always query existing knowledge before creating new assertions:

// Check if fact already exists
existing, _ := episteme.Query(ctx, &QueryParams{
    Subject: subject,
    Predicate: predicate,
})

if existing.Winner == nil {
    // No existing fact, safe to assert
    episteme.Assert(ctx, assertion)
}

2. Use Appropriate Lenses

Choose the right lens for your use case:

• Consensus: General queries where majority view matters
• Recency: Real-time data (prices, status)
• Authority: Regulatory or official information
• Skeptic: Research where disagreement is valuable

3. Include Confidence Scores

Always include confidence when asserting:

assertion := steme.NewAssertion(subject, predicate).
    WithString(value).
    WithConfidence(0.85).  // Be explicit about certainty
    Build()

4. Track Agent Identity

Use agent-specific keys for audit trail:

// Each agent has its own signer
agentSigner, _ := steme.LoadSigner("agent-key.pem")
client := steme.NewClient(endpoint, agentSigner)

---

Testing

Mock Episteme

Use test doubles for unit testing:

type MockEpisteme struct {
    assertions map[string]*Assertion
}

func (m *MockEpisteme) Query(ctx, params) (*QueryResult, error) {
    // Return test data
}

func (m *MockEpisteme) Assert(ctx, assertion) (string, error) {
    // Track assertions for verification
}

Integration Tests

Test against real Episteme instance:

func TestAgentIntegration(t *testing.T) {
    // Start test Episteme instance
    episteme := startTestInstance(t)
    defer episteme.Shutdown()

    // Run agent
    result := agent.Run(ctx, "Test query")

    // Verify assertions created
    assertions := episteme.GetAssertions()
    assert.Len(t, assertions, 1)
}

---

Resources

• Go SDK Reference - Episteme Go client library
• API Documentation - HTTP API reference
• Architecture - System design
• Use Cases - Real-world examples

---

See Also

• Integration Guide - Detailed integration walkthrough
• AI Assistant Integration - Claude/Cursor setup

---

← Back to Documentation Index