ezop 0.0.2__tar.gz

ezop-0.0.2/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: ezop
+Version: 0.0.2
+Summary: Ezop SDK - The story of every AI agent
+Author-email: Ezop <support@ezop.ai>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: build; extra == "dev"
+
+# Ezop Python SDK
+
+Ezop tracks the lifecycle of your AI agents — registrations, versions, and runs — so you have full observability across every deployment.
+
+## Installation
+
+```bash
+pip install ezop
+```
+
+## Configuration
+
+Set your API key before using the SDK:
+
+```bash
+export EZOP_API_KEY=your-ezop-api-key-here
+export EZOP_API_URL=https://api.ezop.ai   # optional, this is the default
+```
+
+## Quick start
+
+```python
+from ezop import Agent
+
+# Register your agent at startup (safe to call on every deploy — idempotent)
+agent = Agent.init(
+    name="customer-support-bot",
+    owner="growth-team",
+    version="v0.3",
+    runtime="langchain",
+    description="Handles tier-1 customer support tickets",
+    default_permissions=["read:tickets"],
+    permissions=["read:tickets", "write:replies"],
+    changelog="Switched to new retrieval pipeline",
+)
+
+# Track a run
+agent.start_run()
+
+try:
+    result = your_agent_logic(user_input)
+    agent.end_run(
+        status="completed",
+        total_tokens=result.usage.total_tokens,
+        total_cost=result.cost,
+        metadata={"user_id": user_id},
+    )
+except Exception as e:
+    agent.end_run(status="failed", metadata={"error": str(e)})
+    raise
+```
+
+## API reference
+
+### `Agent.init()`
+
+Registers the agent and its current version with the Ezop platform. On subsequent calls with the same `name` + `owner`, the agent record is updated in place — safe to call on every startup.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `name` | yes | Agent name |
+| `owner` | yes | Team or user that owns the agent |
+| `version` | yes | Version string for this deployment (e.g. `"v0.3"`) |
+| `runtime` | yes | Runtime framework (e.g. `"langchain"`, `"langchain"`, `"python"`) |
+| `description` | no | Human-readable description of the agent |
+| `default_permissions` | no | Default permission scopes for the agent |
+| `permissions` | no | Permission scopes for this specific version |
+| `changelog` | no | Release notes for this version |
+
+### `agent.start_run()`
+
+Creates a new run record with status `running`. Call this at the start of each agent invocation.
+
+### `agent.end_run()`
+
+Closes the current run. Only provided fields are written.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `status` | `"completed"` | Final run status (`"completed"`, `"failed"`, etc.) |
+| `total_tokens` | `None` | Total tokens consumed |
+| `total_cost` | `None` | Total cost in USD |
+| `metadata` | `None` | Arbitrary JSON metadata |
+
+## Logging
+
+The SDK uses Python's standard `logging` module under the `ezop` namespace. To enable logs in your application:
+
+```python
+import logging
+logging.getLogger("ezop").setLevel(logging.DEBUG)
+```

ezop-0.0.2/README.md

@@ -0,0 +1,92 @@
+# Ezop Python SDK
+
+Ezop tracks the lifecycle of your AI agents — registrations, versions, and runs — so you have full observability across every deployment.
+
+## Installation
+
+```bash
+pip install ezop
+```
+
+## Configuration
+
+Set your API key before using the SDK:
+
+```bash
+export EZOP_API_KEY=your-ezop-api-key-here
+export EZOP_API_URL=https://api.ezop.ai   # optional, this is the default
+```
+
+## Quick start
+
+```python
+from ezop import Agent
+
+# Register your agent at startup (safe to call on every deploy — idempotent)
+agent = Agent.init(
+    name="customer-support-bot",
+    owner="growth-team",
+    version="v0.3",
+    runtime="langchain",
+    description="Handles tier-1 customer support tickets",
+    default_permissions=["read:tickets"],
+    permissions=["read:tickets", "write:replies"],
+    changelog="Switched to new retrieval pipeline",
+)
+
+# Track a run
+agent.start_run()
+
+try:
+    result = your_agent_logic(user_input)
+    agent.end_run(
+        status="completed",
+        total_tokens=result.usage.total_tokens,
+        total_cost=result.cost,
+        metadata={"user_id": user_id},
+    )
+except Exception as e:
+    agent.end_run(status="failed", metadata={"error": str(e)})
+    raise
+```
+
+## API reference
+
+### `Agent.init()`
+
+Registers the agent and its current version with the Ezop platform. On subsequent calls with the same `name` + `owner`, the agent record is updated in place — safe to call on every startup.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `name` | yes | Agent name |
+| `owner` | yes | Team or user that owns the agent |
+| `version` | yes | Version string for this deployment (e.g. `"v0.3"`) |
+| `runtime` | yes | Runtime framework (e.g. `"langchain"`, `"langchain"`, `"python"`) |
+| `description` | no | Human-readable description of the agent |
+| `default_permissions` | no | Default permission scopes for the agent |
+| `permissions` | no | Permission scopes for this specific version |
+| `changelog` | no | Release notes for this version |
+
+### `agent.start_run()`
+
+Creates a new run record with status `running`. Call this at the start of each agent invocation.
+
+### `agent.end_run()`
+
+Closes the current run. Only provided fields are written.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `status` | `"completed"` | Final run status (`"completed"`, `"failed"`, etc.) |
+| `total_tokens` | `None` | Total tokens consumed |
+| `total_cost` | `None` | Total cost in USD |
+| `metadata` | `None` | Arbitrary JSON metadata |
+
+## Logging
+
+The SDK uses Python's standard `logging` module under the `ezop` namespace. To enable logs in your application:
+
+```python
+import logging
+logging.getLogger("ezop").setLevel(logging.DEBUG)
+```

