סביבת פיתוח — Setup לכל SDK

# macOS — עם Homebrew
brew install python@3.12

# Windows — עם winget
winget install Python.Python.3.12
# או: הורד מ-python.org/downloads

# Ubuntu/Debian
sudo apt update && sudo apt install python3.12 python3.12-venv

# אימות
python3 --version  # Python 3.12.x

# === אופציה 1: venv (built-in, תמיד זמין) ===
python -m venv .venv
source .venv/bin/activate      # macOS/Linux
# .venv\Scripts\activate       # Windows
pip install -r requirements.txt

# === אופציה 2: uv (מומלץ! מהיר פי 10-100) ===
# התקנה: https://docs.astral.sh/uv/getting-started/installation/
curl -LsSf https://astral.sh/uv/install.sh | sh  # macOS/Linux
# winget install --id=astral-sh.uv -e             # Windows

# שימוש:
uv init my-agent                   # יוצר פרויקט חדש עם pyproject.toml
cd my-agent
uv add claude-agent-sdk openai-agents google-adk  # מתקין ישירות
uv run python agent.py             # מריץ בתוך ה-venv אוטומטית

# === אופציה 3: conda (לעבודה עם ML/DS) ===
conda create -n agents python=3.12
conda activate agents
pip install -r requirements.txt

# macOS — עם Homebrew
brew install node@22

# Windows — עם winget
winget install OpenJS.NodeJS.LTS
# או: הורד מ-nodejs.org

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# אימות
node --version   # v22.x.x
npm --version    # 10.x.x

# יצירת פרויקט TypeScript חדש
mkdir my-agent-ts && cd my-agent-ts

# npm (ברירת מחדל)
npm init -y
npm install typescript tsx @types/node --save-dev
npx tsc --init

# או pnpm (מומלץ)
pnpm init
pnpm add typescript tsx @types/node -D
pnpm exec tsc --init

# הגדרת tsconfig.json מינימלית לסוכנים
cat > tsconfig.json << 'TSCONFIG'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"]
}
TSCONFIG

# צור קובץ .env בתיקיית הפרויקט
# .env — NEVER commit this file!

# Anthropic
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# OpenAI
OPENAI_API_KEY=sk-proj-your-key-here

# Google
GOOGLE_API_KEY=AIzaSy-your-key-here

# Optional: default model preferences
DEFAULT_MODEL=claude-sonnet-4-6-20260324
MAX_TOKENS=4096

# === API Keys & Secrets ===
.env
.env.local
.env.*.local
*.key
*.pem

# === Python ===
__pycache__/
*.py[cod]
.venv/
venv/
*.egg-info/
dist/
build/

# === Node.js ===
node_modules/
dist/
.next/

# === IDE ===
.vscode/settings.json
.idea/
*.swp
*.swo

# === OS ===
.DS_Store
Thumbs.db

# === Agent-specific ===
logs/
*.log
.cache/

# התקנה
pip install python-dotenv   # או: uv add python-dotenv

# שימוש בקוד
from dotenv import load_dotenv
import os

load_dotenv()  # טוען את .env לתוך os.environ

# גישה למפתחות
anthropic_key = os.getenv("ANTHROPIC_API_KEY")
openai_key = os.getenv("OPENAI_API_KEY")
google_key = os.getenv("GOOGLE_API_KEY")

# בדיקה שהמפתח קיים
if not anthropic_key:
    raise ValueError("ANTHROPIC_API_KEY not found in .env file!")

print("All API keys loaded successfully!")

// התקנה
// npm install dotenv

// שימוש בקוד — src/config.ts
import 'dotenv/config';

const requiredKeys = [
  'ANTHROPIC_API_KEY',
  'OPENAI_API_KEY',
  'GOOGLE_API_KEY',
] as const;

// בדיקה שכל המפתחות קיימים
for (const key of requiredKeys) {
  if (!process.env[key]) {
    console.warn(`Warning: ${key} not found in environment`);
  }
}

export const config = {
  anthropicKey: process.env.ANTHROPIC_API_KEY!,
  openaiKey: process.env.OPENAI_API_KEY!,
  googleKey: process.env.GOOGLE_API_KEY!,
  defaultModel: process.env.DEFAULT_MODEL || 'claude-sonnet-4-6-20260324',
};

