[SILO-766] feat: add Agent Runs API and related models, activities, and tests (#13)

Author: Saurabhkmr98

.gitignore

@@ -49,6 +49,7 @@ venv/
 .env
 .python-version
 .pytest_cache
+.env
 
 # Translations
 *.mo

plane/__init__.py

@@ -1,3 +1,4 @@
+from .api.agent_runs import AgentRuns
 from .api.cycles import Cycles
 from .api.initiatives import Initiatives
 from .api.labels import Labels
@@ -28,6 +29,7 @@
     "PlaneClient",
     "OAuthClient",
     "Configuration",
+    "AgentRuns",
     "WorkItems",
     "WorkItemTypes",
     "WorkItemProperties",

plane/api/agent_runs/__init__.py

@@ -0,0 +1,4 @@
+from .base import AgentRuns
+
+__all__ = ["AgentRuns"]
+

plane/api/agent_runs/activities.py

@@ -0,0 +1,85 @@
+from collections.abc import Mapping
+from typing import Any
+
+from ...models.agent_runs import (
+    AgentRunActivity,
+    CreateAgentRunActivity,
+    PaginatedAgentRunActivityResponse,
+)
+from ..base_resource import BaseResource
+
+
+class AgentRunActivities(BaseResource):
+    """Agent Run Activities API resource.
+
+    Handles all agent run activity operations.
+    """
+
+    def __init__(self, config: Any) -> None:
+        super().__init__(config, "/workspaces/")
+
+    def list(
+        self,
+        workspace_slug: str,
+        run_id: str,
+        params: Mapping[str, Any] | None = None,
+    ) -> PaginatedAgentRunActivityResponse:
+        """List activities for an agent run.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            run_id: UUID of the agent run
+            params: Optional query parameters for pagination (per_page, cursor)
+
+        Returns:
+            Paginated list of agent run activities
+        """
+        response = self._get(
+            f"{workspace_slug}/runs/{run_id}/activities",
+            params=params,
+        )
+        return PaginatedAgentRunActivityResponse.model_validate(response)
+
+    def retrieve(
+        self,
+        workspace_slug: str,
+        run_id: str,
+        activity_id: str,
+    ) -> AgentRunActivity:
+        """Retrieve a specific agent run activity by ID.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            run_id: UUID of the agent run
+            activity_id: UUID of the activity
+
+        Returns:
+            The agent run activity
+        """
+        response = self._get(
+            f"{workspace_slug}/runs/{run_id}/activities/{activity_id}"
+        )
+        return AgentRunActivity.model_validate(response)
+
+    def create(
+        self,
+        workspace_slug: str,
+        run_id: str,
+        data: CreateAgentRunActivity,
+    ) -> AgentRunActivity:
+        """Create a new agent run activity.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            run_id: UUID of the agent run
+            data: The activity data to create
+
+        Returns:
+            The created agent run activity
+        """
+        response = self._post(
+            f"{workspace_slug}/runs/{run_id}/activities",
+            data.model_dump(exclude_none=True),
+        )
+        return AgentRunActivity.model_validate(response)
+

plane/api/agent_runs/base.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+from ...models.agent_runs import AgentRun, CreateAgentRun
+from ..base_resource import BaseResource
+from .activities import AgentRunActivities
+
+
+class AgentRuns(BaseResource):
+    """Agent Runs API resource.
+
+    Handles all agent run operations.
+    """
+
+    def __init__(self, config: Any) -> None:
+        super().__init__(config, "/workspaces/")
+
+        # Initialize sub-resources
+        self.activities = AgentRunActivities(config)
+
+    def create(
+        self,
+        workspace_slug: str,
+        data: CreateAgentRun,
+    ) -> AgentRun:
+        """Create a new agent run.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            data: The agent run data to create
+
+        Returns:
+            The created agent run
+        """
+        response = self._post(
+            f"{workspace_slug}/runs",
+            data.model_dump(exclude_none=True),
+        )
+        return AgentRun.model_validate(response)
+
+    def retrieve(
+        self,
+        workspace_slug: str,
+        run_id: str,
+    ) -> AgentRun:
+        """Retrieve an agent run by ID.
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            run_id: UUID of the agent run
+
+        Returns:
+            The agent run
+        """
+        response = self._get(f"{workspace_slug}/runs/{run_id}")
+        return AgentRun.model_validate(response)

plane/client/plane_client.py

@@ -1,3 +1,4 @@
+from ..api.agent_runs import AgentRuns
 from ..api.customers import Customers
 from ..api.cycles import Cycles
 from ..api.epics import Epics
@@ -56,6 +57,7 @@ def __init__(
         self.work_item_properties = WorkItemProperties(self.config)
         self.customers = Customers(self.config)
         self.intake = Intake(self.config)
+        self.agent_runs = AgentRuns(self.config)
         self.stickies = Stickies(self.config)
         self.initiatives = Initiatives(self.config)
         self.teamspaces = Teamspaces(self.config)

plane/models/agent_runs.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AgentRunStatus(str, Enum):
+    """Agent run status enum."""
+
+    CREATED = "created"
+    IN_PROGRESS = "in_progress"
+    AWAITING = "awaiting"
+    COMPLETED = "completed"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    FAILED = "failed"
+    STALE = "stale"
+
+
+class AgentRunType(str, Enum):
+    """Agent run type enum."""
+
+    COMMENT_THREAD = "comment_thread"
+
+
+class AgentRunActivitySignal(str, Enum):
+    """Agent run activity signal enum."""
+
+    AUTH_REQUEST = "auth_request"
+    CONTINUE = "continue"
+    SELECT = "select"
+    STOP = "stop"
+
+
+class AgentRunActivityType(str, Enum):
+    """Agent run activity type enum."""
+
+    ACTION = "action"
+    ELICITATION = "elicitation"
+    ERROR = "error"
+    PROMPT = "prompt"
+    RESPONSE = "response"
+    THOUGHT = "thought"
+
+
+class AgentRun(BaseModel):
+    """Agent Run model."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    id: str
+    agent_user: str
+    comment: str | None = None
+    source_comment: str | None = None
+    creator: str
+    stopped_at: str | None = None
+    stopped_by: str | None = None
+    started_at: str
+    ended_at: str | None = None
+    external_link: str | None = None
+    issue: str | None = None
+    workspace: str
+    project: str | None = None
+    status: AgentRunStatus
+    error_metadata: dict[str, Any] | None = None
+    type: AgentRunType
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class CreateAgentRun(BaseModel):
+    """Create agent run request model."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    agent_slug: str
+    issue: str | None = None
+    project: str | None = None
+    comment: str | None = None
+    source_comment: str | None = None
+    external_link: str | None = None
+    type: AgentRunType | None = None
+
+
+class AgentRunActivityActionContent(BaseModel):
+    """Agent run activity content for action type."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: Literal["action"]
+    action: str
+    parameters: dict[str, str]
+
+
+class AgentRunActivityTextContent(BaseModel):
+    """Agent run activity content for non-action types."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    type: Literal["elicitation", "error", "prompt", "response", "thought"]
+    body: str
+
+
+AgentRunActivityContent = AgentRunActivityActionContent | AgentRunActivityTextContent
+
+
+class AgentRunActivity(BaseModel):
+    """Agent Run Activity model."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    id: str
+    agent_run: str
+    content: AgentRunActivityContent
+    content_metadata: dict[str, Any] | None = None
+    ephemeral: bool
+    signal: AgentRunActivitySignal
+    signal_metadata: dict[str, Any] | None = None
+    comment: str | None = None
+    actor: str | None = None
+    type: AgentRunActivityType
+    project: str | None = None
+    workspace: str
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class CreateAgentRunActivity(BaseModel):
+    """Create agent run activity request model."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    content: AgentRunActivityContent
+    content_metadata: dict[str, Any] | None = None
+    signal: AgentRunActivitySignal | None = None
+    signal_metadata: dict[str, Any] | None = None
+    type: Literal["action", "elicitation", "error", "response", "thought"]
+    project: str | None = None
+
+
+class PaginatedAgentRunActivityResponse(BaseModel):
+    """Paginated agent run activity response."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    results: list[AgentRunActivity]
+    next_cursor: str | None = None
+    prev_cursor: str | None = None
+    next_page_results: bool | None = None
+    prev_page_results: bool | None = None
+    count: int | None = None
+    total_pages: int | None = None
+    total_results: int | None = None
+    extra_stats: dict[str, Any] | None = None
+

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plane-sdk"
-version = "0.2.3"
+version = "0.2.4"
 description = "Python SDK for Plane API"
 readme = "README.md"
 requires-python = ">=3.10"

tests/unit/conftest.py

@@ -6,7 +6,9 @@
 import pytest
 
 from plane.client import PlaneClient
+from plane.models.agent_runs import AgentRun, CreateAgentRun
 from plane.models.projects import CreateProject, Project
+from plane.models.work_items import CreateWorkItem, CreateWorkItemComment
 
 
 @pytest.fixture(scope="session")
@@ -73,3 +75,31 @@ def project(client: PlaneClient, workspace_slug: str) -> Project:
         client.projects.delete(workspace_slug, project.id)
     except Exception:
         pass
+
+
+@pytest.fixture(scope="session")
+def agent_run(client: PlaneClient, workspace_slug: str, project: Project) -> AgentRun:
+    agent_slug = os.getenv("AGENT_SLUG")
+    if not agent_slug:
+        pytest.skip("AGENT_SLUG environment variable not set")
+    """Create a test agent run and yield it."""
+    work_item = client.work_items.create(
+        workspace_slug,
+        project.id,
+        CreateWorkItem(name="Test Work Item"),
+    )
+    comment = client.work_items.comments.create(
+        workspace_slug,
+        project.id,
+        work_item.id,
+        CreateWorkItemComment(comment_html="<p>This is a test comment</p>"),
+    )
+    agent_run = client.agent_runs.create(
+        workspace_slug,
+        CreateAgentRun(
+            agent_slug=agent_slug,
+            project=project.id,
+            comment=comment.id,
+        ),
+    )
+    yield agent_run