ezop-0.0.2/ezop/__init__.py

@@ -0,0 +1,7 @@
+import logging
+
+from .agent import Agent
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = ["Agent"]

ezop-0.0.2/ezop/agent.py

@@ -0,0 +1,140 @@
+import logging
+from typing import Optional
+from .models import AgentModel, AgentVersion, AgentRun
+from .client import EzopClient
+
+logger = logging.getLogger(__name__)
+
+
+class Agent:
+
+    def __init__(self, model: AgentModel, version: AgentVersion):
+        self.model = model
+        self.version = version
+        self.client = EzopClient()
+        self.current_run: Optional[AgentRun] = None
+
+    @classmethod
+    def init(
+        cls,
+        name: str,
+        owner: str,
+        version: str,
+        runtime: str,
+        *,
+        description: Optional[str] = None,
+        default_permissions: Optional[list[str]] = None,
+        permissions: Optional[list[str]] = None,
+        changelog: Optional[str] = None,
+    ) -> "Agent":
+        """
+        Initialize an Ezop agent and register it with the Ezop platform.
+        Creates the agent record and a corresponding version record.
+        """
+        logger.info(
+            "Initializing agent name=%s owner=%s version=%s runtime=%s",
+            name,
+            owner,
+            version,
+            runtime,
+        )
+        client = EzopClient()
+
+        agent_data = client.register_agent(
+            {
+                "name": name,
+                "owner": owner,
+                "runtime": runtime,
+                "description": description,
+                "default_permissions": default_permissions,
+            }
+        )["data"]
+
+        model = AgentModel(
+            id=agent_data["id"],
+            name=agent_data["name"],
+            owner=agent_data["owner"],
+            runtime=agent_data.get("runtime"),
+            description=agent_data.get("description"),
+            default_permissions=agent_data.get("default_permissions") or [],
+        )
+        logger.debug("Agent model built id=%s", model.id)
+
+        version_data = client.create_version(
+            model.id,
+            {
+                "version": version,
+                "permissions": permissions,
+                "changelog": changelog,
+            },
+        )["data"]
+
+        agent_version = AgentVersion(
+            id=version_data["id"],
+            agent_id=model.id,
+            version=version_data["version"],
+            permissions=version_data.get("permissions") or [],
+            changelog=version_data.get("changelog"),
+        )
+        logger.debug("Agent version built id=%s", agent_version.id)
+
+        logger.info("Agent initialized id=%s version_id=%s", model.id, agent_version.id)
+        return cls(model, agent_version)
+
+    def start_run(self) -> AgentRun:
+        """Start a new run for this agent version."""
+        logger.info(
+            "Starting run for agent id=%s version_id=%s", self.model.id, self.version.id
+        )
+        run_data = self.client.start_run(self.model.id, self.version.id)["data"]
+        self.current_run = AgentRun(
+            id=run_data["id"],
+            agent_id=self.model.id,
+            version_id=self.version.id,
+            status=run_data.get("status", "running"),
+        )
+        logger.debug(
+            "Run created id=%s status=%s", self.current_run.id, self.current_run.status
+        )
+        return self.current_run
+
+    def end_run(
+        self,
+        status: str = "running",
+        total_tokens: Optional[int] = None,
+        total_cost: Optional[float] = None,
+        metadata: Optional[dict] = None,
+        message: Optional[str] = None,
+    ) -> AgentRun:
+        """End the current run.
+
+        Args:
+            status: Final status of the run (e.g. "completed", "failed").
+            message: Optional human-readable message, e.g. a failure reason.
+        """
+        if self.current_run is None:
+            logger.error("end_run called with no active run")
+            raise RuntimeError("No active run. Call start_run() first.")
+
+        logger.info("Ending run id=%s status=%s", self.current_run.id, status)
+        run_data = self.client.end_run(
+            self.current_run.id,
+            status=status,
+            total_tokens=total_tokens,
+            total_cost=total_cost,
+            metadata=metadata,
+            message=message,
+        )["data"]
+        self.current_run.status = run_data.get("status", status)
+        self.current_run.total_tokens = run_data.get("total_tokens")
+        self.current_run.total_cost = run_data.get("total_cost")
+        self.current_run.metadata = run_data.get("metadata")
+        self.current_run.message = run_data.get("message")
+        logger.debug(
+            "Run ended id=%s status=%s total_tokens=%s total_cost=%s",
+            self.current_run.id,
+            self.current_run.status,
+            self.current_run.total_tokens,
+            self.current_run.total_cost,
+        )
+        return self.current_run