"""verify_keys.py — בדיקת מפתחות API"""
from dotenv import load_dotenv
import os

load_dotenv()

def test_anthropic():
    import anthropic
    client = anthropic.Anthropic()
    msg = client.messages.create(
        model="claude-sonnet-4-6-20260324",
        max_tokens=50,
        messages=[{"role": "user", "content": "Say 'API key works!' in 3 words"}]
    )
    print(f"Anthropic: {msg.content[0].text}")

def test_openai():
    from openai import OpenAI
    client = OpenAI()
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        max_tokens=50,
        messages=[{"role": "user", "content": "Say 'API key works!' in 3 words"}]
    )
    print(f"OpenAI: {resp.choices[0].message.content}")

def test_google():
    from google import genai
    client = genai.Client(api_key=os.getenv("GOOGLE_API_KEY"))
    resp = client.models.generate_content(
        model="gemini-2.0-flash",
        contents="Say 'API key works!' in 3 words"
    )
    print(f"Google: {resp.text}")

if __name__ == "__main__":
    for name, test_fn in [
        ("Anthropic", test_anthropic),
        ("OpenAI", test_openai),
        ("Google", test_google),
    ]:
        try:
            test_fn()
        except Exception as e:
            print(f"{name}: FAILED - {e}")

# === עם pip (בתוך venv) ===
pip install anthropic                    # Anthropic API client
pip install claude-agent-sdk             # Claude Agent SDK
pip install openai                       # OpenAI API client
pip install openai-agents                # OpenAI Agents SDK
pip install google-genai                 # Google GenAI client
pip install google-adk                   # Google ADK
pip install langchain langchain-anthropic langchain-openai langgraph  # LangChain + LangGraph
pip install crewai crewai-tools          # CrewAI
pip install mcp                          # MCP SDK
pip install python-dotenv                # .env loading
pip install pydantic-ai                  # Pydantic AI (bonus)

# === עם uv (מומלץ — הכל בפקודה אחת) ===
uv add anthropic claude-agent-sdk \
     openai openai-agents \
     google-genai google-adk \
     langchain langchain-anthropic langchain-openai langgraph \
     crewai crewai-tools \
     mcp python-dotenv pydantic-ai

# === requirements.txt — לנעילת גרסאות ===
cat > requirements.txt << 'REQ'
anthropic>=0.45.0
claude-agent-sdk>=0.1.48
openai>=1.60.0
openai-agents>=0.13.0
google-genai>=1.10.0
google-adk>=1.2.0
langchain>=0.3.0
langchain-anthropic>=0.3.0
langchain-openai>=0.3.0
langgraph>=1.0.0
crewai>=0.95.0
mcp>=1.8.0
python-dotenv>=1.0.0
REQ

# === עם npm ===
npm install @anthropic-ai/claude-agent-sdk   # Claude Agent SDK (TS)
npm install ai                                # Vercel AI SDK core
npm install @ai-sdk/anthropic                 # Vercel + Claude
npm install @ai-sdk/openai                    # Vercel + OpenAI
npm install @ai-sdk/google                    # Vercel + Google
npm install @openai/agents                    # OpenAI Agents SDK (TS)
npm install @modelcontextprotocol/sdk         # MCP SDK (TS)
npm install dotenv                            # .env loading

# === עם pnpm (מומלץ) ===
pnpm add @anthropic-ai/claude-agent-sdk \
         ai @ai-sdk/anthropic @ai-sdk/openai @ai-sdk/google \
         @openai/agents \
         @modelcontextprotocol/sdk \
         dotenv

# Dev dependencies
pnpm add -D typescript tsx @types/node vitest

"""test_sdks.py — verify all SDKs are installed correctly"""

