agents24 0.1.0__tar.gz

agents24-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,63 @@
+# 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/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/agents24/generated/__init__.py

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

agents24-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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)