agents24 0.1.0__py3-none-any.whl

agents24/__init__.py

@@ -0,0 +1,10 @@
+from .builders import AgentDefinitionBuilder, GraphBuilder
+from .client import Agents24
+from .errors import Agents24SDKError
+
+__all__ = [
+    "AgentDefinitionBuilder",
+    "Agents24",
+    "Agents24SDKError",
+    "GraphBuilder",
+]

agents24/artifacts.py

@@ -0,0 +1,60 @@
+_EXPORTS = []
+
+
+def _json_schema(value):
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return value
+    if hasattr(value, "model_json_schema"):
+        return value.model_json_schema()
+    if hasattr(value, "schema"):
+        return value.schema()
+    raise TypeError("schema must be a JSON Schema dict or a Pydantic model")
+
+
+def _register(kind, fn=None, **options):
+    def decorate(handler):
+        name = str(options.get("name") or handler.__name__).strip()
+        _EXPORTS.append(
+            {
+                "name": name,
+                "kind": kind,
+                "description": options.get("description") or getattr(handler, "__doc__", None),
+                "input_schema": _json_schema(options.get("input_schema") or options.get("input")),
+                "output_schema": _json_schema(options.get("output_schema") or options.get("output")),
+                "config_schema": _json_schema(options.get("config_schema") or options.get("config")),
+                "ui_schema": dict(options.get("ui_schema") or options.get("ui") or {}),
+                "side_effects": list(options.get("side_effects") or []),
+                "execution_mode": options.get("execution_mode") or "interactive",
+                "handler_ref": options.get("handler_ref") or handler.__name__,
+            }
+        )
+        return handler
+
+    if callable(fn):
+        return decorate(fn)
+    return decorate
+
+
+def tool(fn=None, **options):
+    return _register("tool", fn, **options)
+
+
+def agent_node(fn=None, **options):
+    return _register("agent_node", fn, **options)
+
+
+def rag_operator(fn=None, **options):
+    return _register("rag_operator", fn, **options)
+
+
+def artifact(*, exports=None):
+    for item in exports or []:
+        if isinstance(item, dict):
+            _EXPORTS.append(item)
+    return {"exports": _EXPORTS}
+
+
+def describe_exports():
+    return list(_EXPORTS)

