Skip to content

CLAUDE.md

Latest commit

 

History

History
171 lines (137 loc) · 7.91 KB

CLAUDE.md

File metadata and controls

171 lines (137 loc) · 7.91 KB

CLAUDE.md

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

Project Overview and Developer Documentation

  • @README.md: audience is human developer only - consult only after explicitly asking user

User Guides and How-To Guides

  • @docs/modules/agent-runtime/pages/how-to-guides/install.adoc
  • @docs/modules/agent-runtime/pages/how-to-guides/configure.adoc
  • @docs/modules/agents/pages/how-to-guides/create-template-agent.adoc
  • @docs/modules/agents/pages/how-to-guides/create-custom-image-agent.adoc
  • @docs/modules/agents/pages/how-to-guides/propagate-headers.adoc
  • @docs/modules/agents/pages/how-to-guides/delegate-to-subagent.adoc
  • @docs/modules/agents/pages/how-to-guides/create-workforce.adoc
  • @docs/modules/tool-servers/pages/how-to-guide.adoc
  • @docs/modules/tool-routes/pages/how-to-guide.adoc
  • @docs/modules/tool-gateways/pages/how-to-guide.adoc
  • @docs/modules/agent-gateways/pages/how-to-guide.adoc
  • @docs/modules/ai-gateways/pages/how-to-guide.adoc
  • @docs/modules/guardrails/pages/how-to-guide.adoc

Reference Documentation

  • @docs/modules/agent-runtime/pages/reference.adoc
  • @docs/modules/agents/pages/reference.adoc
  • @docs/modules/tool-servers/pages/reference.adoc
  • @docs/modules/tool-routes/pages/reference.adoc
  • @docs/modules/tool-gateways/pages/reference.adoc
  • @docs/modules/agent-gateways/pages/reference.adoc
  • @docs/modules/ai-gateways/pages/reference.adoc
  • @docs/modules/guardrails/pages/reference.adoc

Explanation Pages

  • @docs/modules/agent-gateways/pages/explanation.adoc
  • @docs/modules/ai-gateways/pages/explanation.adoc
  • @docs/modules/tool-gateways/pages/explanation.adoc
  • @docs/modules/guardrails/pages/explanation.adoc
  • Overall Agentic Layer Architecture: https://docs.agentic-layer.ai/architecture/main/index.html

Documentation in AsciiDoc format is located in the docs/ directory. This folder is hosted as a separate documentation site.

Essential Commands

🚨 After modifying CRD structs (api/v1alpha1/*.go): run make manifests && make generate

Adding new CRD: operator-sdk create api --group runtime --version v1alpha1 --kind NewResource --resource --controller

Adding webhook: operator-sdk create webhook --group runtime --version v1alpha1 --kind NewResource --defaulting --programmatic-validation

Running tests: make lint, make test, make test-e2e: runs the e2e tests. These should only be run as a final validation, since they take very long.

Architecture

Core Components

  • Agent CRD (api/v1alpha1/agent_types.go): Defines the Agent custom resource with:

    • Framework specification (google-adk, custom)
    • Container image and replica configuration
    • Protocol definitions (A2A, OpenAI)
    • Status tracking with conditions

  • AgentGateway CRD (api/v1alpha1/agentgateway_types.go): Defines the AgentGateway custom resource for exposing agents via a unified gateway:

    • Gateway provider abstraction (KrakenD, Envoy, Nginx)
    • Routing strategies (path-based, subdomain-based)
    • IAP (Identity-Aware Proxy) integration for security
    • TLS configuration and certificate management
    • Agent reference and selective exposure controls

  • ToolServer CRD (api/v1alpha1/toolserver_types.go): Defines the ToolServer custom resource for managing tool servers:

    • Protocol specification (mcp for Model Context Protocol)
    • Transport type configuration (http, sse)
    • Container image and replica configuration
    • Environment variable configuration
    • Status tracking with conditions and service URL

  • ToolRoute CRD (api/v1alpha1/toolroute_types.go): Defines the ToolRoute custom resource for per-consumer exposure of tool servers through a ToolGateway:

    • Upstream reference (cluster ToolServer or external URL)
    • Tool filter (name + glob allow/deny)
    • Status URL populated by the gateway implementation operator
    • Not reconciled by agent-runtime-operator — each tool-gateway implementation owns its reconciliation

  • Agent Controller (internal/controller/agent_controller.go): Reconciles Agent resources by:

    • Creating Kubernetes Deployments for agent workloads
    • Managing Services for protocol exposure
    • Protocol-aware health checking: Automatically generates appropriate readiness probes
      • A2A agents: HTTP GET with configurable paths (validates agent functionality)
      • OpenAI agents: TCP socket probe (validates service availability)
      • Priority: A2A > OpenAI > No probe
      • No protocols: No readiness probe
    • Handling framework-specific configurations

  • ToolServer Controller (internal/controller/toolserver_controller.go): Reconciles ToolServer resources by:

    • Transport-aware deployment: http/sse: Creates Deployments and Services for standalone tool servers
    • Managing TCP-based health probes for http/sse transports
    • Populating status URL for service discovery
    • Handling environment variable configuration

  • Admission Webhooks (internal/webhook/v1alpha1/): Provides validation and mutation for Agent and ToolServer resources

Project Structure

├── api/                  # CRD definitions and types
├── cmd/main.go           # Operator entry point
├── config/               # Kubernetes manifests and Kustomize configs
│   ├── crd/              # Custom Resource Definitions
│   ├── rbac/             # Role-based access control
│   ├── manager/          # Operator deployment
│   ├── webhook/          # Webhook configurations
│   └── samples/          # Example resources
├── docs/                 # AsciiDoc documentation
├── internal/
│   ├── controller/       # Reconciliation logic
│   └── webhook/          # Admission webhook handlers
└── test/
    ├── e2e/              # End-to-end tests
    └── utils/            # Test utilities

Testing Strategy

The project uses a three-tier testing approach, prioritized from simplest to most complex:

1. Unit Tests

  • Purpose: Test isolated logic without external dependencies
  • Framework: Standard Go testing, no extra frameworks
  • Location: Next to implementation files (e.g., *_test.go files)
  • When to use: When logic can be tested without Kubernetes API or complex setup
  • Example: Helper functions, data transformations, validation logic

2. Integration Tests

  • Purpose: Test controller/webhook logic with Kubernetes API interactions
  • Framework: envtest (provides Kubernetes API without a real cluster)
  • Location: Next to implementation classes (e.g., internal/controller/*_test.go)
  • When to use: When testing requires Kubernetes API but not a full cluster
  • Example: Controller reconciliation logic, webhook validation, resource creation

3. End-to-End (E2E) Tests

  • Purpose: Blackbox testing of complete workflows
  • Framework: Real Kind cluster with full operator deployment
  • Location: test/e2e/
  • When to use: Verify complete user workflows work end-to-end
  • Example: Agent deployment, workforce discovery, tool server integration

Testing Principles

  1. Avoid duplication: Don't cover unit-tested logic in integration tests
  2. Prefer simpler tests: Unit test > Integration test > E2E test
  3. Prefer real APIs over mocking: Use envtest integration tests instead of extensive mocking
  4. E2E tests are blackbox: Implementation details should be tested in unit/integration tests

Update Policy

Updates to this CLAUDE.md should be rare. Trigger a CLAUDE.md update suggestion when:

Essential Commands:

  • New critical make targets or operator-sdk commands needed for development
  • Command syntax changes

Architecture:

  • New CRDs or controllers added
  • Significant behavior changes to existing components

Project Structure:

  • Major directory reorganization

Testing Strategy:

  • Testing approach or framework changes