Agent SDK Architecture - Vegvisr

Nodes

Agent SDK Overview

ID: node-root-overview Type: fulltext

# Agent SDK Architecture for Vegvisr

## Purpose
The Vegvisr Agent SDK enables the creation of specialized AI agents that can:
- Generate HTML-node applications
- Design and apply themes
- Create educational content
- Manipulate knowledge graphs
- Orchestrate complex multi-step workflows

## Architecture Principles
- Separation of Concerns: Each agent has a single, well-defined responsibility
- Composability: Agents can be orchestrated to work together
- Tool-based Design: Agents use OpenAI-compatible function calling
- Graph-native: All agents interact with knowledge graphs as primary data store

## Key Components
1. Agent Runtime (vegvisr-frontend/Vue)
2. Agent Builder App (New React + Vite app)
3. Knowledge Graph API (knowledge.vegvisr.org)
4. Tool Registry (Centralized tool definitions)

References:

https://knowledge.vegvisr.org

HTML App Builder Agent

ID: node-html-app-builder Type: fulltext

# HTML App Builder Agent

## Responsibility
Generate complete HTML-node applications from specifications.

## Tools
- `createhtmlnode` - Generate complete HTML document
- `validatehtmlstructure` - Check compliance with graph standards
- `injectgraphbindings` - Add GRAPHID/NODEID placeholders
- `testhtmlrendering` - Validate HTML renders correctly

## Workflow
```
Input: { appType, theme, features, layout }
Process:
1. Read theme node for style tokens
2. Generate HTML structure with CDN libs (marked, DOMPurify)
3. Inject dynamic graph bindings
4. Validate output
Output: { htmlContent, nodeMetadata, suggestedEdges }
```

## Example Use Cases
- Landing page generator
- Dashboard creator
- Course viewer app
- Portfolio site builder

Theme Designer Agent

ID: node-theme-designer Type: fulltext

# Theme Designer Agent

## Responsibility
Create and modify theme nodes with color palettes and typography.

## Tools
- `extractthemefrom_url` - Scrape existing site for colors/fonts
- `generatethemepalette` - Create harmonious color schemes
- `createcssnode` - Generate stylesheet node
- `validatethemecontract` - Check theme has required CSS classes

## Workflow
```
Input: { baseColors?, fontFamily?, mood? }
Process:
1. Generate color palette (primary, surface, text, etc.)
2. Select typography system
3. Create CSS variables
4. Generate preview HTML
Output: { themeNode, cssNode, previewHtml }
```

## Theme Contract Classes
- v-page
- v-container
- v-section
- v-grid
- v-card
- v-title
- v-text
- v-btn

Graph Architect Agent

ID: node-graph-architect Type: fulltext

# Graph Architect Agent

## Responsibility
Design and manipulate knowledge graph structures.

## Tools
- `analyzegraphstructure` - Get graph topology insights
- `clonegraphtemplate` - Duplicate with ID regeneration
- `creategraphfrom_spec` - Generate new graph from schema
- `optimizegraphedges` - Clean up redundant connections
- `migrategraphdata` - Transform between schemas

## Workflow
```
Input: { sourceGraph?, schema, nodeTypes, edgeRules }
Process:
1. Validate schema
2. Clone or create new graph
3. Apply transformations
4. Regenerate IDs if needed
5. Validate integrity
Output: { graphId, nodeMap, edgeMap, warnings }
```

Knowledge Graph API Endpoints

ID: node-api-endpoints Type: fulltext

# Knowledge Graph API Endpoints

## Base URL
`https://knowledge.vegvisr.org`

## Authentication
Header: `x-user-role: Superadmin`

## Core Endpoints

### Save Graph with History
```bash
POST /saveGraphWithHistory
Content-Type: application/json

Body:
{
"id": "graphuniqueid",
"graphData": {
"metadata": { "title": "...", "version": 0 },
"nodes": [...],
"edges": [...]
},
"override": false
}
```

### Get Graph
```bash
GET /getknowgraph?id=graph_id
```

### Add Node (NEW)
```bash
POST /addNode
Content-Type: application/json
x-user-role: Superadmin

Body:
{
"graphId": "graph_id",
"node": {
"id": "node-unique-id",
"label": "Node Label",
"type": "fulltext",
"color": "#hexcolor",
"info": "Node content...",
"position": { "x": 0, "y": 0 },
"visible": true
}
}

Response: {"ok": true, "nodeId": "...", "newVersion": 6}
```

