[back-office] add procedure_id to create_back_office_task

examples/back_office_tasks/run.py

@@ -0,0 +1,36 @@
+import os
+import sys
+import uuid
+import logging
+
+from gradient_labs import (
+    Client,
+    BackOfficeTaskCreateParams,
+    BackOfficeTaskCreateAttachment,
+)
+
+logging.basicConfig(stream=sys.stdout, level=logging.INFO)
+
+client = Client(
+    api_key=os.environ["GLABS_API_KEY"],
+    base_url="http://localhost:4000",
+)
+
+# agent_id is the agent (agent group, prefix `agent_`) that runs the task, and
+# procedure_id is the procedure (prefix `proc_`) within that agent to start from.
+task = client.create_back_office_task(
+    params=BackOfficeTaskCreateParams(
+        id=str(uuid.uuid4()),
+        agent_id="agent_01ham6bzcdeja9xzqhjf6daq30",
+        procedure_id="proc_01ham6bzcdeja9xzqhjf6daq30",
+        input={"order_id": "order-456"},
+        metadata={"team": "billing"},
+        attachments=[
+            BackOfficeTaskCreateAttachment(
+                file_name="document.pdf",
+                url="https://example.com/document.pdf",
+            )
+        ],
+    )
+)
+logging.info(f"✅ Back-office task created: {task.id} (status: {task.status})")

src/gradient_labs/_back_office_task_create.py

@@ -20,7 +20,11 @@ class BackOfficeTaskCreateAttachment:
 @dataclass(frozen=True)
 class BackOfficeTaskCreateParams:
     id: str
+    # agent_id is the agent (agent group, prefix `agent_`) that runs this task.
     agent_id: str
+    # procedure_id is the procedure (prefix `proc_`) within the agent to start the
+    # task from.
+    procedure_id: str
     input: Dict[str, Any]
     created: Optional[datetime] = None
     metadata: Optional[Dict[str, str]] = None
@@ -33,6 +37,7 @@ def create_back_office_task(
     body: Dict[str, Any] = {
         "id": params.id,
         "agent_id": params.agent_id,
+        "procedure_id": params.procedure_id,
         "input": params.input,
     }
     if params.created is not None:

src/gradient_labs/client.py

@@ -114,6 +114,7 @@
 from ._back_office_task_create import (
     create_back_office_task,
     BackOfficeTaskCreateParams,
+    BackOfficeTaskCreateAttachment as BackOfficeTaskCreateAttachment,
 )
 from ._back_office_task_read import read_back_office_task
 
@@ -845,8 +846,11 @@ def read_voice_call_context(
     def create_back_office_task(
         self, *, params: BackOfficeTaskCreateParams
     ) -> BackOfficeTask:
-        """create_back_office_task creates a new back-office task routed to a
-        configurable back-office agent."""
+        """create_back_office_task creates a new back-office task.
+
+        params.agent_id is the agent (agent group, prefix `agent_`) that runs the
+        task, and params.procedure_id is the procedure (prefix `proc_`) within that
+        agent to start the task from."""
         return create_back_office_task(
             client=self.http_client,
             params=params,

tests/test_back_office_task_create.py

@@ -0,0 +1,83 @@
+from datetime import datetime
+from unittest.mock import MagicMock
+
+from gradient_labs import (
+    Client,
+    BackOfficeTask,
+    BackOfficeTaskStatus,
+    BackOfficeTaskCreateParams,
+    BackOfficeTaskCreateAttachment,
+)
+
+AGENT_ID = "agent_01ham6bzcdeja9xzqhjf6daq30"
+PROCEDURE_ID = "proc_01ham6bzcdeja9xzqhjf6daq30"
+
+
+def _client_returning(response: dict):
+    client = Client(api_key="test-key")
+    post = MagicMock(return_value=response)
+    client.http_client.post = post
+    return client, post
+
+
+def _pending_response() -> dict:
+    return {
+        "id": "task-123",
+        "agent_id": AGENT_ID,
+        "status": "pending",
+        "input": {"order_id": "order-456"},
+        "created": "2024-01-15T10:30:00",
+    }
+
+
+def test_create_back_office_task():
+    client, post = _client_returning(_pending_response())
+
+    task = client.create_back_office_task(
+        params=BackOfficeTaskCreateParams(
+            id="task-123",
+            agent_id=AGENT_ID,
+            procedure_id=PROCEDURE_ID,
+            input={"order_id": "order-456"},
+        )
+    )
+
+    _, kwargs = post.call_args
+    body = kwargs["body"]
+    assert kwargs["path"] == "back-office-tasks"
+    assert body["agent_id"] == AGENT_ID
+    assert body["procedure_id"] == PROCEDURE_ID
+    assert body["input"] == {"order_id": "order-456"}
+
+    assert isinstance(task, BackOfficeTask)
+    assert task.agent_id == AGENT_ID
+    assert task.status == BackOfficeTaskStatus.PENDING
+
+
+def test_create_back_office_task_includes_optional_fields():
+    client, post = _client_returning(_pending_response())
+
+    client.create_back_office_task(
+        params=BackOfficeTaskCreateParams(
+            id="task-123",
+            agent_id=AGENT_ID,
+            procedure_id=PROCEDURE_ID,
+            input={"order_id": "order-456"},
+            created=datetime(2024, 1, 15, 10, 30, 0),
+            metadata={"team": "billing"},
+            attachments=[
+                BackOfficeTaskCreateAttachment(
+                    file_name="document.pdf",
+                    url="https://example.com/document.pdf",
+                )
+            ],
+        )
+    )
+
+    _, kwargs = post.call_args
+    body = kwargs["body"]
+    assert body["procedure_id"] == PROCEDURE_ID
+    assert body["metadata"] == {"team": "billing"}
+    assert body["created"] == "2024-01-15T10:30:00.000000Z"
+    assert body["attachments"][0]["file_name"] == "document.pdf"
+    assert body["attachments"][0]["url"] == "https://example.com/document.pdf"