ezop-0.0.2/ezop/client.py

@@ -0,0 +1,82 @@
+import logging
+import requests
+from .config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class EzopClient:
+
+    def _headers(self):
+        return {
+            "Authorization": f"Bearer {Config.EZOP_API_KEY}",
+            "Content-Type": "application/json",
+        }
+
+    def _post(self, path: str, body: dict) -> dict:
+        url = f"{Config.EZOP_API_URL}{path}"
+        logger.debug("POST %s body=%s", url, body)
+        response = requests.post(url, json=body, headers=self._headers())
+        if response.status_code not in (200, 201):
+            logger.error("POST %s failed status=%s body=%s", url, response.status_code, response.text)
+            raise Exception(f"Ezop API error: {response.text}")
+        logger.debug("POST %s status=%s", url, response.status_code)
+        return response.json()
+
+    def _patch(self, path: str, body: dict) -> dict:
+        url = f"{Config.EZOP_API_URL}{path}"
+        logger.debug("PATCH %s body=%s", url, body)
+        response = requests.patch(url, json=body, headers=self._headers())
+        if response.status_code != 200:
+            logger.error("PATCH %s failed status=%s body=%s", url, response.status_code, response.text)
+            raise Exception(f"Ezop API error: {response.text}")
+        logger.debug("PATCH %s status=%s", url, response.status_code)
+        return response.json()
+
+    def register_agent(self, agent_data: dict) -> dict:
+        logger.info("Registering agent name=%s owner=%s", agent_data.get("name"), agent_data.get("owner"))
+        result = self._post("/agents/register", agent_data)
+        logger.info("Agent registered id=%s", result.get("data", {}).get("id"))
+        return result
+
+    def create_version(self, agent_id: str, version_data: dict) -> dict:
+        logger.info("Creating version agent_id=%s version=%s", agent_id, version_data.get("version"))
+        result = self._post(f"/agents/{agent_id}/versions", version_data)
+        logger.info("Version created id=%s", result.get("data", {}).get("id"))
+        return result
+
+    def start_run(
+        self,
+        agent_id: str,
+        version_id: str | None = None,
+        user_id: str | None = None,
+        metadata: dict | None = None,
+    ) -> dict:
+        logger.info("Starting run agent_id=%s version_id=%s", agent_id, version_id)
+        body: dict = {}
+        if version_id is not None:
+            body["version_id"] = version_id
+        if user_id is not None:
+            body["user_id"] = user_id
+        if metadata is not None:
+            body["metadata"] = metadata
+        result = self._post(f"/agents/{agent_id}/runs", body)
+        logger.info("Run started id=%s", result.get("data", {}).get("id"))
+        return result
+
+    def end_run(self, run_id: str, status: str, total_tokens: int | None = None,
+                total_cost: float | None = None, metadata: dict | None = None,
+                message: str | None = None) -> dict:
+        logger.info("Ending run id=%s status=%s", run_id, status)
+        body = {"status": status}
+        if total_tokens is not None:
+            body["total_tokens"] = total_tokens
+        if total_cost is not None:
+            body["total_cost"] = total_cost
+        if metadata is not None:
+            body["metadata"] = metadata
+        if message is not None:
+            body["message"] = message
+        result = self._patch(f"/runs/{run_id}", body)
+        logger.info("Run ended id=%s status=%s total_tokens=%s total_cost=%s", run_id, status, total_tokens, total_cost)
+        return result

ezop-0.0.2/ezop/config.py

@@ -0,0 +1,6 @@
+import os
+
+
+class Config:
+    EZOP_API_URL = os.getenv("EZOP_API_URL", "https://api.ezop.ai")
+    EZOP_API_KEY = os.getenv("EZOP_API_KEY", None)

ezop-0.0.2/ezop/models.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass, field
+from typing import Optional
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class AgentModel:
+    id: str
+    name: str
+    owner: str
+    runtime: Optional[str]
+    description: Optional[str]
+    default_permissions: list[str]
+
+
+@dataclass(frozen=True)
+class AgentVersion:
+    id: str
+    agent_id: str
+    version: str
+    permissions: list[str]
+    changelog: Optional[str]
+
+
+@dataclass
+class AgentRun:
+    id: str
+    agent_id: str
+    version_id: Optional[str]
+    status: str
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    total_tokens: Optional[int] = None
+    total_cost: Optional[float] = None
+    metadata: Optional[dict] = None
+    message: Optional[str] = None

