Skip to content

CLAUDE.md

Latest commit

 

History

History
708 lines (561 loc) · 25.7 KB

CLAUDE.md

File metadata and controls

708 lines (561 loc) · 25.7 KB
Raw

CLAUDE.md

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

Project Overview

AgentShip is a production-ready framework for building, deploying, and operating AI agents. Built on Google ADK and LangGraph, it provides REST API, session management, observability, streaming, and deployment tools.

Key Technologies:

  • Python 3.13+ with pipenv for dependency management
  • FastAPI (REST API server on port 7001)
  • Google ADK & LangGraph (dual execution engines)
  • PostgreSQL (session storage)
  • LiteLLM (multi-provider LLM support)
  • Docker & Docker Compose (containerization)
  • OPIK (observability)
  • MCP (Model Context Protocol for tool integration)
  • Auto Tool Documentation (automatic prompt generation from schemas)

Commands

Docker Development (Recommended)

make docker-setup    # First-time setup (creates .env, builds, starts containers)
make docker-up       # Start containers (API: localhost:7001)
make docker-down     # Stop containers
make docker-restart  # Quick restart
make docker-reload   # Hard reload (rebuild + restart)
make docker-logs     # View logs

Ports:

  • API/Swagger/Docs/AgentShip Studio: localhost:7001
  • PostgreSQL (external): localhost:5433 (inside Docker: postgres:5432)

Local Development (No Docker)

make dev             # Start dev server (localhost:7001)
pipenv run uvicorn src.service.main:app --reload --host 0.0.0.0 --port 7001

Testing

make test            # Run all tests
make test-cov        # Run tests with coverage report
pipenv run pytest tests/ -v
pipenv run pytest tests/unit/ -v           # Unit tests only
pipenv run pytest tests/integration/ -v    # Integration tests only
pipenv run pytest tests/unit/test_file.py -v  # Single test file

Code Quality

make lint            # Run flake8 linter
make format          # Format code with black
make type-check      # Run mypy type checking

Documentation

make docs-build      # Build Sphinx documentation
make docs-serve      # Build docs + start server (localhost:7001/docs)

Deployment

make heroku-deploy   # Deploy to Heroku (one command)

Utilities

make clean           # Clean caches (__pycache__, .pytest_cache, etc.)
pipenv install       # Install production dependencies
pipenv install --dev # Install development dependencies

Architecture

Directory Structure

src/
├── agent_framework/      # Core framework (engines, tools, sessions, config)
│   ├── configs/          # Agent & LLM configuration loaders
│   ├── core/             # BaseAgent, I/O, types
│   ├── engines/          # ADK & LangGraph execution engines
│   │   ├── adk/          # Google ADK engine
│   │   └── langgraph/    # LangGraph engine with LiteLLM
│   ├── factories/        # Engine, memory, observability, tool factories
│   ├── mcp/              # MCP (Model Control Plane) integration
│   ├── middleware/       # Middleware system
│   ├── observability/    # OPIK observability integration
│   ├── registry/         # Agent discovery and registration
│   ├── session/          # Session storage (ADK, LangGraph adapters)
│   ├── tools/            # Tool system (adapters, base tool, domains)
│   └── utils/            # Utilities (path, PDF, Azure)
├── all_agents/           # Agent implementations (auto-discovered)
│   ├── base_agent.py     # Public import surface (BaseAgent, AgentType)
│   ├── single_agent_pattern/
│   ├── orchestrator_pattern/
│   ├── tool_pattern/
│   └── ...
├── service/              # FastAPI REST API layer
│   ├── main.py           # FastAPI app + routes
│   └── routers/          # API routers (REST, SSE, WebSocket)
└── log_settings.py       # Logging configuration

tests/
├── unit/                 # Unit tests
└── integration/          # Integration tests

debug_ui/                 # AgentShip Studio (localhost:7001/studio)
docs_sphinx/              # Sphinx documentation source
agent_store_deploy/       # Database setup scripts
service_cloud_deploy/     # Heroku deployment scripts

Core Concepts

1. Agent Definition (YAML + Python)

Agents are defined using two files:

  • main_agent.yaml: Configuration (LLM, temperature, instructions, tools, MCP)
  • main_agent.py: Python class inheriting from BaseAgent