def test_imports():
    """Test that all SDKs import successfully."""
    results = {}

    # Claude Agent SDK
    try:
        import claude_agent_sdk
        results["Claude Agent SDK"] = f"v{claude_agent_sdk.__version__}"
    except ImportError as e:
        results["Claude Agent SDK"] = f"MISSING: {e}"

    # OpenAI Agents SDK
    try:
        import agents
        results["OpenAI Agents SDK"] = "OK"
    except ImportError as e:
        results["OpenAI Agents SDK"] = f"MISSING: {e}"

    # Google ADK
    try:
        import google.adk
        results["Google ADK"] = "OK"
    except ImportError as e:
        results["Google ADK"] = f"MISSING: {e}"

    # LangGraph
    try:
        import langgraph
        results["LangGraph"] = "OK"
    except ImportError as e:
        results["LangGraph"] = f"MISSING: {e}"

    # CrewAI
    try:
        import crewai
        results["CrewAI"] = "OK"
    except ImportError as e:
        results["CrewAI"] = f"MISSING: {e}"

    # MCP SDK
    try:
        import mcp
        results["MCP SDK"] = "OK"
    except ImportError as e:
        results["MCP SDK"] = f"MISSING: {e}"

    # Pydantic AI
    try:
        import pydantic_ai
        results["Pydantic AI"] = "OK"
    except ImportError as e:
        results["Pydantic AI"] = f"MISSING: {e}"

    print("\n=== SDK Installation Check ===")
    for sdk, status in results.items():
        icon = "+" if "MISSING" not in status else "X"
        print(f"  [{icon}] {sdk}: {status}")

    failed = [k for k, v in results.items() if "MISSING" in v]
    if failed:
        print(f"\n{len(failed)} SDK(s) missing. Install them before continuing.")
    else:
        print(f"\nAll {len(results)} SDKs installed successfully!")

if __name__ == "__main__":
    test_imports()

my-agent/
├── src/
│   ├── agent.py              # Main agent logic (or agent.ts)
│   ├── config.py             # Configuration, env loading
│   ├── tools/                # Custom tool definitions
│   │   ├── __init__.py
│   │   ├── search.py         # Search tools
│   │   ├── database.py       # DB tools
│   │   └── notifications.py  # Email/Slack tools
│   ├── mcp_servers/          # MCP server implementations
│   │   └── my_server.py
│   ├── prompts/              # System prompts and templates
│   │   ├── system.md         # Main system prompt
│   │   └── templates/        # Prompt templates
│   └── memory/               # Memory/state management
│       └── store.py
├── tests/                    # Test cases and evals
│   ├── test_tools.py         # Unit tests for tools
│   ├── test_agent.py         # Integration tests
│   └── evals/                # Evaluation datasets
│       └── golden_dataset.json
├── config/                   # Configuration files
│   └── models.yaml           # Model routing config
├── scripts/                  # Utility scripts
│   ├── verify_keys.py        # API key verification
│   └── test_sdks.py          # SDK installation check
├── .env                      # API keys (GITIGNORED)
├── .env.example              # Template for .env (safe to commit)
├── .gitignore                # Git ignore rules
├── requirements.txt          # Python dependencies (pinned)
├── pyproject.toml            # Python project config (uv/poetry)
├── package.json              # Node.js dependencies (if TS)
├── tsconfig.json             # TypeScript config (if TS)
├── Dockerfile                # Container definition
├── docker-compose.yml        # Multi-container setup
└── README.md                 # Project documentation

# .env.example — Copy to .env and fill in your keys
# cp .env.example .env

# Required: At least one API key
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
OPENAI_API_KEY=sk-proj-your-key-here
GOOGLE_API_KEY=AIzaSy-your-key-here

# Optional: defaults
DEFAULT_MODEL=claude-sonnet-4-6-20260324
MAX_TOKENS=4096
LOG_LEVEL=INFO

# התקנה מהטרמינל
code --install-extension ms-python.python
code --install-extension ms-python.vscode-pylance
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension ms-azuretools.vscode-docker
code --install-extension redhat.vscode-yaml

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.analysis.typeCheckingMode": "basic",
  "editor.formatOnSave": true,
  "editor.tabSize": 4,
  "[python]": {
    "editor.defaultFormatter": "ms-python.python",
    "editor.tabSize": 4
  },
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/.pytest_cache": true,
    "**/node_modules": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/.venv": true
  }
}

# CLAUDE.md — צור קובץ בתיקיית הפרויקט

## Project Context
This is an AI agent project. We use:
- Claude Agent SDK (Python) for main agent logic
- MCP SDK for tool servers
- pytest for testing

## Conventions
- All API keys loaded from .env via python-dotenv
- Type hints on all functions
- Docstrings on all public functions
- Tests in tests/ directory

## Important
- NEVER hardcode API keys
- NEVER commit .env files
- Always use virtual environment

