adding-env-variables

環境変数の追加ガイド

Inkeep Agent Framework に新しい環境変数を追加するための包括的なガイダンスです。すべてのパッケージで一貫性、ドキュメント、型安全性を確保します。

---

CI によるチェック

環境変数の説明は CI によってチェックされます。 check:env-descriptions スクリプトは CI で実行され、env.ts ファイル内の変数に .describe() の呼び出しがない場合は失敗します。

ローカルでチェックするには、次を実行します。

pnpm check:env-descriptions

---

環境変数の構成

このフレームワークでは、複数の env.ts ファイルで定義された環境変数を使用します。

パッケージ	ファイル	用途
agents-api	agents-api/src/env.ts	メイン API サーバーの設定
agents-core	packages/agents-core/src/env.ts	共有コア設定
agents-cli	agents-cli/src/env.ts	CLI ツールの設定

注意： 次のファイルは自動生成されるため、編集しないでください。

• packages/agents-mcp/src/lib/env.ts（Speakeasy によって生成）

---

環境変数を追加するために必要な手順

手順 1：.env.example に追加する

場所：.env.example（リポジトリのルート）

説明的なコメントを付けて変数を追加します。

# ============ SECTION NAME ============
# Description of what this variable does
# Additional context if needed (e.g., where to get API keys)
MY_NEW_VARIABLE=default-value-or-empty

例：

# ============ AI PROVIDERS ============
# Required for agent execution
# Get your API keys from:
# Anthropic: https://console.anthropic.com/
# OpenAI: https://platform.openai.com/
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

手順 2：該当する env.ts ファイルに追加する

.env.example のコメントと一致する .describe() 呼び出しを付けて、Zod スキーマに変数を追加します。

const envSchema = z.object({
  // ... existing variables ...

  MY_NEW_VARIABLE: z
    .string()
    .optional()
    .describe('Description of what this variable does'),
});

手順 3：説明の要件

すべての環境変数に、明確で簡潔な説明を含む .describe() 呼び出しを必ず追加してください。 説明では次の点を満たす必要があります。

1. 変数の用途を説明する
2. .env.example のコメントと一致する
3. 役立つ補足情報（API キーの取得先、デフォルトの動作など）を含める

適切な説明の例：

// AI Provider keys
ANTHROPIC_API_KEY: z
  .string()
  .describe('Anthropic API key for Claude models (required for agent execution). Get from https://console.anthropic.com/'),

// Database configuration
INKEEP_AGENTS_MANAGE_DATABASE_URL: z
  .string()
  .describe('PostgreSQL connection URL for the management database (Doltgres with Git version control)'),

// Authentication
BETTER_AUTH_SECRET: z
  .string()
  .optional()
  .describe('Secret key for Better Auth session encryption (change in production)'),

// Feature flags
LANGFUSE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable Langfuse LLM observability (set to "true" to enable)'),

---

Zod スキーマのパターン

必須の変数

MY_REQUIRED_VAR: z
  .string()
  .describe('This variable is required for the application to function'),

オプションの変数

MY_OPTIONAL_VAR: z
  .string()
  .optional()
  .describe('Optional configuration for feature X'),

デフォルト値を持つ変数

MY_VAR_WITH_DEFAULT: z
  .string()
  .optional()
  .default('default-value')
  .describe('Configuration with a sensible default'),

列挙型の変数

LOG_LEVEL: z
  .enum(['trace', 'debug', 'info', 'warn', 'error'])
  .default('info')
  .describe('Logging verbosity level'),

数値型の変数

POOL_SIZE: z
  .coerce.number()
  .optional()
  .default(10)
  .describe('Maximum number of connections in the pool'),

ブール型の変数（文字列として）

FEATURE_ENABLED: z
  .string()
  .optional()
  .transform((val) => val === 'true')
  .describe('Enable feature X (set to "true" to enable)'),

バリデーション付きの変数

JWT_SECRET: z
  .string()
  .min(32, 'JWT_SECRET must be at least 32 characters')
  .optional()
  .describe('Secret key for signing JWT tokens (minimum 32 characters)'),

ADMIN_EMAIL: z
  .string()
  .optional()
  .refine((val) => !val || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(val), {
    message: 'Invalid email address',
  })
  .describe('Admin email address for notifications'),

---

カテゴリー別の整理

.env.example と env.ts の両方で、関連する変数をコメントでグループ化します。

.env.example の場合：

# ============ DATABASE ============
INKEEP_AGENTS_MANAGE_DATABASE_URL=...
INKEEP_AGENTS_RUN_DATABASE_URL=...

# ============ AI PROVIDERS ============
ANTHROPIC_API_KEY=
OPENAI_API_KEY=

env.ts の場合：

const envSchema = z.object({
  // Database
  INKEEP_AGENTS_MANAGE_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the management database'),
  INKEEP_AGENTS_RUN_DATABASE_URL: z
    .string()
    .describe('PostgreSQL connection URL for the runtime database'),

  // AI Providers
  ANTHROPIC_API_KEY: z
    .string()
    .describe('Anthropic API key for Claude models'),
  OPENAI_API_KEY: z
    .string()
    .optional()
    .describe('OpenAI API key for GPT models'),
});

---

使用する env.ts ファイルの選び方

変数を使用する場所に応じて、適切なファイルを選びます。

用途	ファイル
API サーバーの設定	agents-api/src/env.ts
パッケージ間で共有	packages/agents-core/src/env.ts
CLI 固有	agents-cli/src/env.ts
複数のパッケージ	agents-core に追加し、必要な場所でインポート

---

環境変数追加のチェックリスト

環境変数の追加を完了する前に、次の項目を確認してください。

• 説明的なコメントとともに変数を .env.example に追加した
• 該当する env.ts ファイルに変数を追加した
• 明確な説明を含む .describe() 呼び出しを追加した
• 説明が .env.example のコメントと一致している
• 適切な Zod 型（文字列、数値、列挙型など）を使用した
• 変数が必須でない場合は optional() を追加した
• 適切なデフォルト値がある場合は default() を追加した
• 必要に応じてバリデーション（min、max、refine など）を追加した
• 関連する変数とグループ化した（コメントを使用）
• pnpm check:env-descriptions がローカルで成功する

---

避けるべきよくある間違い

1. .describe() 呼び出しの不足 - すべての変数に説明が必要です（CI が失敗します！）
2. 説明に一貫性がない - .env.example と .describe() の内容を一致させてください
3. ファイルの選択ミス - 実際にその変数を使用するパッケージに追加してください
4. バリデーションの不足 - 機密性の高い値には制約を追加してください（シークレットの最小文字数、メールアドレスの検証など）
5. 自動生成ファイルの編集 - agents-mcp の環境変数ファイルは編集しないでください