agents24/builders.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+def _ref_id(ref: str | Mapping[str, Any]) -> str:
+    return ref if isinstance(ref, str) else str(ref["id"])
+
+
+def _normalize_refs(refs: list[str | Mapping[str, Any]] | None) -> list[str]:
+    seen: list[str] = []
+    for ref in refs or []:
+        value = _ref_id(ref)
+        if value and value not in seen:
+            seen.append(value)
+    return seen
+
+
+class AgentDefinitionBuilder:
+    def __init__(self, agents: Any, options: Mapping[str, Any]) -> None:
+        self._agents = agents
+        self._options = dict(options)
+
+    def to_graph(self) -> dict[str, Any]:
+        model = self._options.get("model")
+        config: dict[str, Any] = {
+            "instructions": self._options.get("instructions") or "",
+            "tools": _normalize_refs(self._options.get("tools")),
+            "toolsets": _normalize_refs(self._options.get("toolsets")),
+        }
+        if model:
+            config["model_id"] = _ref_id(model)
+        return {
+            "spec_version": "4.0",
+            "workflow_contract": {"inputs": []},
+            "state_contract": {"variables": []},
+            "nodes": [
+                {"id": "start", "type": "start", "position": {"x": 0, "y": 0}, "config": {}},
+                {"id": "agent", "type": "agent", "position": {"x": 260, "y": 0}, "config": config},
+                {"id": "end", "type": "end", "position": {"x": 520, "y": 0}, "config": {}},
+            ],
+            "edges": [
+                {"id": "start-agent", "source": "start", "target": "agent", "type": "control"},
+                {"id": "agent-end", "source": "agent", "target": "end", "type": "control"},
+            ],
+        }
+
+    def to_create_request(self) -> dict[str, Any]:
+        knowledge_refs = _normalize_refs(self._options.get("knowledge"))
+        memory = dict(self._options.get("memory") or {})
+        if knowledge_refs:
+            memory.update(
+                {
+                    "long_term_enabled": True,
+                    "long_term_index_id": knowledge_refs[0],
+                    "knowledge_refs": knowledge_refs,
+                }
+            )
+        return {
+            "name": self._options["name"],
+            "description": self._options.get("description"),
+            "graph_definition": self.to_graph(),
+            "memory_config": memory,
+            "execution_constraints": dict(self._options.get("execution") or {}),
+        }
+
+    def create(self, options: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._agents.create(self.to_create_request(), options=options)
+
+
+class GraphBuilder:
+    def __init__(self) -> None:
+        self._nodes: dict[str, dict[str, Any]] = {}
+        self._edges: list[dict[str, Any]] = []
+
+    def node(
+        self,
+        type_: str,
+        config: Mapping[str, Any] | None = None,
+        *,
+        id: str | None = None,
+        x: int | float | None = None,
+        y: int | float | None = None,
+        label: str | None = None,
+    ) -> dict[str, Any]:
+        node_id = id or f"{type_}_{len(self._nodes) + 1}"
+        if node_id in self._nodes:
+            raise ValueError(f"Duplicate graph node id: {node_id}")
+        node = {
+            "id": node_id,
+            "type": type_,
+            "position": {"x": x if x is not None else len(self._nodes) * 260, "y": y if y is not None else 0},
+            "config": dict(config or {}),
+        }
+        if label:
+            node["label"] = label
+        self._nodes[node_id] = node
+        return node
+
+    def connect(
+        self,
+        source: str | Mapping[str, Any],
+        target: str | Mapping[str, Any],
+        *,
+        id: str | None = None,
+        source_handle: str | None = None,
+        target_handle: str | None = None,
+    ) -> "GraphBuilder":
+        source_id = source if isinstance(source, str) else str(source["id"])
+        target_id = target if isinstance(target, str) else str(target["id"])
+        if source_id not in self._nodes:
+            raise ValueError(f"Unknown source node id: {source_id}")
+        if target_id not in self._nodes:
+            raise ValueError(f"Unknown target node id: {target_id}")
+        edge = {"id": id or f"{source_id}-{target_id}", "source": source_id, "target": target_id, "type": "control"}
+        if source_handle:
+            edge["source_handle"] = source_handle
+        if target_handle:
+            edge["target_handle"] = target_handle
+        self._edges.append(edge)
+        return self
+
+    def to_graph(self) -> dict[str, Any]:
+        return {
+            "spec_version": "4.0",
+            "workflow_contract": {"inputs": []},
+            "state_contract": {"variables": []},
+            "nodes": list(self._nodes.values()),
+            "edges": list(self._edges),
+        }

agents24/client.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import requests
+
+from .builders import AgentDefinitionBuilder, GraphBuilder
+from .generated.agents import AgentsNamespace
+from .generated.embed import EmbedNamespace
+from .generated.runs import GeneratedRunsNamespace
+from .http import Agents24HttpClient
+
+
+class RunsNamespace(GeneratedRunsNamespace):
+    def get_trace(self, run_id: str) -> dict[str, Any]:
+        return {
+            "run": self.get(run_id),
+            "tree": self.get_tree(run_id),
+            "events": self.get_events(run_id),
+            "context": self.get_context(run_id),
+        }
+
+
+class Agents24:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        organization_id: str | None = None,
+        project_id: str | None = None,
+        timeout: float = 30.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        self._http = Agents24HttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            organization_id=organization_id,
+            project_id=project_id,
+            timeout=timeout,
+            session=session,
+        )
+        self.agents = AgentsNamespace(self._http)
+        self.embed = EmbedNamespace(self._http)
+        self.runs = RunsNamespace(self._http)
+
+    def agent(self, options: Mapping[str, Any]) -> AgentDefinitionBuilder:
+        return AgentDefinitionBuilder(self.agents, options)
+
+    def graph(self) -> GraphBuilder:
+        return GraphBuilder()