# Dockerfile
FROM python:3.12-slim

# Set working directory
WORKDIR /app

# Install dependencies first (cached layer)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy source code
COPY src/ ./src/
COPY config/ ./config/

# Don't copy .env — pass secrets via environment variables
# docker run --env-file .env my-agent

# Run the agent
CMD ["python", "src/agent.py"]

# docker-compose.yml
version: "3.9"

services:
  agent:
    build: .
    env_file: .env
    depends_on:
      - mcp-server
    volumes:
      - ./logs:/app/logs

  mcp-server:
    build:
      context: .
      dockerfile: Dockerfile.mcp
    ports:
      - "3001:3001"
    env_file: .env

# בנייה
docker build -t my-agent .

# הרצה עם .env
docker run --env-file .env my-agent

# הרצה אינטראקטיבית (לדיבאג)
docker run -it --env-file .env my-agent bash

# docker-compose — הרצת הכל ביחד
docker compose up -d          # ברקע
docker compose logs -f agent  # מעקב אחרי לוגים
docker compose down            # עצירה

"""cost_tracker.py — Track API costs per request"""
import time
from dataclasses import dataclass, field
from typing import Optional


@dataclass
class UsageRecord:
    model: str
    input_tokens: int
    output_tokens: int
    cost_usd: float
    duration_ms: float
    timestamp: float = field(default_factory=time.time)


class CostTracker:
    """Simple cost tracker for LLM API calls."""

    # Approximate prices per 1M tokens (March 2026)
    PRICES = {
        "claude-sonnet-4-6": {"input": 3.0, "output": 15.0},
        "claude-haiku-3-5":  {"input": 0.80, "output": 4.0},
        "claude-opus-4-6":   {"input": 15.0, "output": 75.0},
        "gpt-4o":            {"input": 2.50, "output": 10.0},
        "gpt-4o-mini":       {"input": 0.15, "output": 0.60},
        "gemini-2.5-pro":    {"input": 1.25, "output": 10.0},
        "gemini-2.0-flash":  {"input": 0.10, "output": 0.40},
    }

    def __init__(self, budget_usd: float = 25.0):
        self.budget = budget_usd
        self.records: list[UsageRecord] = []

    def record(self, model: str, input_tokens: int,
               output_tokens: int, duration_ms: float):
        # Find matching price (partial match on model name)
        price = None
        for key, val in self.PRICES.items():
            if key in model:
                price = val
                break
        if not price:
            price = {"input": 5.0, "output": 15.0}  # conservative default

        cost = (
            (input_tokens / 1_000_000) * price["input"] +
            (output_tokens / 1_000_000) * price["output"]
        )

        record = UsageRecord(
            model=model,
            input_tokens=input_tokens,
            output_tokens=output_tokens,
            cost_usd=cost,
            duration_ms=duration_ms,
        )
        self.records.append(record)

        total = self.total_cost
        if total > self.budget * 0.8:
            print(f"WARNING: Spent ${total:.2f} of ${self.budget:.2f} budget!")
        if total > self.budget:
            raise RuntimeError(
                f"BUDGET EXCEEDED: ${total:.2f} > ${self.budget:.2f}"
            )
        return record

    @property
    def total_cost(self) -> float:
        return sum(r.cost_usd for r in self.records)

    def summary(self):
        total = self.total_cost
        total_input = sum(r.input_tokens for r in self.records)
        total_output = sum(r.output_tokens for r in self.records)
        print(f"\n=== Cost Summary ===")
        print(f"Requests:      {len(self.records)}")
        print(f"Input tokens:  {total_input:,}")
        print(f"Output tokens: {total_output:,}")
        print(f"Total cost:    ${total:.4f}")
        print(f"Budget left:   ${self.budget - total:.4f}")

"""agent_logger.py — Structured logging for AI agents"""
import logging
import json
from datetime import datetime


def setup_agent_logger(name: str = "agent", level: str = "INFO"):
    """Create a structured logger for agent debugging."""
    logger = logging.getLogger(name)
    logger.setLevel(getattr(logging, level))

    # Console handler with structured format
    handler = logging.StreamHandler()
    formatter = logging.Formatter(
        '%(asctime)s | %(levelname)-7s | %(message)s',
        datefmt='%H:%M:%S'
    )
    handler.setFormatter(formatter)
    logger.addHandler(handler)

    # File handler for detailed logs
    file_handler = logging.FileHandler(
        f"logs/agent_{datetime.now():%Y%m%d}.log"
    )
    file_handler.setFormatter(formatter)
    logger.addHandler(file_handler)

    return logger