ezop-0.0.2/ezop.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: ezop
+Version: 0.0.2
+Summary: Ezop SDK - The story of every AI agent
+Author-email: Ezop <support@ezop.ai>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: build; extra == "dev"
+
+# Ezop Python SDK
+
+Ezop tracks the lifecycle of your AI agents — registrations, versions, and runs — so you have full observability across every deployment.
+
+## Installation
+
+```bash
+pip install ezop
+```
+
+## Configuration
+
+Set your API key before using the SDK:
+
+```bash
+export EZOP_API_KEY=your-ezop-api-key-here
+export EZOP_API_URL=https://api.ezop.ai   # optional, this is the default
+```
+
+## Quick start
+
+```python
+from ezop import Agent
+
+# Register your agent at startup (safe to call on every deploy — idempotent)
+agent = Agent.init(
+    name="customer-support-bot",
+    owner="growth-team",
+    version="v0.3",
+    runtime="langchain",
+    description="Handles tier-1 customer support tickets",
+    default_permissions=["read:tickets"],
+    permissions=["read:tickets", "write:replies"],
+    changelog="Switched to new retrieval pipeline",
+)
+
+# Track a run
+agent.start_run()
+
+try:
+    result = your_agent_logic(user_input)
+    agent.end_run(
+        status="completed",
+        total_tokens=result.usage.total_tokens,
+        total_cost=result.cost,
+        metadata={"user_id": user_id},
+    )
+except Exception as e:
+    agent.end_run(status="failed", metadata={"error": str(e)})
+    raise
+```
+
+## API reference
+
+### `Agent.init()`
+
+Registers the agent and its current version with the Ezop platform. On subsequent calls with the same `name` + `owner`, the agent record is updated in place — safe to call on every startup.
+
+| Parameter | Required | Description |
+|---|---|---|
+| `name` | yes | Agent name |
+| `owner` | yes | Team or user that owns the agent |
+| `version` | yes | Version string for this deployment (e.g. `"v0.3"`) |
+| `runtime` | yes | Runtime framework (e.g. `"langchain"`, `"langchain"`, `"python"`) |
+| `description` | no | Human-readable description of the agent |
+| `default_permissions` | no | Default permission scopes for the agent |
+| `permissions` | no | Permission scopes for this specific version |
+| `changelog` | no | Release notes for this version |
+
+### `agent.start_run()`
+
+Creates a new run record with status `running`. Call this at the start of each agent invocation.
+
+### `agent.end_run()`
+
+Closes the current run. Only provided fields are written.
+
+| Parameter | Default | Description |
+|---|---|---|
+| `status` | `"completed"` | Final run status (`"completed"`, `"failed"`, etc.) |
+| `total_tokens` | `None` | Total tokens consumed |
+| `total_cost` | `None` | Total cost in USD |
+| `metadata` | `None` | Arbitrary JSON metadata |
+
+## Logging
+
+The SDK uses Python's standard `logging` module under the `ezop` namespace. To enable logs in your application:
+
+```python
+import logging
+logging.getLogger("ezop").setLevel(logging.DEBUG)
+```

ezop-0.0.2/ezop.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+ezop/__init__.py
+ezop/agent.py
+ezop/client.py
+ezop/config.py
+ezop/models.py
+ezop.egg-info/PKG-INFO
+ezop.egg-info/SOURCES.txt
+ezop.egg-info/dependency_links.txt
+ezop.egg-info/requires.txt
+ezop.egg-info/top_level.txt
+tests/test_agent.py
+tests/test_integration.py

ezop-0.0.2/ezop.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ezop-0.0.2/ezop.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests
+
+[dev]
+pytest
+responses
+twine
+build

ezop-0.0.2/ezop.egg-info/top_level.txt

@@ -0,0 +1 @@
+ezop

ezop-0.0.2/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "ezop"
+version = "0.0.2"
+description = "Ezop SDK - The story of every AI agent"
+authors = [{ name = "Ezop", email = "support@ezop.ai" }]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "requests"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "responses",
+    "twine",
+    "build",
+]
+
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"

ezop-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ezop-0.0.2/tests/test_agent.py