agents24/errors.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class Agents24SDKError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        kind: str,
+        status: int | None = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.kind = kind
+        self.status = status
+        self.details = details

agents24/generated/__init__.py

@@ -0,0 +1,3 @@
+from .manifest import SDK_OPERATION_IDS
+
+__all__ = ["SDK_OPERATION_IDS"]

agents24/generated/agents.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Sequence
+
+from ..errors import Agents24SDKError
+from ..http import Agents24HttpClient
+from ..types import AgentListResponse, AgentResponse, AttachmentUploadResult, RequestOptions, RunCancelResult, RuntimeEvent, StartRunResult, StreamResult
+
+class AgentsNamespace:
+    def __init__(self, http: Agents24HttpClient) -> None:
+        self._http = http
+
+    def list(self, status: str | None = None, skip: int = 0, limit: int = 20, view: str = "summary") -> AgentListResponse:
+        return self._http.request_json("GET", "/agents", params={
+            "status": status,
+            "skip": skip if skip is not None else 0,
+            "limit": limit if limit is not None else 20,
+            "view": view if view is not None else "summary",
+        }, json_body=None, options=None, mutation=False)
+
+    def get(self, agent_id: str) -> AgentResponse:
+        return self._http.request_json("GET", f"/agents/{agent_id}", params=None, json_body=None, options=None, mutation=False)
+
+    def create(self, request: Mapping[str, Any], options: RequestOptions | None = None) -> AgentResponse:
+        return self._http.request_json("POST", "/agents", params=None, json_body=request, options=options, mutation=True)
+
+    def update(self, agent_id: str, request: Mapping[str, Any], options: RequestOptions | None = None) -> AgentResponse:
+        return self._http.request_json("PATCH", f"/agents/{agent_id}", params=None, json_body=request, options=options, mutation=True)
+
+    def update_graph(self, agent_id: str, graph: Mapping[str, Any], options: RequestOptions | None = None) -> AgentResponse:
+        return self._http.request_json("PUT", f"/agents/{agent_id}/graph", params=None, json_body=graph, options=options, mutation=True)
+
+    def delete(self, agent_id: str, options: RequestOptions | None = None) -> Any:
+        return self._http.request_json("DELETE", f"/agents/{agent_id}", params=None, json_body=None, options=options, mutation=True)
+
+    def catalog(self) -> Any:
+        return self._http.request_json("GET", "/agents/nodes/catalog", params=None, json_body=None, options=None, mutation=False)
+
+    def schema(self, node_types: Any) -> Any:
+        return self._http.request_json("POST", "/agents/nodes/schema", params=None, json_body={
+            "node_types": node_types,
+        }, options=None, mutation=False)
+
+    def validate(self, agent_id: str) -> Any:
+        return self._http.request_json("POST", f"/agents/{agent_id}/validate", params=None, json_body={}, options=None, mutation=False)
+
+    def publish(self, agent_id: str, options: RequestOptions | None = None) -> AgentResponse:
+        return self._http.request_json("POST", f"/agents/{agent_id}/publish", params=None, json_body={}, options=options, mutation=True)
+
+    def start_run(self, agent_id: str, payload: Mapping[str, Any], options: RequestOptions | None = None) -> StartRunResult:
+        return self._http.request_json("POST", f"/agents/{agent_id}/run", params=None, json_body=payload, options=options, mutation=True)
+
+    def stream(self, agent_id: str, payload: Mapping[str, Any], on_event: Callable[[RuntimeEvent], None] | None = None, mode: str | None = None) -> StreamResult:
+        return self._http.request_stream("POST", f"/agents/{agent_id}/stream", json_body=dict(payload), params={"mode": mode}, on_event=on_event)
+
+    def resume_run(self, run_id: str, payload: Mapping[str, Any], options: RequestOptions | None = None) -> Any:
+        return self._http.request_json("POST", f"/agents/runs/{run_id}/resume", params=None, json_body=payload, options=options, mutation=True)
+
+    def cancel_run(self, run_id: str, assistant_output_text: str | None = None) -> RunCancelResult:
+        return self._http.request_json("POST", f"/agents/runs/{run_id}/cancel", params=None, json_body={
+            "assistant_output_text": assistant_output_text,
+        }, options=None, mutation=True)
+
+    def upload_attachments(self, agent_id: str, files: Sequence[Any], thread_id: str | None = None) -> AttachmentUploadResult:
+        return self._http.request_multipart("POST", f"/agents/{agent_id}/attachments/upload", data={
+            "thread_id": thread_id,
+        }, files=files)

