agentbyte 0.44.0__tar.gz → 0.44.1__tar.gz

{agentbyte-0.44.0 → agentbyte-0.44.1}/CHANGELOG.md

@@ -6,6 +6,21 @@ The format follows Keep a Changelog principles and semantic versioning.
 
 ## [Unreleased]
 
+## [0.44.1] - 2026-10-05
+
+### Added
+
+- `agentbyte.execution_trace.SpanKind` (spec 0067): `StrEnum` of the framework's own span kinds
+  (`agent`, `invocation`, `orchestrator`, `workflow`, `workflow_agent`, `step`), used by
+  `trace_stream` and the collector. `ExecutionSpan.kind` stays an open `str`, so
+  `trace_scope(kind=...)` / `TraceCollector.start` still accept caller-defined kinds.
+
+### Fixed
+
+- Flaky `test_cli_interrupt_exits_130_and_records_cancelled_run`: it sent SIGINT as soon as the run
+  was admitted, sometimes before the item started, so the item was recorded `not_started` instead
+  of `cancelled`. The test now waits (read-only history store) until the item is running.
+
 ## [0.44.0] - 2026-10-05
 
 ### Changed

{agentbyte-0.44.0 → agentbyte-0.44.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentbyte
-Version: 0.44.0
+Version: 0.44.1
 Summary: A toolkit for designing multiagent systems
 Author-email: MrDataPsycho <mr.data.psycho@gmail.com>
 License-Expression: LicenseRef-Proprietary
@@ -77,7 +77,7 @@ Description-Content-Type: text/markdown
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.44.0**
+Current release: **0.44.1**
 
 ## Building an Agent
 

{agentbyte-0.44.0 → agentbyte-0.44.1}/README.md

@@ -2,7 +2,7 @@
 
 Agentbyte is an observability-first agentic AI framework for building and studying multiagent systems with a learning-first, implementation-oriented workflow.
 
-Current release: **0.44.0**
+Current release: **0.44.1**
 
 ## Building an Agent
 

agentbyte-0.44.1/src/agentbyte/__about__.py

@@ -0,0 +1,2 @@
+__version__ = "0.44.1"
+VERSION = __version__

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/agents/agent.py

@@ -12,7 +12,7 @@ from typing import List, Optional, Union
 
 from agentbyte.cancellation_token import CancellationToken
 from agentbyte.context import AgentContext
-from agentbyte.execution_trace import trace_stream
+from agentbyte.execution_trace import SpanKind, trace_stream
 from agentbyte.llm.types import ChatCompletionChunk
 from agentbyte.messages import (
     AssistantMessage,
@@ -445,7 +445,7 @@ class Agent(BaseAgent):
             )
             yield ToolApprovalEvent(source=self.name, approval_request=request)
 
-    @trace_stream("agent")
+    @trace_stream(SpanKind.AGENT)
     async def run_stream(
         self,
         task: Optional[Union[str, UserMessage, List[Message]]] = None,

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/eval/history/conformance.py

@@ -23,7 +23,7 @@ from pydantic import BaseModel
 from agentbyte.eval.base import BaseEvalJudge, BaseEvalTarget, JudgeScoringError
 from agentbyte.eval.runner import EvalRunner
 from agentbyte.eval.types import EvalScore, EvalTask, EvalTrajectory, ScoringStatus, WorkflowEvalTask
-from agentbyte.execution_trace.models import ExecutionEvent, ExecutionSpan, ExecutionTrace
+from agentbyte.execution_trace.models import ExecutionEvent, ExecutionSpan, ExecutionTrace, SpanKind
 from agentbyte.messages import AssistantMessage, UserMessage, Usage
 
 from .errors import (
@@ -59,7 +59,7 @@ class _Target(BaseEvalTarget):
             await asyncio.sleep(task.metadata.get("delay", 0))
             if task.metadata.get("target_fails"):
                 raise RuntimeError("target failed")
-            span = ExecutionSpan(kind="agent", name="conformance", status="completed")
+            span = ExecutionSpan(kind=SpanKind.AGENT, name="conformance", status="completed")
             trace = ExecutionTrace(spans=[span], events=[ExecutionEvent(span_id=span.id, kind="step")])
             return EvalTrajectory(
                 task=task,
@@ -222,7 +222,7 @@ async def check_full_evidence_round_trips_as_data(store: EvalRunStore) -> None:
         task=task,
         messages=[*turn, *turn, AssistantMessage(content="", source="a", structured_content=_Answer(city="Rome"))],
         success=True,
-        trace=ExecutionTrace(spans=[ExecutionSpan(kind="agent", name="a")]),
+        trace=ExecutionTrace(spans=[ExecutionSpan(kind=SpanKind.AGENT, name="a")]),
     )
     score = EvalScore(overall=8.0, reasoning={"q": "why"}, trajectory=trajectory)
     run = await _started(store, 1)

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/eval/workbench/smoke.py

@@ -18,7 +18,7 @@ from agentbyte.cancellation_token import CancellationToken
 from agentbyte.eval.base import BaseEvalTarget
 from agentbyte.eval.judges import ContainsJudge
 from agentbyte.eval.types import EvalTask, EvalTrajectory
-from agentbyte.execution_trace.models import ExecutionSpan, ExecutionStatus, ExecutionTrace
+from agentbyte.execution_trace.models import ExecutionSpan, ExecutionStatus, ExecutionTrace, SpanKind
 from agentbyte.messages import AssistantMessage, UserMessage
 
 from .suite import EvalSuite, EvalSuiteRegistry
@@ -37,7 +37,7 @@ class ArithmeticTarget(BaseEvalTarget):
         self, task: EvalTask, cancellation_token: CancellationToken | None = None
     ) -> EvalTrajectory:
         started = time.perf_counter()
-        span = ExecutionSpan(kind="agent", name=self.name, input=task.input)
+        span = ExecutionSpan(kind=SpanKind.AGENT, name=self.name, input=task.input)
         match = _QUESTION.search(task.input)
         if match is None:
             answer, status, error = None, ExecutionStatus.FAILED, "unsupported_question"

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/execution_trace/__init__.py

@@ -1,6 +1,6 @@
 """Runtime-neutral execution evidence, independent of evaluation and OpenTelemetry."""
 
-from .models import ExecutionEvent, ExecutionSpan, ExecutionTrace, ExecutionStatus
+from .models import ExecutionEvent, ExecutionSpan, ExecutionStatus, ExecutionTrace, SpanKind
 from .collector import (
     TraceCollector,
     current_collector,
@@ -14,6 +14,7 @@ __all__ = [
     "ExecutionSpan",
     "ExecutionTrace",
     "ExecutionStatus",
+    "SpanKind",
     "TraceCollector",
     "current_collector",
     "trace_call",

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/execution_trace/collector.py

@@ -16,7 +16,7 @@ from pydantic import BaseModel
 
 from agentbyte.messages import BaseMessage, UserMessage, SystemMessage
 from agentbyte.types import OrchestrationEvent
-from .models import ExecutionEvent, ExecutionSpan, ExecutionTrace, ExecutionStatus
+from .models import ExecutionEvent, ExecutionSpan, ExecutionStatus, ExecutionTrace, SpanKind
 
 if TYPE_CHECKING:
     from agentbyte.types import TurnKind
@@ -79,8 +79,8 @@ class TraceCollector:
             _parent.reset(parent)
             _collector.reset(token)
 
-    def start(self, kind: str, name: str, **kwargs: Any) -> ExecutionSpan:
-        span = ExecutionSpan(kind=kind, name=name, parent_id=_parent.get(), **kwargs)
+    def start(self, kind: SpanKind | str, name: str, **kwargs: Any) -> ExecutionSpan:
+        span = ExecutionSpan(kind=str(kind), name=name, parent_id=_parent.get(), **kwargs)
         self.trace.spans.append(span)
         return span
 
@@ -95,7 +95,7 @@ class TraceCollector:
         if isinstance(item, BaseMessage):
             if (
                 self.capture_payloads
-                and span.kind == "agent"
+                and span.kind == SpanKind.AGENT
                 and not isinstance(item, (UserMessage, SystemMessage))
                 and item not in span.messages
             ):
@@ -107,7 +107,7 @@ class TraceCollector:
             if item.needs_approval and self.capture_payloads:
                 span.metadata["pending_requests"] = snapshot(item.approval_requests)
             span.usage = item.usage
-            if span.kind == "agent":
+            if span.kind == SpanKind.AGENT:
                 span.usage = span.usage + self.trace.aggregate_usage(span.id)
             span.error = item.error.message if item.error is not None else None
             orchestration = getattr(item, "orchestration", None)
@@ -117,7 +117,7 @@ class TraceCollector:
                 span.output = item.final_content
             return
         if hasattr(item, "event_type") or isinstance(item, OrchestrationEvent):
-            if self.capture_payloads and span.kind != "workflow_agent":
+            if self.capture_payloads and span.kind != SpanKind.WORKFLOW_AGENT:
                 self.trace.events.append(
                     ExecutionEvent(
                         span_id=span.id,
@@ -136,7 +136,7 @@ class TraceCollector:
 
 
 @contextmanager
-def trace_scope(kind: str, name: str, **kwargs: Any) -> Iterator[ExecutionSpan | None]:
+def trace_scope(kind: SpanKind | str, name: str, **kwargs: Any) -> Iterator[ExecutionSpan | None]:
     """Record a scope only when capture is active."""
     collector = current_collector()
     if collector is None:
@@ -164,7 +164,7 @@ def trace_scope(kind: str, name: str, **kwargs: Any) -> Iterator[ExecutionSpan |
         _parent.reset(token)
 
 
-def trace_call(kind: str) -> Callable:
+def trace_call(kind: SpanKind | str) -> Callable:
     """Instrument an async runtime method without changing its public signature."""
 
     def decorate(fn):
@@ -193,7 +193,7 @@ async def capture_agent_call(agent: Any, **kwargs: Any) -> Any:
     context = kwargs.get("context")
     history = list(context.messages) if context is not None else []
     with trace_scope(
-        "invocation", getattr(agent, "name", type(agent).__name__)
+        SpanKind.INVOCATION, getattr(agent, "name", type(agent).__name__)
     ) as span:
         try:
             result = await agent.run(**kwargs)
@@ -217,7 +217,7 @@ async def capture_agent_call(agent: Any, **kwargs: Any) -> Any:
         return result
 
 
-def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
+def trace_stream(kind: SpanKind | str, *, accounting: bool = False) -> Callable:
     """Instrument streams, keeping collector/parent bindings out of consumer code."""
 
     def decorate(fn):
@@ -267,13 +267,13 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
                     try:
                         item = await anext(stream)
                         is_forwarded_member_event = (
-                            kind == "orchestrator"
+                            kind == SpanKind.ORCHESTRATOR
                             and hasattr(item, "event_type")
                             and getattr(item, "source", "orchestrator") != "orchestrator"
                         )
                         if not is_forwarded_member_event:
                             collector.observe(span, item)
-                        if kind == "invocation" and hasattr(item, "finish_reason"):
+                        if kind == SpanKind.INVOCATION and hasattr(item, "finish_reason"):
                             if any(
                                 s.parent_id == span.id for s in collector.trace.spans
                             ):
@@ -294,7 +294,7 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
                                 collector.incomplete(
                                     "Custom agent exposes response evidence only"
                                 )
-                        if kind == "workflow_agent" and hasattr(item, "finish_reason"):
+                        if kind == SpanKind.WORKFLOW_AGENT and hasattr(item, "finish_reason"):
                             item.usage = collector.trace.aggregate_usage(
                                 span.id
                             ).model_copy(
@@ -314,7 +314,7 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
                         not original_verbose
                         and "verbose" in signature.parameters
                         and not (
-                            kind == "workflow_agent"
+                            kind == SpanKind.WORKFLOW_AGENT
                             and bound.arguments.get("stream_tokens", False)
                             and getattr(item, "event_type", None) == "step_event"
                         )
@@ -332,7 +332,7 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
                     else ExecutionStatus.FAILED
                 )
                 span.error = str(exc) or type(exc).__name__
-                if span.kind == "agent" and span.usage is None:
+                if span.kind == SpanKind.AGENT and span.usage is None:
                     collector.incomplete(
                         "Agent ended without reporting usage", usage=True
                     )
@@ -347,7 +347,7 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
                     _collector.reset(ct)
                 if span.status == "running":
                     span.status = ExecutionStatus.COMPLETED
-                if kind == "orchestrator":
+                if kind == SpanKind.ORCHESTRATOR:
                     span.usage = collector.trace.aggregate_usage(span.id)
                     for usage in self._get_additional_usage_stats():
                         span.usage = span.usage + usage
@@ -358,7 +358,7 @@ def trace_stream(kind: str, *, accounting: bool = False) -> Callable:
     return decorate
 
 
-@trace_stream("invocation")
+@trace_stream(SpanKind.INVOCATION)
 async def capture_agent_stream(
     agent: Any,
     task: Any,

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/execution_trace/models.py

@@ -12,6 +12,28 @@ from pydantic import BaseModel, Field
 from agentbyte.messages import Message, Usage
 
 
+class SpanKind(StrEnum):
+    """The span kinds the framework itself records (spec 0067).
+
+    ``ExecutionSpan.kind`` stays an open ``str``: code may open its own spans with
+    ``trace_scope(kind=...)`` or ``TraceCollector.start``. Built-in kinds compare equal to
+    these members.
+    """
+
+    AGENT = "agent"
+    """One ``Agent.run_stream`` call."""
+    INVOCATION = "invocation"
+    """A single captured call into an agent or step runtime."""
+    ORCHESTRATOR = "orchestrator"
+    """One team run (any orchestration pattern)."""
+    WORKFLOW = "workflow"
+    """One ``WorkflowRunner`` run."""
+    WORKFLOW_AGENT = "workflow_agent"
+    """A ``workflow.as_agent()`` wrapper run."""
+    STEP = "step"
+    """One attempt of a workflow step."""
+
+
 class ExecutionStatus(StrEnum):
     """Lifecycle status of a traced execution."""
 
@@ -39,6 +61,7 @@ class ExecutionSpan(BaseModel):
     id: str = Field(default_factory=lambda: str(uuid4()))
     parent_id: str | None = None
     kind: str
+    """A ``SpanKind`` value for framework spans, or any caller-chosen kind."""
     name: str
     step_id: str | None = None
     attempt: int | None = None

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/orchestration/base.py

@@ -13,7 +13,7 @@ from typing import Any, Dict, List, Optional, Sequence, Union, cast
 
 from agentbyte.agents.base import BaseAgent
 from agentbyte.agents.types import AgentErrorDetail, AgentResponse, Usage
-from agentbyte.execution_trace import trace_stream
+from agentbyte.execution_trace import SpanKind, trace_stream
 from agentbyte.execution_trace.collector import capture_agent_stream, normalize_status
 from agentbyte.cancellation_token import CancellationToken
 from agentbyte.compaction.grouping import MessageGroup, group_messages
@@ -230,7 +230,7 @@ class BaseOrchestrator(ABC):
                 select_final_message=False,
             )
 
-    @trace_stream("orchestrator")
+    @trace_stream(SpanKind.ORCHESTRATOR)
     async def run_stream(
         self,
         task: Union[str, UserMessage, List[Message], None] = None,

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/workflow/agent.py

@@ -12,7 +12,7 @@ from agentbyte.agents.base import BaseAgent
 from agentbyte.agents.types import AgentResponse, Usage
 from agentbyte.cancellation_token import CancellationToken
 from agentbyte.context import AgentContext
-from agentbyte.execution_trace import trace_stream
+from agentbyte.execution_trace import SpanKind, trace_stream
 from agentbyte.messages import AssistantMessage, BaseMessage, Message, UserMessage
 from agentbyte.middleware import MiddlewareChain
 from agentbyte.workflow.core.checkpoint import (
@@ -109,7 +109,7 @@ class WorkflowAgent(BaseAgent):
             raise RuntimeError(msg)
         return final_response
 
-    @trace_stream("workflow_agent", accounting=True)
+    @trace_stream(SpanKind.WORKFLOW_AGENT, accounting=True)
     async def run_stream(
         self,
         task: Any = None,

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/workflow/core/runner.py

@@ -16,7 +16,7 @@ from uuid import uuid4
 from pydantic import BaseModel, TypeAdapter
 
 from agentbyte.cancellation_token import CancellationToken
-from agentbyte.execution_trace import trace_stream
+from agentbyte.execution_trace import SpanKind, trace_stream
 from agentbyte.workflow.core.checkpoint import (
     CheckpointConfig,
     CheckpointType,
@@ -132,7 +132,7 @@ class WorkflowRunner:
             raise RuntimeError(msg)
         return final_execution
 
-    @trace_stream("workflow")
+    @trace_stream(SpanKind.WORKFLOW)
     async def run_stream(
         self,
         workflow: Workflow,

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/workflow/steps/agent.py

@@ -12,6 +12,7 @@ from agentbyte.agents import AgentResponse, BaseAgent
 from agentbyte.cancellation_token import CancellationToken
 from agentbyte.context import AgentContext, ToolApprovalResponse
 from agentbyte.execution_trace.collector import normalize_status, trace_stream
+from agentbyte.execution_trace.models import SpanKind
 from agentbyte.workflow.core.models import StepMetadata, WorkflowContext, WorkflowPendingRequest
 from agentbyte.workflow.steps.step import BaseStep
 
@@ -79,7 +80,7 @@ class AgentStep(
             raise ValueError("Provide exactly one decision for every pending agent tool approval")
         return decisions
 
-    @trace_stream("invocation")
+    @trace_stream(SpanKind.INVOCATION)
     async def _agent_stream(
         self, task: str | None, context: AgentContext | None,
         cancellation_token: CancellationToken | None, verbose: bool, stream_tokens: bool,

{agentbyte-0.44.0 → agentbyte-0.44.1}/src/agentbyte/workflow/steps/step.py

@@ -9,7 +9,7 @@ from typing import Any, Generic, Type
 
 from agentbyte.execution_trace import current_collector, trace_scope
 from agentbyte.execution_trace.collector import snapshot
-from agentbyte.execution_trace.models import ExecutionStatus
+from agentbyte.execution_trace.models import ExecutionStatus, SpanKind
 
 from agentbyte.workflow.core.models import (
     InputType,
@@ -140,7 +140,7 @@ class BaseStep(Generic[InputType, OutputType], ABC):
     ) -> dict[str, Any]:
         collector = current_collector()
         with trace_scope(
-            "step", self.metadata.name, step_id=self.step_id, attempt=attempt + 1
+            SpanKind.STEP, self.metadata.name, step_id=self.step_id, attempt=attempt + 1
         ) as span:
             if span is not None and collector.capture_payloads:
                 span.input = snapshot(input_data)

{agentbyte-0.44.0 → agentbyte-0.44.1}/tests/eval/test_eval_workbench.py

@@ -16,7 +16,14 @@ from pathlib import Path
 import pytest
 
 from agentbyte.eval import BaseEvalJudge, BaseEvalTarget, ContainsJudge, EvalScore, EvalTask, JudgeScoringError
-from agentbyte.eval.history import EvalItemRecord, EvalRunRecord, EvalRunRecorder, MemoryEvalRunStore
+from agentbyte.eval.history import (
+    EvalItemRecord,
+    EvalRunRecord,
+    EvalRunRecorder,
+    ItemState,
+    MemoryEvalRunStore,
+    SQLiteEvalRunStore,
+)
 from agentbyte.eval.runner import EvalRunner
 from agentbyte.eval.workbench import (
     MIN_SCORE_LABEL,
@@ -427,6 +434,19 @@ def test_cli_results_for_unknown_run_exit_2(cli_env, tmp_path) -> None:
     assert result.returncode == 2 and "Unknown evaluation run" in result.stderr
 
 
+async def _wait_for_running_item(history: Path, run_id: str, timeout: float = 30.0) -> None:
+    """Poll the CLI's history (as a read-only store) until the run's item is running."""
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout
+    async with SQLiteEvalRunStore(history, writer=False) as store:
+        while loop.time() < deadline:
+            items = await store.list_items(run_id)
+            if any(item.state == ItemState.RUNNING for item in items):
+                return
+            await asyncio.sleep(0.02)
+    raise AssertionError(f"run {run_id} never started its item")
+
+
 @pytest.mark.skipif(sys.platform == "win32", reason="POSIX signals")
 def test_cli_interrupt_exits_130_and_records_cancelled_run(cli_env, tmp_path) -> None:
     history = tmp_path / "slow.sqlite"
@@ -439,6 +459,9 @@ def test_cli_interrupt_exits_130_and_records_cancelled_run(cli_env, tmp_path) ->
         line = process.stderr.readline()
         assert "started" in line, line
         run_id = line.split()[1]
+        # "started" prints when the run is admitted, before its item runs. Interrupting a
+        # still-pending item records it as not_started, so wait until it is running.
+        asyncio.run(_wait_for_running_item(history, run_id))
         process.send_signal(signal.SIGINT)
         _, stderr = process.communicate(timeout=60)
     finally:

{agentbyte-0.44.0 → agentbyte-0.44.1}/tests/test_option_enums.py

@@ -17,7 +17,7 @@ from pydantic import ValidationError
 from agentbyte.eval import PairwiseWinner, ScoringStatus
 from agentbyte.eval.history import CaptureMode, EvidenceStatus, ItemState, RunStatus, TaskType
 from agentbyte.eval.workbench.verdict import ItemOutcome
-from agentbyte.execution_trace import ExecutionStatus
+from agentbyte.execution_trace import ExecutionSpan, ExecutionStatus, SpanKind, TraceCollector
 from agentbyte.middleware.base import OperationType, RetrySequenceOutcome
 from agentbyte.orchestration import (
     AgentHistoryPolicy,
@@ -144,6 +144,24 @@ class TestStrEnumBehaviour:
         assert "passed" in set(ItemOutcome) and CaptureMode.FULL == "full"
 
 
+class TestSpanKind:
+    """Built-in span kinds are a StrEnum; the span field stays open for caller kinds."""
+
+    def test_builtin_kinds(self) -> None:
+        assert [k.value for k in SpanKind] == [
+            "agent", "invocation", "orchestrator", "workflow", "workflow_agent", "step",
+        ]
+
+    def test_builtin_member_is_stored_as_plain_value(self) -> None:
+        span = TraceCollector().start(SpanKind.AGENT, "a")
+
+        assert span.kind == SpanKind.AGENT == "agent"
+        assert span.model_dump(mode="json")["kind"] == "agent"
+
+    def test_caller_defined_kind_is_allowed(self) -> None:
+        assert ExecutionSpan(kind="retrieval", name="vector search").kind == "retrieval"
+
+
 # Multi-value Literals allowed to stay: message-role / entity-type tags of a discriminated
 # union, where each concrete class narrows the base to one value.
 _ALLOWED_LITERALS = {

agentbyte-0.44.0/src/agentbyte/__about__.py

@@ -1,2 +0,0 @@
-__version__ = "0.44.0"
-VERSION = __version__