Example: Creating a New Agent

# 1. Create directory
mkdir -p src/all_agents/my_agent

# 2. Create main_agent.yaml
cat > src/all_agents/my_agent/main_agent.yaml << EOF
agent_name: my_agent
llm_provider_name: openai
llm_model: gpt-4o
temperature: 0.4
execution_engine: adk  # or langgraph
streaming_mode: none   # or token_by_token
description: My helpful assistant
instruction_template: |
  You are a helpful assistant.
EOF

# 3. Create main_agent.py
cat > src/all_agents/my_agent/main_agent.py << EOF
from src.all_agents.base_agent import BaseAgent
from src.service.models.base_models import TextInput, TextOutput
from src.agent_framework.utils.path_utils import resolve_config_path

class MyAgent(BaseAgent):
    def __init__(self):
        super().__init__(
            config_path=resolve_config_path(relative_to=__file__),
            input_schema=TextInput,
            output_schema=TextOutput
        )
EOF

Agents are auto-discovered on server restart (no manual registration needed).

2. Execution Engines

AgentShip supports two pluggable engines:

  • ADK Engine (execution_engine: adk): Google ADK-based execution
  • LangGraph Engine (execution_engine: langgraph): LangGraph with LiteLLM, supports token-by-token streaming

Set execution_engine in YAML. Default is adk.

3. Agent Discovery

  • Agents in src/all_agents/ are auto-discovered at startup
  • Discovery looks for classes inheriting from BaseAgent
  • Registry key = agent_name from main_agent.yaml (not class name or directory name)
  • Only main_agent.yaml files create discoverable agents; sub-agent YAMLs in orchestrator dirs are not independently registered
  • Registry: src/agent_framework/registry/discovery.py

4. Session Storage

  • Docker: PostgreSQL at postgres:5432 (container), localhost:5433 (host)
  • Local: PostgreSQL at localhost:5432
  • Database name: agentship_session_store
  • Adapters: ADK (session/adapters/adk.py), LangGraph (session/adapters/langgraph.py)

5. Tools & MCP Integration

  • Tools can be defined in YAML (tools: section) or Python
  • MCP Integration: Full Model Context Protocol support for both ADK and LangGraph
  • MCP Configuration:
    • Global: .mcp.settings.json (JSON format compatible with Cursor IDE)
    • Per-agent: mcp.servers in YAML
  • Tool adapters for ADK and LangGraph in src/agent_framework/tools/adapters/
  • MCP adapters: src/agent_framework/mcp/adapters/ (ADK and LangGraph)
  • Tool discovery: src/agent_framework/mcp/tool_discovery.py
  • Auto Tool Documentation: Schemas automatically generate LLM prompts (src/agent_framework/prompts/tool_documentation.py)

6. Observability

  • OPIK integration for monitoring and evaluation
  • Configured via environment variables
  • Adapters for ADK and LangGraph in src/agent_framework/observability/opik/adapters/

MCP Integration

AgentShip has production-ready MCP (Model Context Protocol) support for both ADK and LangGraph engines.

Features

  • ✅ STDIO Transport - Connect to local MCP servers via stdin/stdout
  • ✅ HTTP/OAuth Transport - Connect to remote services (GitHub, Slack) via OAuth 2.0
  • ✅ Auto Tool Discovery - Tools discovered automatically from MCP servers
  • ✅ Auto Documentation - Tool schemas → LLM prompts (zero manual work)
  • ✅ Dual Engine Support - Works with both ADK and LangGraph
  • ✅ Per-Agent Client Isolation - OAuth servers get separate client per agent
  • ✅ Env Var Resolution - ${VAR} tokens in command args resolved at load time
  • ✅ Event Loop Safe - Automatic reconnection when event loop changes
  • ✅ Configuration-First - Define servers in JSON or YAML

Transport Types

Transport Client Class Use Case Auth
stdio StdioMCPClient Local servers (npx, Python) Env vars
http/sse SSEMCPClient Remote APIs OAuth 2.0 (requires AGENTSHIP_AUTH_DB_URI)

Architecture

Agent YAML
    ↓