agents24/generated/embed.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Sequence
+
+from ..errors import Agents24SDKError
+from ..http import Agents24HttpClient
+from ..types import AttachmentUploadResult, RequestOptions, RunCancelResult, RunContext, RuntimeEvent, StreamResult, ThreadDeleteResult, ThreadDetail, ThreadsResponse
+
+class EmbedNamespace:
+    def __init__(self, http: Agents24HttpClient) -> None:
+        self._http = http
+
+    def stream_agent(self, agent_id: str, payload: Mapping[str, Any], on_event: Callable[[RuntimeEvent], None] | None = None) -> StreamResult:
+        return self._http.request_stream("POST", f"/public/embed/agents/{agent_id}/chat/stream", json_body=dict(payload), params=None, on_event=on_event)
+
+    def list_agent_threads(self, agent_id: str, external_user_id: Any = None, external_session_id: Any = None, skip: Any = 0, limit: Any = 20) -> ThreadsResponse:
+        return self._http.request_json("GET", f"/public/embed/agents/{agent_id}/threads", params={
+            "external_user_id": external_user_id,
+            "external_session_id": external_session_id,
+            "skip": skip if skip is not None else 0,
+            "limit": limit if limit is not None else 20,
+        }, json_body=None, options=None, mutation=False)
+
+    def get_agent_thread(self, agent_id: str, thread_id: str, external_user_id: Any = None, external_session_id: Any = None, before_turn_index: Any = None, limit: Any = None, include_subthreads: Any = None, subthread_depth: Any = None, subthread_turn_limit: Any = None, subthread_child_limit: Any = None) -> ThreadDetail:
+        return self._http.request_json("GET", f"/public/embed/agents/{agent_id}/threads/{thread_id}", params={
+            "external_user_id": external_user_id,
+            "external_session_id": external_session_id,
+            "before_turn_index": before_turn_index,
+            "limit": limit,
+            "include_subthreads": include_subthreads,
+            "subthread_depth": subthread_depth,
+            "subthread_turn_limit": subthread_turn_limit,
+            "subthread_child_limit": subthread_child_limit,
+        }, json_body=None, options=None, mutation=False)
+
+    def delete_agent_thread(self, agent_id: str, thread_id: str, external_user_id: Any = None, external_session_id: Any = None, options: RequestOptions | None = None) -> ThreadDeleteResult:
+        return self._http.request_json("DELETE", f"/public/embed/agents/{agent_id}/threads/{thread_id}", params={
+            "external_user_id": external_user_id,
+            "external_session_id": external_session_id,
+        }, json_body=None, options=options, mutation=True)
+
+    def get_agent_run_context(self, agent_id: str, run_id: str, external_user_id: Any = None, external_session_id: Any = None) -> RunContext:
+        return self._http.request_json("GET", f"/public/embed/agents/{agent_id}/runs/{run_id}/context", params={
+            "external_user_id": external_user_id,
+            "external_session_id": external_session_id,
+        }, json_body=None, options=None, mutation=False)
+
+    def cancel_agent_run(self, agent_id: str, run_id: str, external_user_id: Any = None, external_session_id: Any = None, assistant_output_text: str | None = None) -> RunCancelResult:
+        return self._http.request_json("POST", f"/public/embed/agents/{agent_id}/runs/{run_id}/cancel", params={
+            "external_user_id": external_user_id,
+            "external_session_id": external_session_id,
+        }, json_body={
+            "assistant_output_text": assistant_output_text,
+        }, options=None, mutation=True)
+
+    def upload_agent_attachments(self, agent_id: str, files: Sequence[Any], external_user_id: str | None = None, external_session_id: str | None = None, thread_id: str | None = None) -> AttachmentUploadResult:
+        if not external_user_id:
+            raise Agents24SDKError("upload_agent_attachments requires external_user_id.", kind="protocol")
+        return self._http.request_multipart("POST", f"/public/embed/agents/{agent_id}/attachments/upload", data={
+            "external_user_id": external_user_id,
+            "external_session_id": external_session_id,
+            "thread_id": thread_id,
+        }, files=files)