@@ -0,0 +1,166 @@
+from unittest.mock import patch, MagicMock
+import pytest
+from ezop import Agent
+from ezop.models import AgentModel, AgentVersion, AgentRun
+
+
+AGENT_RESP = {"success": True, "error": None, "data": {
+    "id": "agent-uuid-123",
+    "name": "support-bot",
+    "owner": "growth-team",
+    "runtime": "langchain",
+    "description": "Handles support tickets",
+    "default_permissions": ["read:tickets"],
+}}
+
+VERSION_RESP = {"success": True, "error": None, "data": {
+    "id": "version-uuid-456",
+    "version": "v0.3",
+    "permissions": ["read:tickets", "write:replies"],
+    "changelog": "Initial release",
+}}
+
+RUN_RESP = {"success": True, "error": None, "data": {
+    "id": "run-uuid-789",
+    "status": "running",
+}}
+
+
+def make_agent():
+    with patch("ezop.client.EzopClient.register_agent", return_value=AGENT_RESP), \
+         patch("ezop.client.EzopClient.create_version", return_value=VERSION_RESP):
+        return Agent.init(
+            name="support-bot",
+            owner="growth-team",
+            version="v0.3",
+            runtime="langchain",
+            description="Handles support tickets",
+            default_permissions=["read:tickets"],
+            permissions=["read:tickets", "write:replies"],
+            changelog="Initial release",
+        )
+
+
+class TestAgentInit:
+    def test_returns_agent_instance(self):
+        agent = make_agent()
+        assert isinstance(agent, Agent)
+
+    def test_model_populated(self):
+        agent = make_agent()
+        assert agent.model.id == "agent-uuid-123"
+        assert agent.model.name == "support-bot"
+        assert agent.model.owner == "growth-team"
+        assert agent.model.runtime == "langchain"
+        assert agent.model.description == "Handles support tickets"
+        assert agent.model.default_permissions == ["read:tickets"]
+
+    def test_version_populated(self):
+        agent = make_agent()
+        assert agent.version.id == "version-uuid-456"
+        assert agent.version.agent_id == "agent-uuid-123"
+        assert agent.version.version == "v0.3"
+        assert agent.version.permissions == ["read:tickets", "write:replies"]
+        assert agent.version.changelog == "Initial release"
+
+    def test_no_active_run_on_init(self):
+        agent = make_agent()
+        assert agent.current_run is None
+
+    def test_calls_register_agent_with_correct_payload(self):
+        with patch("ezop.client.EzopClient.register_agent", return_value=AGENT_RESP) as mock_register, \
+             patch("ezop.client.EzopClient.create_version", return_value=VERSION_RESP):
+            Agent.init(name="support-bot", owner="growth-team", version="v0.3", runtime="langchain",
+                       description="Handles support tickets", default_permissions=["read:tickets"])
+            mock_register.assert_called_once_with({
+                "name": "support-bot",
+                "owner": "growth-team",
+                "runtime": "langchain",
+                "description": "Handles support tickets",
+                "default_permissions": ["read:tickets"],
+            })
+
+    def test_calls_create_version_with_correct_payload(self):
+        with patch("ezop.client.EzopClient.register_agent", return_value=AGENT_RESP), \
+             patch("ezop.client.EzopClient.create_version", return_value=VERSION_RESP) as mock_version:
+            Agent.init(name="support-bot", owner="growth-team", version="v0.3", runtime="langchain",
+                       permissions=["read:tickets"], changelog="Initial release")
+            mock_version.assert_called_once_with("agent-uuid-123", {
+                "version": "v0.3",
+                "permissions": ["read:tickets"],
+                "changelog": "Initial release",
+            })
+
+    def test_optional_fields_default_to_empty(self):
+        with patch("ezop.client.EzopClient.register_agent", return_value={**AGENT_RESP, "data": {**AGENT_RESP["data"], "default_permissions": None}}), \
+             patch("ezop.client.EzopClient.create_version", return_value={**VERSION_RESP, "data": {**VERSION_RESP["data"], "permissions": None}}):
+            agent = Agent.init(name="support-bot", owner="growth-team", version="v0.3", runtime="langchain")
+            assert agent.model.default_permissions == []
+            assert agent.version.permissions == []
+
+    def test_raises_on_api_error(self):
+        with patch("ezop.client.EzopClient.register_agent", side_effect=Exception("Ezop API error: 401")):
+            with pytest.raises(Exception, match="Ezop API error"):
+                Agent.init(name="support-bot", owner="growth-team", version="v0.3", runtime="langchain")
+
+
+class TestAgentRuns:
+    def test_start_run_returns_agent_run(self):
+        agent = make_agent()
+        with patch("ezop.client.EzopClient.start_run", return_value=RUN_RESP):
+            run = agent.start_run()
+        assert isinstance(run, AgentRun)
+        assert run.id == "run-uuid-789"
+        assert run.status == "running"
+        assert run.agent_id == "agent-uuid-123"
+        assert run.version_id == "version-uuid-456"
+
+    def test_start_run_sets_current_run(self):
+        agent = make_agent()
+        with patch("ezop.client.EzopClient.start_run", return_value=RUN_RESP):
+            agent.start_run()
+        assert agent.current_run is not None
+        assert agent.current_run.id == "run-uuid-789"
+
+    def test_end_run_updates_status(self):
+        agent = make_agent()
+        with patch("ezop.client.EzopClient.start_run", return_value=RUN_RESP):
+            agent.start_run()
+        end_resp = {"success": True, "error": None, "data": {"status": "completed", "total_tokens": 500, "total_cost": 0.01, "metadata": None}}
+        with patch("ezop.client.EzopClient.end_run", return_value=end_resp):
+            run = agent.end_run(status="completed", total_tokens=500, total_cost=0.01)
+        assert run.status == "completed"
+        assert run.total_tokens == 500
+        assert run.total_cost == 0.01
+
+    def test_end_run_failed_status(self):
+        agent = make_agent()
+        with patch("ezop.client.EzopClient.start_run", return_value=RUN_RESP):
+            agent.start_run()
+        end_resp = {"success": True, "error": None, "data": {"status": "failed", "total_tokens": None, "total_cost": None, "metadata": {"error": "timeout"}, "message": "Rate limit exceeded"}}
+        with patch("ezop.client.EzopClient.end_run", return_value=end_resp):
+            run = agent.end_run(status="failed", metadata={"error": "timeout"}, message="Rate limit exceeded")
+        assert run.status == "failed"
+        assert run.metadata == {"error": "timeout"}
+        assert run.message == "Rate limit exceeded"
+
+    def test_end_run_calls_client_with_correct_args(self):
+        agent = make_agent()
+        with patch("ezop.client.EzopClient.start_run", return_value=RUN_RESP):
+            agent.start_run()
+        end_resp = {"success": True, "error": None, "data": {"status": "completed", "total_tokens": 100, "total_cost": 0.005, "metadata": {"k": "v"}, "message": None}}
+        with patch("ezop.client.EzopClient.end_run", return_value=end_resp) as mock_end:
+            agent.end_run(status="completed", total_tokens=100, total_cost=0.005, metadata={"k": "v"})
+            mock_end.assert_called_once_with(
+                "run-uuid-789",
+                status="completed",
+                total_tokens=100,
+                total_cost=0.005,
+                metadata={"k": "v"},
+                message=None,
+            )
+
+    def test_end_run_without_start_raises(self):
+        agent = make_agent()
+        with pytest.raises(RuntimeError, match="No active run"):
+            agent.end_run()