MCP Registry (.mcp.settings.json)
    ↓
MCPClientManager (singleton, per-agent cache)
    ↓
StdioMCPClient / SSEMCPClient
    ↓
Tool Discovery (fetches tool schemas)
    ↓
Tool Adapters (ADK or LangGraph)
    ↓
Tool Documentation Generator (extracts schemas)
    ↓
Prompt Builder (injects into system prompt)
    ↓
Agent uses tools (MCP calls handled automatically)

Per-Agent Client Isolation

STDIO servers are shared (all agents share one client). OAuth/HTTP servers are isolated per agent to prevent token cross-contamination:

# STDIO: shared client (safe to share)
client = manager.get_client(postgres_config)

# HTTP/OAuth: per-agent client
client = manager.get_client(github_config, owner="my_agent")

Cache key: "{server_id}" for shared, "{server_id}:{agent_name}" for per-agent.

Configuration

Global Config (.mcp.settings.json):

{
  "servers": {
    "postgres": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${AGENT_SESSION_STORE_URI}"
      ]
    },
    "github": {
      "transport": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "auth": {
        "type": "oauth",
        "provider": "github",
        "client_id_env": "GITHUB_OAUTH_CLIENT_ID",
        "client_secret_env": "GITHUB_OAUTH_CLIENT_SECRET",
        "authorize_url": "https://github.com/login/oauth/authorize",
        "token_url": "https://github.com/login/oauth/access_token",
        "scopes": ["repo"]
      }
    }
  }
}

Agent YAML:

agent_name: database_agent
execution_engine: adk  # or langgraph - both work!

mcp:
  servers:
    - postgres   # STDIO: shared client
    - github     # HTTP/OAuth: per-agent client

Auto Tool Documentation

Tool schemas are automatically converted to LLM-friendly documentation:

Tool Schema (from MCP):

{
  "name": "query",
  "description": "Execute SQL query",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sql": {"type": "string", "description": "SQL query to execute"}
    },
    "required": ["sql"]
  }
}

Generated Documentation (injected into prompt):

## Available Tools

### query
**Description:** Execute SQL query
**Parameters:**
- `sql` (string, **required**): SQL query to execute

**Example:**
```json
{"sql": "SELECT * FROM table"}

This is **automatically injected** into the agent's system prompt. No manual work needed!

### Key Files

- **Registry**: `src/agent_framework/mcp/registry.py` - MCP server configuration, env var resolution
- **Client Manager**: `src/agent_framework/mcp/client_manager.py` - Singleton, per-agent cache
- **STDIO Client**: `src/agent_framework/mcp/clients/stdio.py` - Process spawning
- **SSE Client**: `src/agent_framework/mcp/clients/sse.py` - HTTP/OAuth transport
- **Tool Discovery**: `src/agent_framework/mcp/tool_discovery.py` - Schema fetching
- **ADK Adapter**: `src/agent_framework/mcp/adapters/adk.py` - ADK tool wrapper
- **LangGraph Adapter**: `src/agent_framework/mcp/adapters/langgraph.py` - LangGraph wrapper
- **Tool Doc Generator**: `src/agent_framework/prompts/tool_documentation.py` - Schema → prompt
- **Tool Manager**: `src/agent_framework/tools/tool_manager.py` - Unified tool creation
- **Token Encryption**: `src/agent_framework/mcp/token_encryption.py` - OAuth token storage
- **DB Operations**: `src/agent_framework/mcp/db_operations.py` - CRUD for OAuth tokens
- **CLI**: `src/cli/` - `agentship mcp connect/list-connections/disconnect`

### Event Loop Handling

MCP clients detect event loop changes and automatically reconnect:

```python
# Agent initialization (one event loop)
agent = PostgresMcpAgent()

# Web request (different event loop)
result = await agent.chat(request)  # ✅ Auto-reconnects!

Logs show:

[WARNING] Event loop changed for postgres, reconnecting...
[INFO] Connecting to STDIO MCP server postgres...
[INFO] MCP STDIO client connected and initialized

This is normal and expected in production web servers.

Available MCP Servers