agents24/generated/manifest.py

@@ -0,0 +1,28 @@
+SDK_OPERATION_IDS = [
+  "agents.cancel_run",
+  "agents.catalog",
+  "agents.create",
+  "agents.delete",
+  "agents.get",
+  "agents.list",
+  "agents.publish",
+  "agents.resume_run",
+  "agents.schema",
+  "agents.start_run",
+  "agents.stream",
+  "agents.update",
+  "agents.update_graph",
+  "agents.upload_attachments",
+  "agents.validate",
+  "embed.cancel_agent_run",
+  "embed.delete_agent_thread",
+  "embed.get_agent_run_context",
+  "embed.get_agent_thread",
+  "embed.list_agent_threads",
+  "embed.stream_agent",
+  "embed.upload_agent_attachments",
+  "runs.get",
+  "runs.get_context",
+  "runs.get_events",
+  "runs.get_tree"
+]

agents24/generated/runs.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping, Sequence
+
+from ..errors import Agents24SDKError
+from ..http import Agents24HttpClient
+from ..types import RequestOptions, RunContext, RunEventsResponse, RunStatus
+
+class GeneratedRunsNamespace:
+    def __init__(self, http: Agents24HttpClient) -> None:
+        self._http = http
+
+    def get(self, run_id: str, include_tree: bool | None = None) -> RunStatus:
+        return self._http.request_json("GET", f"/agents/runs/{run_id}", params={
+            "include_tree": include_tree,
+        }, json_body=None, options=None, mutation=False)
+
+    def get_tree(self, run_id: str) -> Any:
+        return self._http.request_json("GET", f"/agents/runs/{run_id}/tree", params=None, json_body=None, options=None, mutation=False)
+
+    def get_events(self, run_id: str, after_sequence: int | None = None, limit: int | None = None) -> RunEventsResponse:
+        return self._http.request_json("GET", f"/agents/runs/{run_id}/events", params={
+            "after_sequence": after_sequence,
+            "limit": limit,
+        }, json_body=None, options=None, mutation=False)
+
+    def get_context(self, run_id: str) -> RunContext:
+        return self._http.request_json("GET", f"/agents/runs/{run_id}/context", params=None, json_body=None, options=None, mutation=False)