ezop-0.0.2/tests/test_integration.py

@@ -0,0 +1,495 @@
+"""
+Integration tests for the Ezop SDK.
+
+These tests use the `responses` library to intercept HTTP calls at the network
+level, exercising the full stack (Agent → EzopClient → requests → HTTP parsing)
+without hitting a real server.
+
+To run against the real Ezop API, set EZOP_API_KEY and EZOP_API_URL in your
+environment and run:
+
+    pytest tests/test_integration.py -m live -v
+
+Live tests are skipped by default unless EZOP_API_KEY is present.
+"""
+
+import pytest
+import responses as responses_lib
+from responses import matchers
+from ezop import Agent
+from ezop.config import Config
+
+
+BASE_URL = Config.EZOP_API_URL
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+_AGENT_DATA = {
+    "id": "integ-agent-001",
+    "name": "integ-bot",
+    "owner": "integ-team",
+    "runtime": "langchain",
+    "description": "Integration test agent",
+    "default_permissions": ["read:logs"],
+}
+
+_VERSION_DATA = {
+    "id": "integ-version-001",
+    "agent_id": "integ-agent-001",
+    "version": "v1.0",
+    "permissions": ["read:logs", "write:reports"],
+    "changelog": "Integration test version",
+}
+
+_RUN_DATA = {
+    "id": "integ-run-001",
+    "status": "running",
+}
+
+_END_RUN_DATA = {
+    "id": "integ-run-001",
+    "status": "completed",
+    "total_tokens": 1200,
+    "total_cost": 0.024,
+    "metadata": None,
+}
+
+
+def _wrap(data):
+    return {"success": True, "data": data, "error": None}
+
+
+AGENT_PAYLOAD = _wrap(_AGENT_DATA)
+VERSION_PAYLOAD = _wrap(_VERSION_DATA)
+RUN_PAYLOAD = _wrap(_RUN_DATA)
+END_RUN_PAYLOAD = _wrap(_END_RUN_DATA)
+
+
+def register_mock_endpoints():
+    """Register all mock HTTP endpoints for a complete agent lifecycle."""
+    responses_lib.add(
+        responses_lib.POST,
+        f"{BASE_URL}/agents/register",
+        json=AGENT_PAYLOAD,
+        status=201,
+    )
+    responses_lib.add(
+        responses_lib.POST,
+        f"{BASE_URL}/agents/integ-agent-001/versions",
+        json=VERSION_PAYLOAD,
+        status=201,
+    )
+    responses_lib.add(
+        responses_lib.POST,
+        f"{BASE_URL}/agents/integ-agent-001/runs",
+        json=RUN_PAYLOAD,
+        status=201,
+    )
+    responses_lib.add(
+        responses_lib.PATCH,
+        f"{BASE_URL}/runs/integ-run-001",
+        json=END_RUN_PAYLOAD,
+        status=200,
+    )
+
+
+# ---------------------------------------------------------------------------
+# HTTP-level integration tests (no real network — responses intercepts)
+# ---------------------------------------------------------------------------
+
+
+class TestAgentInitHTTP:
+    """Verify Agent.init() sends correct HTTP requests and parses responses."""
+
+    @responses_lib.activate
+    def test_register_agent_url_and_method(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json=AGENT_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/versions",
+            json=VERSION_PAYLOAD,
+            status=201,
+        )
+        Agent.init(
+            name="integ-bot", owner="integ-team", version="v1.0", runtime="langchain"
+        )
+        assert responses_lib.calls[0].request.method == "POST"
+        assert responses_lib.calls[0].request.url == f"{BASE_URL}/agents/register"
+
+    @responses_lib.activate
+    def test_register_agent_request_body(self):
+        import json
+
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json=AGENT_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/versions",
+            json=VERSION_PAYLOAD,
+            status=201,
+        )
+        Agent.init(
+            name="integ-bot",
+            owner="integ-team",
+            version="v1.0",
+            runtime="langchain",
+            description="Integration test agent",
+            default_permissions=["read:logs"],
+        )
+        body = json.loads(responses_lib.calls[0].request.body)
+        assert body["name"] == "integ-bot"
+        assert body["owner"] == "integ-team"
+        assert body["runtime"] == "langchain"
+        assert body["description"] == "Integration test agent"
+        assert body["default_permissions"] == ["read:logs"]
+
+    @responses_lib.activate
+    def test_register_agent_auth_header(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json=AGENT_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/versions",
+            json=VERSION_PAYLOAD,
+            status=201,
+        )
+        Agent.init(
+            name="integ-bot", owner="integ-team", version="v1.0", runtime="langchain"
+        )
+        auth = responses_lib.calls[0].request.headers.get("Authorization", "")
+        assert auth.startswith("Bearer ")
+
+    @responses_lib.activate
+    def test_create_version_url_uses_agent_id(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json=AGENT_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/versions",
+            json=VERSION_PAYLOAD,
+            status=201,
+        )
+        Agent.init(
+            name="integ-bot", owner="integ-team", version="v1.0", runtime="langchain"
+        )
+        assert (
+            responses_lib.calls[1].request.url
+            == f"{BASE_URL}/agents/integ-agent-001/versions"
+        )
+
+    @responses_lib.activate
+    def test_create_version_request_body(self):
+        import json
+
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json=AGENT_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/versions",
+            json=VERSION_PAYLOAD,
+            status=201,
+        )
+        Agent.init(
+            name="integ-bot",
+            owner="integ-team",
+            version="v1.0",
+            runtime="langchain",
+            permissions=["read:logs", "write:reports"],
+            changelog="Integration test version",
+        )
+        body = json.loads(responses_lib.calls[1].request.body)
+        assert body["version"] == "v1.0"
+        assert body["permissions"] == ["read:logs", "write:reports"]
+        assert body["changelog"] == "Integration test version"
+
+    @responses_lib.activate
+    def test_agent_built_correctly_from_responses(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json=AGENT_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/versions",
+            json=VERSION_PAYLOAD,
+            status=201,
+        )
+        agent = Agent.init(
+            name="integ-bot",
+            owner="integ-team",
+            version="v1.0",
+            runtime="lanchain",
+            description="Integration test agent",
+            default_permissions=["read:logs"],
+            permissions=["read:logs", "write:reports"],
+            changelog="Integration test version",
+        )
+        assert agent.model.id == "integ-agent-001"
+        assert agent.model.name == "integ-bot"
+        assert agent.model.runtime == "langchain"
+        assert agent.version.id == "integ-version-001"
+        assert agent.version.version == "v1.0"
+        assert agent.version.permissions == ["read:logs", "write:reports"]
+
+    @responses_lib.activate
+    def test_api_400_raises_exception(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json={"error": "invalid payload"},
+            status=400,
+        )
+        with pytest.raises(Exception, match="Ezop API error"):
+            Agent.init(
+                name="integ-bot",
+                owner="integ-team",
+                version="v1.0",
+                runtime="langchain",
+            )
+
+    @responses_lib.activate
+    def test_api_401_raises_exception(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json={"error": "unauthorized"},
+            status=401,
+        )
+        with pytest.raises(Exception, match="Ezop API error"):
+            Agent.init(
+                name="integ-bot",
+                owner="integ-team",
+                version="v1.0",
+                runtime="langchain",
+            )
+
+    @responses_lib.activate
+    def test_api_500_raises_exception(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json={"error": "server error"},
+            status=500,
+        )
+        with pytest.raises(Exception, match="Ezop API error"):
+            Agent.init(
+                name="integ-bot",
+                owner="integ-team",
+                version="v1.0",
+                runtime="langchain",
+            )
+
+
+class TestRunLifecycleHTTP:
+    """Verify start_run / end_run send correct HTTP requests."""
+
+    def _make_agent(self):
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/register",
+            json=AGENT_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/versions",
+            json=VERSION_PAYLOAD,
+            status=201,
+        )
+        return Agent.init(
+            name="integ-bot", owner="integ-team", version="v1.0", runtime="langchain"
+        )
+
+    @responses_lib.activate
+    def test_start_run_url_and_method(self):
+        agent = self._make_agent()
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/runs",
+            json=RUN_PAYLOAD,
+            status=201,
+        )
+        agent.start_run()
+        last_call = responses_lib.calls[-1]
+        assert last_call.request.method == "POST"
+        assert last_call.request.url == f"{BASE_URL}/agents/integ-agent-001/runs"
+
+    @responses_lib.activate
+    def test_start_run_request_body_contains_version_id(self):
+        import json
+
+        agent = self._make_agent()
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/runs",
+            json=RUN_PAYLOAD,
+            status=201,
+        )
+        agent.start_run()
+        body = json.loads(responses_lib.calls[-1].request.body)
+        assert body["version_id"] == "integ-version-001"
+
+    @responses_lib.activate
+    def test_start_run_returns_correct_run(self):
+        agent = self._make_agent()
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/runs",
+            json=RUN_PAYLOAD,
+            status=201,
+        )
+        run = agent.start_run()
+        assert run.id == "integ-run-001"
+        assert run.status == "running"
+        assert run.agent_id == "integ-agent-001"
+        assert run.version_id == "integ-version-001"
+
+    @responses_lib.activate
+    def test_end_run_url_and_method(self):
+        agent = self._make_agent()
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/runs",
+            json=RUN_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.PATCH,
+            f"{BASE_URL}/runs/integ-run-001",
+            json=END_RUN_PAYLOAD,
+            status=200,
+        )
+        agent.start_run()
+        agent.end_run(status="completed", total_tokens=1200, total_cost=0.024)
+        last_call = responses_lib.calls[-1]
+        assert last_call.request.method == "PATCH"
+        assert last_call.request.url == f"{BASE_URL}/runs/integ-run-001"
+
+    @responses_lib.activate
+    def test_end_run_request_body(self):
+        import json
+
+        agent = self._make_agent()
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/runs",
+            json=RUN_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.PATCH,
+            f"{BASE_URL}/runs/integ-run-001",
+            json=END_RUN_PAYLOAD,
+            status=200,
+        )
+        agent.start_run()
+        agent.end_run(
+            status="completed",
+            total_tokens=1200,
+            total_cost=0.024,
+            metadata={"user_id": "u-42"},
+        )
+        body = json.loads(responses_lib.calls[-1].request.body)
+        assert body["status"] == "completed"
+        assert body["total_tokens"] == 1200
+        assert body["total_cost"] == 0.024
+        assert body["metadata"] == {"user_id": "u-42"}
+
+    @responses_lib.activate
+    def test_end_run_body_omits_none_fields(self):
+        import json
+
+        agent = self._make_agent()
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/runs",
+            json=RUN_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.PATCH,
+            f"{BASE_URL}/runs/integ-run-001",
+            json=_wrap(
+                {
+                    "id": "integ-run-001",
+                    "status": "failed",
+                    "total_tokens": None,
+                    "total_cost": None,
+                    "metadata": None,
+                }
+            ),
+            status=200,
+        )
+        agent.start_run()
+        agent.end_run(status="failed")
+        body = json.loads(responses_lib.calls[-1].request.body)
+        assert "total_tokens" not in body
+        assert "total_cost" not in body
+        assert "metadata" not in body
+
+    @responses_lib.activate
+    def test_end_run_updates_agent_state(self):
+        agent = self._make_agent()
+        responses_lib.add(
+            responses_lib.POST,
+            f"{BASE_URL}/agents/integ-agent-001/runs",
+            json=RUN_PAYLOAD,
+            status=201,
+        )
+        responses_lib.add(
+            responses_lib.PATCH,
+            f"{BASE_URL}/runs/integ-run-001",
+            json=END_RUN_PAYLOAD,
+            status=200,
+        )
+        agent.start_run()
+        run = agent.end_run(status="completed", total_tokens=1200, total_cost=0.024)
+        assert run.status == "completed"
+        assert run.total_tokens == 1200
+        assert run.total_cost == 0.024
+
+    @responses_lib.activate
+    def test_full_lifecycle(self):
+        """Agent init → start_run → end_run, exactly 4 HTTP calls."""
+        register_mock_endpoints()
+        agent = Agent.init(
+            name="integ-bot",
+            owner="integ-team",
+            version="v1.0",
+            runtime="langchain",
+            description="Integration test agent",
+            default_permissions=["read:logs"],
+            permissions=["read:logs", "write:reports"],
+            changelog="Integration test version",
+        )
+        run = agent.start_run()
+        assert run.status == "running"
+        result = agent.end_run(status="completed", total_tokens=1200, total_cost=0.024)
+        assert result.status == "completed"
+        assert len(responses_lib.calls) == 4