AgentShip works with any MCP server:

  • PostgreSQL - @modelcontextprotocol/server-postgres
  • Filesystem - @modelcontextprotocol/server-filesystem
  • GitHub - @modelcontextprotocol/server-github
  • Google Drive - @modelcontextprotocol/server-gdrive
  • Brave Search - @modelcontextprotocol/server-brave-search

See MCP Servers for full list.

Testing MCP Integration

# Unit tests (no external deps)
pipenv run pytest tests/unit/agent_framework/test_mcp/ -v

# Integration tests
pipenv run pytest tests/integration/test_mcp_infrastructure.py -v  # no external deps
pipenv run pytest tests/integration/test_mcp_http_agents.py -v     # no external deps
pipenv run pytest tests/integration/test_mcp_stdio_agents.py -v    # requires Docker postgres

Example Agents

  • src/all_agents/postgres_mcp_agent/ — STDIO transport example
  • src/all_agents/github_adk_mcp_agent/ — HTTP/OAuth transport, ADK engine
  • src/all_agents/github_langgraph_mcp_agent/ — HTTP/OAuth transport, LangGraph engine

Long-Term Memory

AgentShip ships pluggable long-term memory that lets an agent recall facts about a user across sessions — separate from the per-session conversation history kept by the engine's checkpointer.

Features

  • ✅ Cross-session recall — facts said in session A surface in session B for the same user_id.
  • ✅ Engine-agnostic — works identically on ADK and LangGraph via MiddlewareEngine.
  • ✅ Zero-touch opt-in — turn it on with a YAML block; no Python changes to the agent.
  • ✅ Off the hot path — writes default to fire-and-forget so the user never waits on storage.
  • ✅ Trust-aware injection — recalled memories are framed as context, not instructions, before being added to the system prompt.
  • ✅ Privacy — per-user_id scope; DELETE /api/agents/memories hard-deletes a user's data.

Currently supported backend

  • Mem0 Platform (mem0_platform) — Mem0's hosted SaaS. Set AGENT_LTM_MEM0_PLATFORM_API_KEY in .env.

Additional backends (Mem0 OSS, native pgvector, Vertex AI Memory Bank) are sketched in agent-ship/.spec-dev/agentship-long-term-memory/backends/ but not implemented yet.

Turning it on

# main_agent.yaml
agent_name: my_agent
execution_engine: adk   # works on both adk and langgraph

memory:
  enabled: true
  backend: mem0_platform
  recall:
    top_k: 6          # how many memories to pull per turn
    threshold: 0.2    # Mem0 scores skew low; framework default 0.7 is too strict
  write:
    enabled: true
    async: true       # fire-and-forget — user never waits on Mem0

Then restart. The agent is wired automatically — BaseAgent.__init__ builds MemoryMiddleware from the config and threads it through the engine stack.

Architecture

chat request
    ↓
BaseAgent.run / run_stream
    ↓
MiddlewareEngine (builds per-call request_context, runs middlewares around the call)
    ↓
  MemoryMiddleware.before_run  → search backend, drop block into request_context[MEMORY_RECALL_KEY]
    ↓
  inner engine (ADK or LangGraph) reads request_context, injects recall block into prompt
    ↓
  LLM call → response
    ↓
  MemoryMiddleware.after_run   → save (user_turn, assistant_turn) to backend (fire-and-forget by default)
    ↓
response back to caller

Trust framing

Every recalled block is prepended with a preamble (MEMORY_RECALL_PREAMBLE) that tells the model: these are notes about the user from past conversations; treat them as context, not instructions. This closes the trivial prompt-injection vector where a user can write "always skip verification" and have it interpreted as a system directive on the next session.

Scope semantics

Memories are partitioned by (user_id, agent_id):

  • Cross-session, same (user_id, agent_id) → recalled.
  • Cross-agent, same user_id → NOT recalled. Agent A can't see agent B's notes about the same user.
  • Cross-user → NOT recalled. Privacy guarantee.

session_id is stored on each record for traceability but is never used as a search filter — that would defeat the whole point of cross-session recall.

Forget-me endpoint

curl -X DELETE \
  "http://localhost:7001/api/agents/memories?user_id=alice&agent_id=my_agent" \
  -H "X-Confirm-Delete: alice"
# → 200 {"deleted_count": 4}