agents24/http.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import Mapping, Sequence
+from typing import Any, Callable
+
+import requests
+
+from .errors import Agents24SDKError
+from .sse import consume_event_stream
+from .types import RequestOptions, RuntimeEvent, StreamResult
+
+
+class Agents24HttpClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        organization_id: str | None = None,
+        project_id: str | None = None,
+        timeout: float = 30.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        self.base_url = self._normalize_base_url(base_url)
+        self.api_key = str(api_key or "").strip()
+        if not self.api_key:
+            raise Agents24SDKError("Agents24 requires a non-empty api_key.", kind="protocol")
+        self.organization_id = str(organization_id) if organization_id else None
+        self.project_id = str(project_id) if project_id else None
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    @staticmethod
+    def _normalize_base_url(base_url: str) -> str:
+        normalized = str(base_url or "").strip().rstrip("/")
+        if not normalized or "://" not in normalized:
+            raise Agents24SDKError("Agents24 requires a valid base_url.", kind="protocol")
+        return normalized
+
+    def _headers(
+        self,
+        *,
+        accept: str = "application/json",
+        content_type: str | None = "application/json",
+        mutation: bool = False,
+        options: RequestOptions | None = None,
+    ) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": accept,
+            "X-SDK-Contract": "1",
+        }
+        if content_type:
+            headers["Content-Type"] = content_type
+        if self.organization_id:
+            headers["X-Organization-ID"] = self.organization_id
+        if self.project_id:
+            headers["X-Project-ID"] = self.project_id
+        if mutation:
+            headers["X-Idempotency-Key"] = (options or {}).get("idempotency_key") or str(uuid.uuid4())
+        metadata = (options or {}).get("request_metadata")
+        if metadata:
+            headers["X-Request-Metadata"] = json.dumps(metadata, separators=(",", ":"))
+        return headers
+
+    @staticmethod
+    def _params(params: Mapping[str, Any] | None, options: RequestOptions | None = None) -> dict[str, Any]:
+        merged = {k: v for k, v in dict(params or {}).items() if v not in (None, "")}
+        if options and "dry_run" in options:
+            merged["dry_run"] = bool(options["dry_run"])
+        if options and "validate_only" in options:
+            merged["validate_only"] = bool(options["validate_only"])
+        return merged
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_body: Any = None,
+        options: RequestOptions | None = None,
+        mutation: bool = False,
+    ) -> Any:
+        try:
+            response = self.session.request(
+                method=method,
+                url=f"{self.base_url}{path}",
+                params=self._params(params, options),
+                json=json_body,
+                headers=self._headers(mutation=mutation, options=options),
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise Agents24SDKError("Failed to connect to the Agents24 API.", kind="network") from exc
+        self._raise_for_status(response)
+        if response.text:
+            return response.json()
+        return None
+
+    def request_multipart(
+        self,
+        method: str,
+        path: str,
+        *,
+        data: Mapping[str, Any],
+        files: Sequence[Any],
+    ) -> Any:
+        form_data = {k: v for k, v in dict(data or {}).items() if v not in (None, "")}
+        try:
+            response = self.session.request(
+                method=method,
+                url=f"{self.base_url}{path}",
+                data=form_data,
+                files={"files": files} if files and not isinstance(files[0], tuple) else list(files),
+                headers=self._headers(content_type=None),
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise Agents24SDKError("Failed to connect to the Agents24 attachment endpoint.", kind="network") from exc
+        self._raise_for_status(response)
+        return response.json()
+
+    def request_stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Mapping[str, Any],
+        params: Mapping[str, Any] | None,
+        on_event: Callable[[RuntimeEvent], None] | None,
+    ) -> StreamResult:
+        try:
+            response = self.session.request(
+                method=method,
+                url=f"{self.base_url}{path}",
+                params=self._params(params),
+                json=dict(json_body),
+                headers=self._headers(accept="text/event-stream"),
+                timeout=self.timeout,
+                stream=True,
+            )
+        except requests.RequestException as exc:
+            raise Agents24SDKError("Failed to connect to the Agents24 stream endpoint.", kind="network") from exc
+        self._raise_for_status(response)
+        observed_run_id = response.headers.get("X-Run-ID")
+        for event in consume_event_stream(response.iter_lines(decode_unicode=True)):
+            observed_run_id = observed_run_id or event["run_id"]
+            if on_event:
+                on_event(event)
+        return {
+            "thread_id": response.headers.get("X-Thread-ID"),
+            "run_id": observed_run_id,
+        }
+
+    @staticmethod
+    def _raise_for_status(response: requests.Response) -> None:
+        if response.status_code < 400:
+            return
+        details: Any
+        try:
+            details = response.json()
+        except Exception:
+            details = response.text
+        message = response.reason or "Request failed"
+        if isinstance(details, dict):
+            detail = details.get("detail")
+            if isinstance(detail, str):
+                message = detail
+            elif isinstance(detail, dict) and isinstance(detail.get("message"), str):
+                message = detail["message"]
+            elif isinstance(details.get("message"), str):
+                message = details["message"]
+        elif isinstance(details, str) and details:
+            message = details
+        raise Agents24SDKError(message, kind="http", status=response.status_code, details=details)

agents24/sse.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable
+
+from .errors import Agents24SDKError
+from .types import RuntimeEvent
+
+
+def _parse_sse_block(block: str) -> str | None:
+    data_lines: list[str] = []
+    for raw_line in block.split("\n"):
+        line = raw_line.rstrip("\r")
+        if not line or line.startswith(":"):
+            continue
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+        if field == "data":
+            data_lines.append(value)
+    return "\n".join(data_lines) if data_lines else None
+
+
+def parse_runtime_event(raw_payload: str) -> RuntimeEvent:
+    try:
+        parsed = json.loads(raw_payload)
+    except Exception as exc:
+        raise Agents24SDKError("Malformed SSE event: invalid JSON payload.", kind="protocol", details=raw_payload) from exc
+    if not isinstance(parsed, dict) or parsed.get("version") != "run-stream.v2":
+        raise Agents24SDKError("SSE protocol mismatch: expected run-stream.v2 event envelopes.", kind="protocol", details=parsed)
+    for field in ("seq", "ts", "event", "run_id", "stage"):
+        if field not in parsed:
+            raise Agents24SDKError("Malformed SSE event: missing required envelope fields.", kind="protocol", details=parsed)
+    payload = parsed.get("payload") or {}
+    diagnostics = parsed.get("diagnostics") or []
+    if not isinstance(payload, dict) or not isinstance(diagnostics, list):
+        raise Agents24SDKError("Malformed SSE event payload.", kind="protocol", details=parsed)
+    parsed["payload"] = payload
+    parsed["diagnostics"] = diagnostics
+    return parsed  # type: ignore[return-value]
+
+
+def consume_event_stream(lines: Iterable[str | bytes]) -> Iterable[RuntimeEvent]:
+    buffer: list[str] = []
+    for item in lines:
+        line = item.decode("utf-8") if isinstance(item, bytes) else str(item)
+        if line == "":
+            payload = _parse_sse_block("\n".join(buffer))
+            buffer = []
+            if payload:
+                yield parse_runtime_event(payload)
+        else:
+            buffer.append(line)
+    if buffer:
+        payload = _parse_sse_block("\n".join(buffer))
+        if payload:
+            yield parse_runtime_event(payload)

agents24/types.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Any, NotRequired, TypeAlias, TypedDict
+
+JSONDict: TypeAlias = dict[str, Any]
+
+
+class RequestOptions(TypedDict, total=False):
+    idempotency_key: str
+    dry_run: bool
+    validate_only: bool
+    request_metadata: dict[str, Any]
+
+
+class RuntimeEvent(TypedDict):
+    version: str
+    seq: int | float
+    ts: str
+    event: str
+    run_id: str
+    stage: str
+    payload: dict[str, Any]
+    diagnostics: list[dict[str, Any]]
+
+
+class StreamResult(TypedDict):
+    thread_id: str | None
+    run_id: str | None
+
+
+class AttachmentUploadResult(TypedDict):
+    items: list[dict[str, Any]]
+
+
+class AgentCreateRequest(TypedDict):
+    name: str
+    graph_definition: dict[str, Any]
+    description: NotRequired[str | None]
+    memory_config: NotRequired[dict[str, Any]]
+    execution_constraints: NotRequired[dict[str, Any]]
+
+
+AgentUpdateRequest: TypeAlias = dict[str, Any]
+AgentResponse: TypeAlias = dict[str, Any]
+AgentListResponse: TypeAlias = dict[str, Any]
+AgentStreamRequest: TypeAlias = dict[str, Any]
+EmbedStreamRequest: TypeAlias = dict[str, Any]
+StartRunResult: TypeAlias = dict[str, Any]
+RunCancelResult: TypeAlias = dict[str, Any]
+RunContext: TypeAlias = dict[str, Any]
+RunEventsResponse: TypeAlias = dict[str, Any]
+RunStatus: TypeAlias = dict[str, Any]
+RunTrace: TypeAlias = dict[str, Any]
+ThreadDeleteResult: TypeAlias = dict[str, Any]
+ThreadDetail: TypeAlias = dict[str, Any]
+ThreadsResponse: TypeAlias = dict[str, Any]

agents24-0.1.0.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: agents24
+Version: 0.1.0
+Summary: Unified Python SDK for Agents24 agent runtime and control APIs.
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+
+# agents24
+
+Last Updated: 2026-05-25
+
+Unified Python SDK for Agents24.
+
+Endpoint methods are generated from `packages/agents24-sdk-contract/agents24.sdk.json`.
+Do not edit files under `agents24/generated/` directly. For SDK maintenance, see `docs/references/agents24_sdk_development_guide.md`.
+
+```python
+from agents24 import Agents24
+
+client = Agents24(
+    base_url="http://localhost:8000",
+    api_key="tpk_...",
+    organization_id="org-id",
+    project_id="project-id",
+)
+
+agent = client.agent({
+    "name": "Support Agent",
+    "instructions": "Answer briefly.",
+}).create()
+
+client.agents.publish(agent["id"])
+```
+
+## Artifact Authoring
+
+Artifact code imports lightweight helpers from `agents24.artifacts`:
+
+```python
+from agents24.artifacts import tool
+
+
+@tool(
+    name="echo",
+    input_schema={
+        "type": "object",
+        "properties": {"text": {"type": "string"}},
+        "required": ["text"],
+    },
+    output_schema={
+        "type": "object",
+        "properties": {"text": {"type": "string"}},
+        "required": ["text"],
+    },
+)
+async def echo(input, config, context):
+    return {"text": input["text"]}
+```
+
+The `agents24.artifacts` module is transport-free and safe for artifact runtime code.
+
+## Development
+
+```bash
+pnpm run generate:sdk
+pnpm run check:sdk-contract
+pnpm run test:agents24-python
+```
+
+Generated endpoint methods must stay in parity with the TypeScript `@agents24/sdk` package.

agents24-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+agents24/__init__.py,sha256=VQohNGpp9E2BzwKSx4iS1TvRHwKFeI6LH2OKgvR6oag,230
+agents24/artifacts.py,sha256=kRz-1QnLeTK6CjFuGrI27mDpMv9JT4KDNInCvRszhIc,1908
+agents24/builders.py,sha256=3Wl1V0jg72OAWhRTIge5TCIlyK5cOj2nKT-5bwfC2Ro,4802
+agents24/client.py,sha256=5vq4yHmddXhfZoqdNFA8ywXq_G5mfkI8k-Ssmi5i3xw,1537
+agents24/errors.py,sha256=ZRjdq0_-NMeqJBzVkMgD1ARCAmxV4xifnhFcr5tOK30,409
+agents24/http.py,sha256=xi_uvR5GCzEdxkGFJQ-wLkWyFQIrexcwcIEzsLEt7rU,6642
+agents24/sse.py,sha256=Omx-aeBgwapiPtyM9FV4hMY5Eg2p0x0pe4EehUHz69U,2260
+agents24/types.py,sha256=5hGgIYPLEMbFzybSiB8ThXPJIkZTehSusy2t7R7hR4k,1479
+agents24/generated/__init__.py,sha256=J35rhjvtYFSMtERrp9OTveWpIBEBGJByBgZ7POBg21I,73
+agents24/generated/agents.py,sha256=rup_FcbVmKWFRMRVbMmod-e2Mw9wmCIFlRLt9jTyxoQ,4245
+agents24/generated/embed.py,sha256=ndWnw-CbL6GFTM0j0kbreug2FDy_7vWOKE9pqiM7a_4,4217
+agents24/generated/manifest.py,sha256=BE4EiUMeylto6wBICXgAs2-kF2Pe2dNETp9SbqY6Kfc,622
+agents24/generated/runs.py,sha256=ponpY4VEl50-aBeByYVUCk-qiVVlS8PWGP40skfrcQI,1333
+agents24-0.1.0.dist-info/METADATA,sha256=k4fSmod7QPCLzYVwb3vSm1na6zyzSPGntbDUEhw9F70,1661
+agents24-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agents24-0.1.0.dist-info/top_level.txt,sha256=CVcfR_w_8svOxK5tZP1uayAtxTPL2RaVYpqoPXP4KuY,9
+agents24-0.1.0.dist-info/RECORD,,

agents24-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agents24-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agents24