stemedb/docs/references/go-adk/README.md

# 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](./reference-guide.md)** - Complete ADK-Go integration documentation
- **[Research Notes](./research.md)** - Research and design considerations

---

## Agent Examples

### Basic Agents

- **[Chatbot Agent](./agent-chatbot.md)** - Simple conversational agent with Episteme integration
- **[Sales Agent](./agent-sales-agent.md)** - Sales automation with knowledge graph lookups

### Advanced Agents

- **[Researcher Agent](./agent-researcher.md)** - Research assistant with claim tracking and validation
- **[Multi-Chatters Agent](./agent-multi-chatters.md)** - Multi-agent conversation system
- **[Planning Facilitator](./agent-planning-facilitator.md)** - Planning and coordination agent

---

## Key Concepts

### Tool Integration

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

```go
// 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

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

### Basic Setup

```go
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](../../.claude/guides/integrations/adk-go-episteme.md)**

---

## 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:

```go
// 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:

```go
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:

```go
// 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:

```go
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:

```go
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](../../sdk/go-sdk.md)** - Episteme Go client library
- **[API Documentation](../../../crates/stemedb-api/README.md)** - HTTP API reference
- **[Architecture](../../../architecture.md)** - System design
- **[Use Cases](../../../use-cases/README.md)** - Real-world examples

---

## See Also

- **[Integration Guide](../../.claude/guides/integrations/adk-go-episteme.md)** - Detailed integration walkthrough
- **[AI Assistant Integration](../../.claude/guides/integrations/ai-coding-assistant-integration.md)** - Claude/Cursor setup

---

**[← Back to Documentation Index](../../README.md)**