### Remove Node (NEW)
```bash
POST /removeNode
Content-Type: application/json
x-user-role: Superadmin

Body:
{
"graphId": "graph_id",
"nodeId": "node-to-remove",
"removeEdges": true
}

Response: {"ok": true, "nodeId": "...", "newVersion": 7}
```

### Patch Node
```bash
POST /patchNode
Content-Type: application/json
x-user-role: Superadmin

Body:
{
"graphId": "graph_id",
"nodeId": "node-to-update",
"fields": {
"label": "Updated Label",
"color": "#ff0000"
}
}
```

### OpenAPI Spec
```bash
GET /openapi.json
```

## Benefits

- No need to download entire graph
- Faster operations
- Auto-versioning
- History tracking
- Edge cleanup (removeNode)

References:

https://knowledge.vegvisr.org/openapi.json

Agent Builder App (React + Vite)

ID: node-agent-builder-app Type: fulltext

# Agent Builder App

## Purpose
Standalone React + Vite application for creating and managing custom agents.

## Features
- Visual Tool Builder: Drag-and-drop tool definition interface
- Prompt Editor: Write and test agent system prompts
- Test Sandbox: Run agents in isolated environment
- Agent Catalog: Browse and clone existing agents
- curl Command Tester: Test API endpoints directly
- Knowledge Graph Documentation Generator: Create docs as graph nodes

## Technology Stack
- Framework: React 18 + TypeScript
- Build Tool: Vite
- UI Components: vegvisr-ui-kit
- State Management: Zustand or Jotai
- API Client: fetch with retry logic

## Project Structure
```
agent-builder-app/
├── src/
│ ├── components/
│ │ ├── ToolBuilder.tsx
│ │ ├── PromptEditor.tsx
│ │ ├── AgentTester.tsx
│ │ ├── CurlTester.tsx
│ │ └── GraphDocGenerator.tsx
│ ├── lib/
│ │ ├── agentSDK.ts
│ │ └── graphAPI.ts
│ └── App.tsx
├── package.json
└── vite.config.ts
```

System Flow Diagram

ID: 7643d3ea-f739-42c7-b532-0433dcdb32d8 Type: mermaid-diagram

graph TB
subgraph "User Workspace"
User[👤 User]
end

subgraph "Frontend Applications"
AgentBuilder[Agent Builder App
React + Vite
Port: 5173]
VegvisrFrontend[vegvisr-frontend
Vue 3
Agent SDK Runtime]
AIChatApp[aichat-vegvisr
React
Chat Interface]
end

subgraph "Cloudflare Workers"
KnowledgeWorker[Knowledge Graph Worker
knowledge.vegvisr.org
Graph CRUD + History]
GrokWorker[Grok Worker
grok.vegvisr.org
xAI API Proxy]
OpenAIWorker[OpenAI Worker
openai.vegvisr.org
OpenAI API Proxy]
ClaudeWorker[Claude Worker
anthropic.vegvisr.org
Anthropic API Proxy]
GeminiWorker[Gemini Worker
gemini.vegvisr.org
Google AI Proxy]
AuthWorker[Auth Worker
auth.vegvisr.org
Authentication]
end

subgraph "Data Layer"
D1DB[(D1 Database
vegvisr_org
Graphs + History)]
HTMLKV[(KV: HTML_PAGES
Published HTML)]
BrandKV[(KV: BRAND_CONFIG
Domain Branding)]
ThemeKV[(KV: THEME_STUDIO
Custom Themes)]
end

subgraph "External AI Services"
xAI[xAI / Grok API]
OpenAI[OpenAI API]
Anthropic[Anthropic API]
Google[Google Gemini API]
end

style User fill:#fbbf24
style AgentBuilder fill:#ec4899
style VegvisrFrontend fill:#8b5cf6
style AIChatApp fill:#38bdf8
style KnowledgeWorker fill:#10b981
style D1DB fill:#6366f1
style HTMLKV fill:#6366f1
style BrandKV fill:#6366f1
style ThemeKV fill:#6366f1

C4 Level 1: System Context