# Usage example
logger = setup_agent_logger()

def log_tool_call(tool_name: str, params: dict, result: str,
                  duration_ms: float):
    """Log a tool call with all relevant details."""
    logger.info(json.dumps({
        "event": "tool_call",
        "tool": tool_name,
        "params": params,
        "result_length": len(result),
        "duration_ms": round(duration_ms, 1),
    }))

def log_llm_call(model: str, input_tokens: int,
                 output_tokens: int, duration_ms: float):
    """Log an LLM API call."""
    logger.info(json.dumps({
        "event": "llm_call",
        "model": model,
        "input_tokens": input_tokens,
        "output_tokens": output_tokens,
        "duration_ms": round(duration_ms, 1),
    }))

# התקנה
pip install jupyter ipykernel    # או: uv add jupyter ipykernel

# רישום ה-venv כ-kernel
python -m ipykernel install --user --name=agents --display-name="AI Agents"

# הפעלה
jupyter notebook  # או: jupyter lab

# התקנה
pip install pytest pytest-asyncio    # או: uv add pytest pytest-asyncio -D

# pytest.ini (או pyproject.toml)
cat > pytest.ini << 'PYTEST'
[pytest]
testpaths = tests
asyncio_mode = auto
markers =
    unit: Unit tests (no API calls)
    integration: Integration tests (API calls required)
    eval: Evaluation tests (expensive, run manually)
PYTEST

# tests/test_tools.py — דוגמה ל-unit test
def test_weather_tool_validates_input():
    """Tool should reject invalid city names."""
    from src.tools.search import validate_city

    assert validate_city("Tel Aviv") == True
    assert validate_city("") == False
    assert validate_city(None) == False

def test_cost_tracker_budget():
    """CostTracker should raise when budget exceeded."""
    from src.cost_tracker import CostTracker
    import pytest

    tracker = CostTracker(budget_usd=0.01)
    tracker.record("claude-sonnet-4-6", 100000, 50000, 1000)

    with pytest.raises(RuntimeError, match="BUDGET EXCEEDED"):
        tracker.record("claude-sonnet-4-6", 100000, 50000, 1000)

# הרצה
# pytest -m unit          # רק unit tests (בלי API)
# pytest -m integration   # עם API calls
# pytest                  # הכל

// התקנה: npm install -D vitest
// או: pnpm add -D vitest

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    include: ['tests/**/*.test.ts'],
    environment: 'node',
    testTimeout: 30000,  // 30s for API calls
  },
});

// tests/config.test.ts — בדיקת configuration
import { describe, it, expect } from 'vitest';

describe('Configuration', () => {
  it('should load API keys from environment', () => {
    // This tests that .env is loaded correctly
    expect(process.env.ANTHROPIC_API_KEY).toBeDefined();
    expect(process.env.ANTHROPIC_API_KEY).toMatch(/^sk-ant/);
  });

  it('should have valid default model', () => {
    const model = process.env.DEFAULT_MODEL || 'claude-sonnet-4-6-20260324';
    expect(model).toContain('claude');
  });
});

// package.json — add script
// "scripts": { "test": "vitest run", "test:watch": "vitest" }

{
  "version": "1.0",
  "description": "Golden dataset for agent evaluation",
  "test_cases": [
    {
      "id": "TC001",
      "category": "weather",
      "input": "What's the weather in Tel Aviv?",
      "expected_tool": "get_weather",
      "expected_params": {"city": "Tel Aviv"},
      "success_criteria": "Response mentions temperature and city name"
    },
    {
      "id": "TC002",
      "category": "no_tool",
      "input": "What is the capital of France?",
      "expected_tool": null,
      "success_criteria": "Answers 'Paris' without calling any tool"
    },
    {
      "id": "TC003",
      "category": "edge_case",
      "input": "Weather in !!@@##",
      "expected_tool": null,
      "success_criteria": "Asks for clarification, does not crash"
    }
  ]
}