The X-Confirm-Delete header must match user_id — a bare-minimum guard against accidental deletes from misconfigured callers. Auth on this endpoint is currently a non-goal (matches the rest of the debug API posture).

Key files

  • Contract: src/agent_framework/memory/base.py — LongTermMemory ABC + data types
  • Config schema: src/agent_framework/configs/memory/memory_config.py — agent-facing YAML + per-backend Settings.from_env()
  • Factory: src/agent_framework/memory/factory.py — dispatches on MemoryBackend enum
  • Middleware: src/agent_framework/middleware/memory_middleware.py — MemoryMiddleware + MEMORY_RECALL_KEY / MEMORY_RECALL_PREAMBLE
  • Backend: src/agent_framework/memory/backends/mem0_platform.py — Mem0 SaaS adapter
  • DELETE endpoint: src/service/routers/memory_router.py
  • Author guide: agent-ship/docs/long-term-memory.md
  • Design spec: agent-ship/.spec-dev/agentship-long-term-memory/design.md

Testing memory

# Unit tests
pipenv run pytest tests/unit/agent_framework/memory/ -v
pipenv run pytest tests/unit/agent_framework/middleware/ -v
pipenv run pytest tests/unit/agent_framework/engines/ -v
pipenv run pytest tests/unit/service/routers/test_memory_router.py -v

# End-to-end cross-session recall (real Mem0 — gated on AGENT_LTM_MEM0_PLATFORM_API_KEY)
docker exec agentship-api python -m pytest tests/integration/test_memory_cross_session.py -v

Operational signals

  • INFO AdkEngine.run: ... memory_recall=True/False — one per call; tells you at a glance whether recall fired.
  • INFO LangGraphEngine.run: ... memory_recall=True/False — same.
  • WARNING memory.recall.failed / memory.write.failed — backend errors are swallowed (graceful degrade) but always logged.
  • At DEBUG level: per-skip reasons, per-write outcomes, recall hit counts (memory.recall.hit found=N injected_chars=M).

Environment Configuration

Copy env.example to .env and configure:

Required:

  • At least one LLM API key: OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY

Optional:

  • AGENT_SESSION_STORE_URI: PostgreSQL connection string
  • AGENT_SHORT_TERM_MEMORY: Session storage type (Database or InMemory)
  • LOG_LEVEL: Logging level (INFO, DEBUG)
  • ENVIRONMENT: Environment name (local, docker, production)

Docker Networking:

  • Docker containers use postgres:5432 (service name)
  • Local development uses localhost:5432
  • docker-compose.yml automatically overrides AGENT_SESSION_STORE_URI for Docker

Agent Patterns

The repository includes example patterns:

  1. Single Agent (single_agent_pattern/): Simple one-agent flow
  2. Orchestrator (orchestrator_pattern/): Main agent + sub-agents (flight, hotel, summary)
  3. Tool Pattern (tool_pattern/): Agent with custom tools
  4. File Analysis (file_analysis_agent/): PDF/document analysis
  5. MCP Demo (mcp_demo_agent/): MCP integration example

Testing Guidelines

  • Use pipenv run pytest (not bare pytest)
  • Tests marked with @pytest.mark.unit or @pytest.mark.integration
  • Async tests supported (asyncio_mode = auto in pytest.ini)
  • Coverage reports in htmlcov/index.html
  • Test structure mirrors src/ structure

Integration Test Fixtures (tests/integration/conftest.py)

  • project_root_cwd() — context manager, required when calling discover_agents("src/all_agents")
  • reset_mcp_singletons — autouse, resets MCPClientManager and MCPServerRegistry between tests
  • reset_agent_instance_cache — autouse, clears the agent registry singleton
  • mock_langgraph_llm(response_text) — patches src.agent_framework.engines.langgraph.engine.acompletion
  • require_postgres() — returns pytest.mark.skipif when AGENT_SESSION_STORE_URI is not set

Key Test Patterns

# ADK engine access (MiddlewareEngine wraps actual engine)
agent.engine._inner.runner  # NOT agent.engine.runner

# LangGraph LLM mock
with mock_langgraph_llm("response text"):
    events = [e async for e in agent.chat_stream(request)]