ID: node-c4-level1-system-context Type: mermaid-diagram

graph TB
subgraph "Vegvisr Ecosystem"
AgentSDK["Vegvisr Agent SDK

AI-powered knowledge graph platform
with specialized agents for content
creation, theme design, and app building"]
end

ContentCreator["👤 Content Creator

Creates courses, articles,
educational content"]
Developer["👨‍💻 Developer

Builds custom agents,
integrates AI tools"]
EndUser["👥 End Users

Consumes published
content and apps"]
Admin["👑 Administrator

Manages system,
users, permissions"]

OpenAI["🤖 OpenAI

GPT-4, GPT-5,
DALL-E, Whisper"]
Anthropic["🧠 Anthropic

Claude Opus,
Sonnet, Haiku"]
xAI["⚡ xAI

Grok Models
for reasoning"]
Google["🔍 Google AI

Gemini models
multimodal AI"]
Perplexity["🌐 Perplexity

Real-time web
search & research"]

CloudflarePages["☁️ Cloudflare Pages

Static site hosting
for published apps"]
CloudflareWorkers["⚙️ Cloudflare Workers

Edge computing
serverless functions"]
D1Database["💾 Cloudflare D1

Distributed SQL database
for graph storage"]
GitHub["🔧 GitHub

Source code repository
CI/CD deployment"]

style AgentSDK fill:#10b981,stroke:#059669,stroke-width:4px,color:#fff
style ContentCreator fill:#fbbf24,stroke:#f59e0b,stroke-width:2px
style Developer fill:#fbbf24,stroke:#f59e0b,stroke-width:2px
style EndUser fill:#fbbf24,stroke:#f59e0b,stroke-width:2px
style Admin fill:#fbbf24,stroke:#f59e0b,stroke-width:2px
style OpenAI fill:#94a3b8,stroke:#64748b,stroke-width:2px
style Anthropic fill:#94a3b8,stroke:#64748b,stroke-width:2px
style xAI fill:#94a3b8,stroke:#64748b,stroke-width:2px
style Google fill:#94a3b8,stroke:#64748b,stroke-width:2px
style Perplexity fill:#94a3b8,stroke:#64748b,stroke-width:2px
style CloudflarePages fill:#6366f1,stroke:#4f46e5,stroke-width:2px
style CloudflareWorkers fill:#6366f1,stroke:#4f46e5,stroke-width:2px
style D1Database fill:#6366f1,stroke:#4f46e5,stroke-width:2px
style GitHub fill:#6366f1,stroke:#4f46e5,stroke-width:2px

References:

https://c4model.com

Graph Template Recommendations

ID: node-template-recommendations Type: fulltext

# Recommended Templates for Agent SDK Documentation

## 🎯 Essential for Documentation (High Priority)

### 1. FullTextNode
- ID: `94409110-ebce-4c3a-85e2-18a822afd261`
- Use: Detailed technical documentation with markdown support
- Perfect for: API documentation, concept explanations, tutorials
- Tool-enabled: Yes (AI can generate)

### 2. FlowChart
- ID: `0a9c2ce1-d788-4524-957a-59cebe5f0e8c`
- Use: Process flows and decision trees
- Perfect for: Agent workflow diagrams, execution flows, decision logic

### 3. InfoNode
- ID: `768f99e8-7fda-4ff7-a724-68118c167577`
- Use: Structured information with formatting
- Perfect for: Quick reference cards, specification sheets

### 4. NotesNode
- ID: `2e94807d-d3a8-413c-8177-69c7a96fe644`
- Use: Quick insights and annotations
- Perfect for: Implementation notes, gotchas, best practices

## 📊 Architecture & Planning (Medium Priority)

### 5. GanttChart
- ID: `90b649b1-dcf5-4298-8f96-4ecbc61eb60e`
- Use: Project timelines and phases
- Perfect for: Implementation roadmap, release planning

### 6. TimeLine
- ID: `74e137f0-5e08-4efe-a062-c806fa633813`
- Use: Chronological events
- Perfect for: Version history, feature releases
- Tool-enabled: Yes

### 7. QuadrantChart
- ID: `e4b8a869-35c2-4614-b97c-77b26ec4620a`
- Use: 2x2 matrix categorization
- Perfect for: Agent prioritization (complexity vs value)

## 📈 Data Visualization

### 8. MultiLineChart
- ID: `7fef9db6-9eed-4395-a205-3462141a7da2`
- Use: Trend comparisons
- Perfect for: Performance metrics, adoption rates

### 9. HBarChart
- ID: `df39ac91-972c-41d4-9a00-07832f3b5316`
- Use: Horizontal bar comparisons
- Perfect for: Tool usage statistics

## 🎨 Layout & Structure

### 10. HTML Page Node
- ID: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
- Use: Full HTML page examples
- Perfect for: Complete app templates, working examples
- Tool-enabled: Yes

### 11. TitleNode
- ID: `01bd8bf2-428a-43f4-b4d7-42fd75897730`
- Use: Section headers and dividers

## 🎥 Media & Interactive

### 12. YouTube
- ID: `303d26ab-6a71-466b-83fb-bb9a76321b8b`
- Use: Video tutorials and demos
- Tool-enabled: Yes

### 13. Image
- ID: `4c4bea99-3e26-4b30-98b4-4770bdc56ac1`
- Use: Screenshots and diagrams

## 💡 Top 5 for Agent SDK

1. FullTextNode - Core documentation
2. FlowChart - Agent workflows
3. GanttChart - Implementation timeline
4. HTML Page Node - Working examples
5. YouTube - Tutorial videos

## Template Categories Summary

Total Templates: 62

- General: 20 templates (core content types)
- My Apps: 27 templates (user-created apps)
- Layout Templates: 4 templates (FLEXBOX patterns)
- Video: 1 template (YouTube)
- Audio: 2 templates
- Interactive: 3 templates
- Advertisement: 1 template
- Learning Content: 1 template
- Security: 1 template
- Presentation: 1 template
- Visual Elements: 1 template

References:

https://knowledge.vegvisr.org

Claude Agent SDK Full Workshop

ID: node-youtube-agent-sdk-workshop Type: youtube-video

# Claude Agent SDK Full Workshop

Presenter: Thariq Shihipar (Anthropic)
Duration: 1 hour 52 minutes
Event: AI Engineer Summit

## What You Will Learn

This comprehensive workshop covers building autonomous AI agents using Anthropic's Claude Agent SDK, progressing from theoretical foundations to hands-on implementation.

### Topics Covered:

- Agent Loop Pattern: Context → Thought → Action → Observation
- Tool Integration: Bash tool for general computer use
- Safety Considerations: ReadOnly vs ReadWrite file access permissions
- Error Handling: Addressing common challenges like handling stuck states through feedback loops
- Live Coding: Hands-on implementation demonstrations

## About the SDK

The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.

## Perfect For:

- Developers new to AI agents
- Engineers building autonomous systems
- Anyone interested in Claude Code internals
- Teams implementing AI-powered workflows

References:

https://www.classcentral.com/course/youtube-claude-agent-sdk-full-workshop-thariq-shihipar-anthropic-519150
https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk

Claude Agent SDK & Batch API (Anthropic)

ID: node-claude-agent-sdk-official Type: fulltext

# Claude Agent SDK & Batch API

## Overview

These are the official Anthropic tools for building and scaling AI agents powered by Claude.

---

## Claude Agent SDK

### What It Is

The Claude Agent SDK is Anthropic's official framework for building autonomous AI agents that can:
- Make decisions autonomously
- Use tools and external APIs
- Maintain conversation state across interactions
- Work toward complex goals with minimal human intervention

### Key Features

1. Agent Configuration
- Define agent behavior, personality, and instructions
- Set capabilities and constraints
- Configure response styles

2. Custom Tool Integration
- Attach functions agents can call autonomously
- Database queries, API calls, file operations
- External system integrations

3. Session Management
- Maintain context across conversations
- Track agent state and memory
- Handle multi-turn interactions

4. MCP Integration
- Connect to Model Context Protocol servers
- Extend agent capabilities dynamically
- Share tools across agents

5. Permission & Security
- Control what actions agents can perform
- Audit tool usage
- Sandbox dangerous operations

6. Cost Tracking
- Monitor token usage in real-time
- Track API costs per agent/session
- Optimize for budget constraints

### Available In

- Node.js/TypeScript
- Python

### Use Cases

- 🤖 Autonomous assistants - Customer support, data analysis
- 📊 Workflow automation - Multi-step business processes
- 🔧 Tool-using agents - Agents that interact with APIs/databases
- 💬 Interactive chat systems - Context-aware conversational AI

---

## Batch API

### What It Is

The Batch API is Anthropic's solution for cost-effective, large-scale processing of multiple Claude API requests.

### Key Features

1. Cost Optimization
- Up to 50% lower cost vs synchronous API calls
- Ideal for non-urgent, high-volume workloads

2. Asynchronous Processing
- Submit batches of requests
- Process in background
- Retrieve results when ready

3. Webhook Notifications
- Get notified when batch completes
- Handle results programmatically
- Integrate with existing pipelines

4. Flexible Workloads
- Process thousands of documents
- Dataset labeling and classification
- Content generation at scale

### Use Cases

- 📄 Document processing - Analyze thousands of PDFs, contracts, reports
- 🏷️ Dataset labeling - Classify and tag large datasets
- ✍️ Content generation - Generate product descriptions, summaries
- 🔍 Batch analysis - Sentiment analysis, entity extraction

---

## Agent SDK vs Batch API

| Aspect | Agent SDK | Batch API |
|--------|-----------|----------|
| Purpose | Build autonomous agents | Cost-effective batch processing |
| Interaction | Real-time, interactive | Asynchronous, background |
| Decision Making | Autonomous tool use | Processes predefined requests |
| Tool Use | ✅ Yes | ❌ No |
| Best For | Chat, automation, workflows | Large-scale inference |
| Latency | Real-time | Minutes to hours |
| Cost | Standard API pricing | 50% discount |

---

## Combined Usage

You can use both together:

```
Agent SDK Agent
↓
Identifies need for bulk processing
↓
Submits job to Batch API
↓
Waits for webhook notification
↓
Processes results and continues workflow
```

Example: An agent analyzing customer feedback might:
1. Use Agent SDK for real-time interaction
2. Submit 10,000 reviews to Batch API for sentiment analysis
3. Wait for results via webhook
4. Use Agent SDK to summarize findings

---

## Documentation

- Agent SDK: https://platform.anthropic.com/docs/build/agents
- Batch API: https://platform.anthropic.com/docs/build/batch-processing
- API Reference: https://docs.anthropic.com/en/api

---

## Relation to Vegvisr Agent SDK

The Vegvisr Agent SDK builds on these Anthropic primitives to create:
- Knowledge graph-native agents that understand graph structures
- Visual agent builders for non-technical users
- Pre-built agent templates for common tasks
- Graph-aware tools that manipulate knowledge graphs

Vegvisr extends the Claude Agent SDK with domain-specific capabilities for knowledge management.

References:

https://platform.anthropic.com/docs/build/agents
https://platform.anthropic.com/docs/build/batch-processing

Claude Agent SDK & Batch API Architecture

ID: node-claude-sdk-architecture-diagram Type: mermaid-diagram

graph TB
subgraph Anthropic["🏢 Anthropic Platform"]
Claude["🧠 Claude Models
(Opus, Sonnet, Haiku)"]
BatchAPI["📦 Batch API
50% cost reduction
Async processing"]
end

subgraph AgentSDK["🤖 Claude Agent SDK"]
AgentConfig["⚙️ Agent Configuration
Instructions & behavior"]
Tools["🔧 Custom Tools
Functions agents can call"]
Session["💾 Session Management
Context & state"]
MCP["🔌 MCP Integration
Extended capabilities"]
Security["🔒 Permissions & Security
Action controls"]
end

subgraph Developer["👨‍💻 Developer"]
App["📱 Your Application"]
Code["💻 TypeScript/Python Code"]
end

subgraph Combined["🔄 Combined Usage"]
AgentApp["🤖 Agent Application"] -->|Real-time chat| AgentSDK
AgentApp -->|Detects bulk need| Decision{"Need bulk
processing?"}
Decision -->|Yes| SubmitBatch["📤 Submit to Batch API"]
Decision -->|No| AgentSDK
SubmitBatch -->|Process| BatchAPI
BatchAPI -->|Complete| AgentApp
AgentApp -->|Summarize| AgentSDK
end

style Claude fill:#ff9900,stroke:#ff6600,stroke-width:3px
style AgentSDK fill:#7c3aed,stroke:#6d28d9,stroke-width:2px
style BatchAPI fill:#0ea5e9,stroke:#0284c7,stroke-width:2px
style App fill:#10b981,stroke:#059669,stroke-width:2px
style Decision fill:#f59e0b,stroke:#d97706,stroke-width:2px

Agent Builder App (Learning Project)

ID: node-agent-builder-app-new Type: fulltext

# Agent Builder App

## Overview

A learning project to understand how to use AI Agents with the Vegvisr knowledge graph system.

## Purpose

Build a visual agent builder application that demonstrates:

1. Claude Agent SDK Integration
- Creating and configuring AI agents
- Managing agent sessions
- Implementing custom tools

2. Knowledge Graph Integration
- Connecting agents to knowledge graphs
- Using graph data as agent context
- Creating graph-aware agent tools

3. Visual Agent Builder
- UI for agent configuration
- Agent list/management interface
- Template selection
- Tool builder interface

---

## Tech Stack

- React 19 + TypeScript + Vite
- Tailwind CSS v3
- vegvisr-ui-kit (AuthBar, EcosystemNav, LanguageSelector)
- Magic link authentication (cookie.vegvisr.org)
- i18n support

---

## Project Structure

```
Agent-Builder/
├── src/
│ ├── App.tsx # Main application
│ ├── main.tsx # Entry point
│ ├── lib/
│ │ ├── auth.ts # Authentication logic
│ │ ├── i18n.ts # Internationalization
│ │ └── storage.ts # Local storage helpers
│ └── assets/ # Images, logos
├── functions/ # Cloudflare Pages functions
├── package.json
├── vite.config.ts
└── wrangler.toml # Cloudflare config
```

---

## Development Roadmap

### Phase 1: Foundation ✅
- [x] Copy scaffold from my-new-app
- [x] Rename to Agent-Builder
- [x] Initialize git repository
- [x] Add to workspace
- [x] Document in knowledge graph
- [ ] Update app logos and branding
- [ ] Customize i18n for agent builder

### Phase 2: Agent Configuration UI
- [ ] Create agent list view
- [ ] Agent creation form
- [ ] Agent configuration panel
- [ ] Save/load agent configs

### Phase 3: Claude Agent SDK Integration
- [ ] Install @anthropic-ai/sdk
- [ ] Implement agent runner
- [ ] Add tool execution framework
- [ ] Session management

### Phase 4: Knowledge Graph Integration
- [ ] Graph browser component
- [ ] Node selection for context
- [ ] Graph query tools for agents
- [ ] Template-based node creation

### Phase 5: Agent Execution & Monitoring
- [ ] Agent runtime interface
- [ ] Tool call visualization
- [ ] Result display
- [ ] Cost tracking

---

## Quick Start

```bash
cd /Users/torarnehave/Documents/GitHub/Agent-Builder
npm install
npm run dev
```

App runs on: http://localhost:5173

---

## Repository

Location: `/Users/torarnehave/Documents/GitHub/Agent-Builder`

Workspace: `my-test-app.code-workspace`

---

## Learning Goals

1. Understand Agent SDK primitives from Anthropic
2. Integrate agents with knowledge graphs in meaningful ways
3. Build reusable agent templates for common tasks
4. Create visual tools for non-technical agent creation
5. Explore agent autonomy and decision-making patterns

---

## Related Documentation

- [Claude Agent SDK & Batch API (Anthropic)](#node-claude-agent-sdk-official)
- [Claude Agent SDK & Batch API Architecture](#node-claude-sdk-architecture-diagram)
- [Agent SDK Overview](#node-root-overview)

Agent SDK Architecture - Vegvisr

Nodes

Agent SDK Overview

References:

HTML App Builder Agent

Theme Designer Agent

Graph Architect Agent

Knowledge Graph API Endpoints

References:

Agent Builder App (React + Vite)

System Flow Diagram

C4 Level 1: System Context

References:

Graph Template Recommendations

References:

Claude Agent SDK Full Workshop

References:

Claude Agent SDK & Batch API (Anthropic)

References:

Claude Agent SDK & Batch API Architecture

Agent Builder App (Learning Project)

Connections