agentgram CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Agentgram is a unified interface for interacting with multiple AI agents. The system consists of:

• API (Go): Multiplexer that connects to remote agents, handles authentication (Keycloak JWT), permissions (Google Workspace groups/users), and emits AG-UI protocol events
• Web (Next.js + SSE/AG-UI): User interface for chatting with agents

Repository Structure

agentgram/
├── api/              # Go API (multiplexer)
│   ├── cmd/server/   # Entry point
│   ├── internal/     # Core packages
│   ├── configs/      # YAML configuration
│   ├── docker/       # Docker compose for dev environment
│   └── test/         # Mock agent and test frontend
├── web/              # Next.js web with SSE/AG-UI
└── Makefile          # Root commands

Quick Start

# Full environment with Docker (api + mock agents + test frontend)
make docker-up

# Or run separately:
make api              # Terminal 1: Go API on :8080
make web              # Terminal 2: Next.js on :3000

Architecture

┌──────────────────────┐     ┌─────────────────────┐     ┌─────────────────┐
│        Web           │────>│        API          │────>│  Agent (Custom) │
│  (Next.js+SSE/AG-UI)│<────│   (Go Multiplexer)  │<────│  SSE or JSON    │
└──────────────────────┘     │                     │     └─────────────────┘
         ↑                   │  - JWT Auth         │     ┌─────────────────┐
    AG-UI Events             │  - Permissions      │────>│  Agent (A2A)    │
                             │  - AG-UI Response   │<────│  JSON-RPC       │
                             │  - Session Store    │     └─────────────────┘
                             └─────────────────────┘

Key Design Decisions

1. AG-UI Protocol: API emits AG-UI events (RUN_STARTED, TEXT_MESSAGE_*, RUN_FINISHED) that SSE/AG-UI consumes directly
2. Protocol Abstraction: Web doesn't know if agent uses REST or A2A - API handles conversion
3. Sessions in Redis: The API manages sessions directly via store.SessionStore (Redis); agents are stateless with respect to sessions
4. Permission Model: Access controlled by Google Workspace groups + individual users per agent
5. Configuration: Bootstrap and secret-bearing configuration lives in YAML with ${ENV:VAR} syntax; operational settings that admins can tune at runtime live in the runtime_config database table
6. Security Layers: Security headers, body size limits, JWT audience+nonce validation, rate limiting, sanitized error responses