# MCP singletons reset between tests
MCPClientManager.reset_instance()
MCPServerRegistry._instance = None

API Endpoints

When server is running (port 7001):

AgentShip Studio Debug API (/api/debug/)

Method Path Description
GET /api/debug/agents List all registered agents with schemas
GET /api/debug/agents/{name}/schema Input/output schema for an agent
GET /api/debug/agents/{name}/config Engine, model, provider, streaming mode
POST /api/debug/chat Non-streaming chat (returns full response)
POST /api/debug/chat/stream SSE streaming chat (thinking, content, tool_call, tool_result, done)
POST /api/debug/feedback Record thumbs up/down feedback
GET /api/debug/sessions List sessions
POST /api/debug/sessions Create session
DELETE /api/debug/sessions/{id} Delete session

Database Environments

Environment Command Database Access
Docker make docker-up agentship_session_store postgres:5432 (container), localhost:5433 (host)
Local make dev agentship_session_store localhost:5432
Heroku Auto-provisioned Heroku PostgreSQL DATABASE_URL env var

Important: Docker and local use separate databases. Data does not sync.

Development Workflow

  1. Start Development

    • Docker: make docker-setup (first time), then make docker-up
    • Local: make dev

  2. Create New Agent

    • Create directory in src/all_agents/my_new_agent/
    • Add main_agent.yaml and main_agent.py
    • Restart server (auto-discovery)

  3. Test Agent

  4. Run Tests

    • make test or pipenv run pytest tests/ -v

  5. Code Quality

    • Format: make format
    • Lint: make lint
    • Type check: make type-check

Important Notes

  • Agent auto-discovery: Agents in src/all_agents/ are automatically discovered on server start
  • Hot-reload: Code changes auto-reload in Docker (docker-compose.yml mounts src/)
  • Python version: Requires Python 3.13+ (see runtime.txt)
  • Dependency management: Uses pipenv (not pip directly)
  • MCP integration:
    • Works with both ADK and LangGraph engines
    • Configure servers in .mcp.settings.json (global) or agent YAML (per-agent)
    • Tool documentation auto-generated from schemas
    • Event loop safe (auto-reconnects when needed)
    • STDIO transport (local npx/Python) and HTTP/OAuth transport (GitHub, Slack, etc.) both supported
  • Auto Tool Documentation:
    • Tool schemas are single source of truth
    • Documentation auto-generated and injected into prompts
    • Works for all tool types (functions, MCP tools, agent tools)
    • Zero maintenance required
  • Streaming: LangGraph engine supports token-by-token streaming (streaming_mode: token_based)
  • Observability: OPIK integration available for both ADK and LangGraph engines
  • Memory optimization: Target is 512MB memory limit (see health check endpoint)

Common Patterns

Import BaseAgent

from src.all_agents.base_agent import BaseAgent, AgentType

Resolve Config Path

from src.agent_framework.utils.path_utils import resolve_config_path

config_path=resolve_config_path(relative_to=__file__)

Custom Input/Output Schemas

from pydantic import BaseModel

class CustomInput(BaseModel):
    field1: str
    field2: int

class CustomOutput(BaseModel):
    result: str

Access Agent Config

# In BaseAgent subclass
self.agent_config.agent_name
self.agent_config.llm_model
self.agent_config.temperature

Claude Code Skills

Project-level skills live in .claude/commands/ and are available to anyone who opens this repo in Claude Code.

Skill Invoke What it does
/new-agent /new-agent weather_agent Scaffolds a new agent (YAML + Python) with prompts for engine, model, instruction
/add-mcp /add-mcp postgres Adds an MCP server to .mcp.settings.json and wires it to an agent
/run-tests /run-tests unit Runs the right tests for changed code with correct flags
/studio /studio Reference for Studio URLs, debug API endpoints, and troubleshooting

Debugging

  • Logs: Check dev_app.log or make docker-logs
  • AgentShip Studio: http://localhost:7001/studio for interactive testing
  • Health check: http://localhost:7001/health shows memory usage
  • PostgreSQL: Connect with psql -h localhost -p 5433 -U agentship_user -d agentship_session_store (Docker) or port 5432 (local)