Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: implement event handling in Python SDK (#739)

Bhavesh Patel134dcb907e7b
diff --git a/.changeset/python-event-delta-helpers.md b/.changeset/python-event-delta-helpers.md
new file mode 100644
index 000000000..e44b1c8ef
--- /dev/null
+++ b/.changeset/python-event-delta-helpers.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Python SDK `is_event_delta` / `merge_event_delta` (PyPI version locksteps with this package on Version Packages).
diff --git a/.changeset/python-use-in-code-snippets.md b/.changeset/python-use-in-code-snippets.md
index ef096572e..5c17b31e5 100644
--- a/.changeset/python-use-in-code-snippets.md
+++ b/.changeset/python-use-in-code-snippets.md
@@ -2,4 +2,4 @@
"@truefoundry/trueforge": patch
---
-Add Python TrueForge SDK stream and non-stream samples to agent Use in Code snippets.
+Add Python TrueForge SDK stream and non-stream samples to agent Use in Code snippets, merging deltas with is_event_delta / merge_event_delta.
diff --git a/.gitignore b/.gitignore
index 64431bd80..343e082b4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,4 +41,5 @@ service-account*.json
.vscode
-.certs/
\ No newline at end of file
+.certs/
+*.pyc
\ No newline at end of file
diff --git a/docs/api/overview.mdx b/docs/api/overview.mdx
index 4aeaae4e9..bf1447930 100644
--- a/docs/api/overview.mdx
+++ b/docs/api/overview.mdx
@@ -169,6 +169,8 @@ Your order ORD-2031 shipped on June 12.
Your order ORD-2031 shipped on June 12. Total: $1,240.00.
```
+In the SDK, use TypeScript `isEventDelta` / `mergeEventDelta` or Python `is_event_delta` / `merge_event_delta` from `trueforge_sdk.events`. See [Create and stream a turn](/api/use-agent#create-and-stream-a-turn).
+
Deltas only exist on the live stream. When you list a turn's events afterwards (`GET .../events`), each `model.message` is already merged, so you use it directly.
<Note>
diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdx
index bec36506b..cadb0cd54 100644
--- a/docs/api/use-agent.mdx
+++ b/docs/api/use-agent.mdx
@@ -214,7 +214,7 @@ Creating a new turn in a session automatically cancels any turn still running in
`createTurnStream` / `create_turn_stream` returns a stream of [turn events](#turn-events-reference). `stream.withMetadata()` / `stream.with_metadata()` yields `{ data, id }` (TypeScript) or `StreamEvent` (Python: `.data`, `.id`), where `data` is the parsed event and `id` is the per-stream sequence number used to [resume after a disconnect](#resume-a-stream). The stream opens with `turn.created` and closes with `turn.done`; read the terminal result from `turn.done.state`.
-Keep an **`id`-keyed event index**. Model output streams as an empty `model.message` base followed by `model.message.delta` fragments that share the base's `id`. TypeScript stores each non-delta event under its `id` and merges each delta into the base with `isEventDelta` / `mergeEventDelta`. Python does not export those helpers — skip events whose `type` ends in `.delta`. (Deltas appear only while streaming; [`listTurnEvents`](#replay-a-finished-turn) / `list_turn_events` returns them already merged.) Pause handlers and the per-thread index below reuse this pattern.
+Keep an **`id`-keyed event index**. Model output streams as an empty `model.message` base followed by `model.message.delta` fragments that share the base's `id`. Store each non-delta event under its `id` and merge each delta into the base with TypeScript `isEventDelta` / `mergeEventDelta` or Python `is_event_delta` / `merge_event_delta` (`from trueforge_sdk.events import …`). (Deltas appear only while streaming; [`listTurnEvents`](#replay-a-finished-turn) / `list_turn_events` returns them already merged.) Pause handlers and the per-thread index below reuse this pattern.
<CodeGroup>
```typescript TypeScript wrap
@@ -249,6 +249,7 @@ for await (const { data: event, id } of stream.withMetadata()) {
```python Python wrap
import os
from trueforge_sdk import TrueForge
+from trueforge_sdk.events import is_event_delta, merge_event_delta
client = TrueForge(
base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
@@ -270,9 +271,12 @@ for meta in stream.with_metadata():
last_sequence_number = int(meta.id)
if event.type == "turn.created":
turn_id = event.turn_id
- if event.type.endswith(".delta"):
- continue
- events[event.id] = event
+ if is_event_delta(event):
+ base = events.get(event.id)
+ if base is not None:
+ merge_event_delta(base, event)
+ else:
+ events[event.id] = event
if event.type == "turn.done":
print("status:", event.state.status)
```
@@ -486,7 +490,7 @@ For approvals and questions, each pending ref carries the `sourceEventId` of the
### Tool approvals
-A gated tool ([human approval](/create-agent/overview#whats-in-an-agent)) emits [`tool.approval_required`](#tool-approval-required). Collect the pending events while streaming, then resume with one `user.tool_approval` per pending call, either allowing it or denying it with a reason. Look up each ref in the [event index](#create-and-stream-a-turn); Python rebuilds that index from [`list_turn_events`](#replay-a-finished-turn) after the stream closes.
+A gated tool ([human approval](/create-agent/overview#whats-in-an-agent)) emits [`tool.approval_required`](#tool-approval-required). Collect the pending events while streaming, then resume with one `user.tool_approval` per pending call, either allowing it or denying it with a reason. Look up each ref in the [event index](#create-and-stream-a-turn).
<CodeGroup>
```typescript TypeScript wrap
@@ -538,6 +542,7 @@ for await (const { data: event } of resume.withMetadata()) console.log(event.typ
```python Python wrap
import os
from trueforge_sdk import TrueForge
+from trueforge_sdk.events import is_event_delta, merge_event_delta
client = TrueForge(
base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
@@ -545,24 +550,23 @@ client = TrueForge(
)
session = client.sessions.create(agent={"name": "ops-bot"})
+events = {}
pending_approvals = []
-turn_id = None
stream = client.sessions.create_turn_stream(
session_id=session.data.id,
input=[{"type": "user.message", "content": "Restart the billing service."}],
)
for event in stream:
- if event.type == "turn.created":
- turn_id = event.turn_id
+ if is_event_delta(event):
+ base = events.get(event.id)
+ if base is not None:
+ merge_event_delta(base, event)
+ else:
+ events[event.id] = event
if event.type == "tool.approval_required":
pending_approvals.append(event)
-events = {
- event.id: event
- for event in client.sessions.list_turn_events(session_id=session.data.id, turn_id=turn_id)
-}
-
approvals = []
for pending in pending_approvals:
for ref in pending.tool_calls:
@@ -645,6 +649,7 @@ for await (const { data: event } of resume.withMetadata()) console.log(event.typ
import json
import os
from trueforge_sdk import TrueForge
+from trueforge_sdk.events import is_event_delta, merge_event_delta
client = TrueForge(
base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
@@ -652,24 +657,23 @@ client = TrueForge(
)
session = client.sessions.create(agent={"name": "ops-bot"})
+events = {}
pending_questions = []
-turn_id = None
stream = client.sessions.create_turn_stream(
session_id=session.data.id,
input=[{"type": "user.message", "content": "Create a new environment called testing-1."}],
)
for event in stream:
- if event.type == "turn.created":
- turn_id = event.turn_id
+ if is_event_delta(event):
+ base = events.get(event.id)
+ if base is not None:
+ merge_event_delta(base, event)
+ else:
+ events[event.id] = event
if event.type == "tool.response_required":
pending_questions.append(event)
-events = {
- event.id: event
- for event in client.sessions.list_turn_events(session_id=session.data.id, turn_id=turn_id)
-}
-
responses = []
for pending in pending_questions:
for ref in pending.tool_calls:
@@ -831,6 +835,7 @@ if (turn.state.status === 'running') {
```python Python wrap
import os
from trueforge_sdk import TrueForge
+from trueforge_sdk.events import is_event_delta, merge_event_delta
client = TrueForge(
base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
@@ -852,9 +857,12 @@ for meta in stream.with_metadata():
last_sequence_number = int(meta.id)
if event.type == "turn.created":
turn_id = event.turn_id
- if event.type.endswith(".delta"):
- continue
- events[event.id] = event
+ if is_event_delta(event):
+ base = events.get(event.id)
+ if base is not None:
+ merge_event_delta(base, event)
+ else:
+ events[event.id] = event
# …after a disconnect, with session.id / turn_id / last_sequence_number restored:
turn = client.sessions.get_turn(session_id=session.data.id, turn_id=turn_id).data
@@ -869,9 +877,12 @@ if turn.state.status == "running":
event = meta.data
if meta.id is not None:
last_sequence_number = int(meta.id)
- if event.type.endswith(".delta"):
- continue
- events[event.id] = event
+ if is_event_delta(event):
+ base = events.get(event.id)
+ if base is not None:
+ merge_event_delta(base, event)
+ else:
+ events[event.id] = event
else:
# Already finished: rebuild from the stored log (deltas already merged).
for event in client.sessions.list_turn_events(session_id=session.data.id, turn_id=turn_id):
@@ -891,7 +902,7 @@ A turn stream interleaves the root agent and any parallel [subagents](/key-featu
- A unique id: a subagent thread. [`thread.created`](#thread-created) and [`thread.done`](#thread-done) bracket its lifecycle.
- `null`: a turn-level event, such as [`turn.created`](#turn-created), [`turn.done`](#turn-done), [`sandbox.created`](#sandbox-created), and [`mcp.auth_required`](#mcp-auth-required).
-Keep a **per-thread** index (`Map<threadId, Map<id, event>>` in TypeScript; nested dicts in Python) and apply the same [event-index](#create-and-stream-a-turn) merge (or skip) inside each thread's bucket.
+Keep a **per-thread** index (`Map<threadId, Map<id, event>>` in TypeScript; nested dicts in Python) and apply the same [event-index](#create-and-stream-a-turn) merge inside each thread's bucket.
```mermaid
sequenceDiagram
@@ -951,6 +962,7 @@ for await (const { data: event } of stream.withMetadata()) {
```python Python wrap
import os
from trueforge_sdk import TrueForge
+from trueforge_sdk.events import is_event_delta, merge_event_delta
client = TrueForge(
base_url=os.environ.get("TRUEFORGE_BASE_URL", "http://localhost:8790"),
@@ -969,9 +981,12 @@ for event in stream:
print("turn-level event:", event.type)
continue
bucket = threads.setdefault(event.thread_id, {})
- if event.type.endswith(".delta"):
- continue
- bucket[event.id] = event
+ if is_event_delta(event):
+ base = bucket.get(event.id)
+ if base is not None:
+ merge_event_delta(base, event)
+ else:
+ bucket[event.id] = event
if event.type == "thread.done":
print(f"{event.thread_id} done: {event.title} ({len(bucket)} events)")
del threads[event.thread_id]
@@ -1093,7 +1108,7 @@ An assistant message — text content and/or tool calls. On a live stream the ba
#### `model.message.delta`
-An incremental fragment of a `model.message` — text and/or tool-call chunks. All deltas share the base event's `id`; append `content` chunks and merge tool-call fragments by index. The most frequent event on a live stream. Not present when listing persisted events.
+An incremental fragment of a `model.message` — text and/or tool-call chunks. All deltas share the base event's `id`; append `content` chunks and merge tool-call fragments by index (`isEventDelta` / `mergeEventDelta` in TypeScript; `is_event_delta` / `merge_event_delta` from `trueforge_sdk.events` in Python). The most frequent event on a live stream. Not present when listing persisted events.
### Tool activity
diff --git a/packages/trueforge/src/apis/codesnippet-templates/python.ts b/packages/trueforge/src/apis/codesnippet-templates/python.ts
index 56cc8bba8..5691c39d5 100644
--- a/packages/trueforge/src/apis/codesnippet-templates/python.ts
+++ b/packages/trueforge/src/apis/codesnippet-templates/python.ts
@@ -1,5 +1,6 @@
export const pythonStreamTemplate = `# pip install trueforge-sdk
from trueforge_sdk import TrueForge
+from trueforge_sdk.events import is_event_delta, merge_event_delta
client = TrueForge(
base_url={{baseUrl}},{{tokenLine}}
@@ -9,6 +10,8 @@ session = client.sessions.create(
agent={"name": {{agentName}}},
)
+events = {}
+
stream = client.sessions.create_turn_stream(
session_id=session.data.id,
input=[{"type": "user.message", "content": "Hello!"}],
@@ -16,6 +19,12 @@ stream = client.sessions.create_turn_stream(
for event in stream:
print(event)
+ if is_event_delta(event):
+ base = events.get(event.id)
+ if base is not None:
+ merge_event_delta(base, event)
+ else:
+ events[event.id] = event
`;
export const pythonNonStreamTemplate = `# pip install trueforge-sdk
diff --git a/packages/trueforge/tests/unit/apis/agents.test.ts b/packages/trueforge/tests/unit/apis/agents.test.ts
index f6cea8495..dede2fedc 100644
--- a/packages/trueforge/tests/unit/apis/agents.test.ts
+++ b/packages/trueforge/tests/unit/apis/agents.test.ts
@@ -205,8 +205,11 @@ describe('agents router', () => {
);
expect(body.data.snippets.map(snippet => snippet.language)).toEqual(['typescript', 'python']);
const python = body.data.snippets.find(snippet => snippet.language === 'python');
+ const typescript = body.data.snippets.find(snippet => snippet.language === 'typescript');
expect(python?.sample_code.stream).toContain('create_turn_stream');
+ expect(python?.sample_code.stream).toContain('merge_event_delta');
expect(python?.sample_code.non_stream).toContain('create_turn');
+ expect(typescript?.sample_code.stream).toContain('mergeEventDelta');
for (const snippet of body.data.snippets) {
expect(snippet.sample_code.stream).not.toContain('USER_API_KEY');
expect(snippet.sample_code.non_stream).not.toContain('USER_API_KEY');
diff --git a/python/trueforge_sdk/.fernignore b/python/trueforge_sdk/.fernignore
new file mode 100644
index 000000000..98192b7ca
--- /dev/null
+++ b/python/trueforge_sdk/.fernignore
@@ -0,0 +1,2 @@
+src/trueforge_sdk/events.py
+tests/test_events.py
diff --git a/python/trueforge_sdk/src/trueforge_sdk/events.py b/python/trueforge_sdk/src/trueforge_sdk/events.py
new file mode 100644
index 000000000..b004e6e56
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/events.py
@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import typing
+
+from .types.chat_completion_message_tool_call_function import ChatCompletionMessageToolCallFunction
+from .types.extended_chunk_delta_tool_call import ExtendedChunkDeltaToolCall
+from .types.model_message_delta_event import ModelMessageDeltaEvent
+from .types.model_message_event import ModelMessageEvent
+from .types.tool_call import ToolCall
+from .types.turn_streaming_event import TurnStreamingEvent
+
+
+def is_event_delta(event: object) -> typing.TypeGuard[ModelMessageDeltaEvent]:
+ return getattr(event, "type", None) == "model.message.delta"
+
+
+def merge_event_delta(
+ base: TurnStreamingEvent | ModelMessageEvent,
+ delta: ModelMessageDeltaEvent,
+) -> None:
+ """Merge a `model.message.delta` into its matching `model.message` in place."""
+ if base.type != "model.message":
+ return
+ if base.id != delta.id:
+ return
+
+ if delta.content is not None and len(delta.content) > 0:
+ if base.content is None or isinstance(base.content, str):
+ base.content = f"{base.content or ''}{delta.content}"
+
+ if delta.reasoning_content is not None and len(delta.reasoning_content) > 0:
+ base.reasoning_content = f"{base.reasoning_content or ''}{delta.reasoning_content}"
+
+ if delta.refusal is not None:
+ base.refusal = delta.refusal
+
+ if delta.finish_reason is not None:
+ base.finish_reason = delta.finish_reason
+
+ if delta.usage is not None:
+ base.usage = delta.usage
+
+ if delta.tool_calls is not None and len(delta.tool_calls) > 0:
+ if base.tool_calls is None:
+ base.tool_calls = []
+ for delta_tool_call in delta.tool_calls:
+ _merge_tool_call_delta(base.tool_calls, delta_tool_call)
+
+
+def _merge_tool_call_delta(
+ tool_calls: list[ToolCall],
+ delta_tool_call: ExtendedChunkDeltaToolCall,
+) -> None:
+ index = delta_tool_call.index
+ if index < len(tool_calls):
+ existing = tool_calls[index]
+ if delta_tool_call.id is not None:
+ existing.id = delta_tool_call.id
+ if delta_tool_call.tool_info is not None:
+ existing.tool_info = delta_tool_call.tool_info
+ if delta_tool_call.provider_specific_fields is not None:
+ existing.provider_specific_fields = delta_tool_call.provider_specific_fields
+ if delta_tool_call.function is not None:
+ if delta_tool_call.function.name is not None:
+ existing.function.name = delta_tool_call.function.name
+ if delta_tool_call.function.arguments is not None:
+ existing.function.arguments += delta_tool_call.function.arguments
+ return
+
+ # Streaming tool calls are emitted in index order; ignore sparse gaps.
+ if index != len(tool_calls):
+ return
+
+ tool_id = delta_tool_call.id
+ name = None if delta_tool_call.function is None else delta_tool_call.function.name
+ tool_info = delta_tool_call.tool_info
+ if tool_id is None or name is None or tool_info is None:
+ return
+
+ arguments = ""
+ if delta_tool_call.function is not None and delta_tool_call.function.arguments is not None:
+ arguments = delta_tool_call.function.arguments
+
+ created = ToolCall(
+ id=tool_id,
+ type="function",
+ function=ChatCompletionMessageToolCallFunction(name=name, arguments=arguments),
+ tool_info=tool_info,
+ )
+ if delta_tool_call.provider_specific_fields is not None:
+ created.provider_specific_fields = delta_tool_call.provider_specific_fields
+ tool_calls.append(created)
diff --git a/python/trueforge_sdk/tests/test_events.py b/python/trueforge_sdk/tests/test_events.py
new file mode 100644
index 000000000..fca2f1467
--- /dev/null
+++ b/python/trueforge_sdk/tests/test_events.py
@@ -0,0 +1,133 @@
+from trueforge_sdk.events import is_event_delta, merge_event_delta
+from trueforge_sdk.types.chat_completion_chunk_delta_tool_call_function import (
+ ChatCompletionChunkDeltaToolCallFunction,
+)
+from trueforge_sdk.types.chat_completion_content_part_text import ChatCompletionContentPartText
+from trueforge_sdk.types.extended_chunk_delta_tool_call import ExtendedChunkDeltaToolCall
+from trueforge_sdk.types.finish_reason import FinishReason
+from trueforge_sdk.types.model_message_delta_event import ModelMessageDeltaEvent
+from trueforge_sdk.types.model_message_event import ModelMessageEvent
+from trueforge_sdk.types.true_foundry_system_tool_info import TrueFoundrySystemToolInfo
+from trueforge_sdk.types.turn_created_event import TurnCreatedEvent
+from trueforge_sdk.types.turn_state_running import TurnStateRunning
+
+
+def _base(**overrides: object) -> ModelMessageEvent:
+ fields: dict[str, object] = {
+ "id": "msg-1",
+ "created_at": "2026-01-01T00:00:00Z",
+ "thread_id": "main",
+ "type": "model.message",
+ }
+ fields.update(overrides)
+ return ModelMessageEvent(**fields)
+
+
+def _delta(**overrides: object) -> ModelMessageDeltaEvent:
+ fields: dict[str, object] = {
+ "id": "msg-1",
+ "thread_id": "main",
+ "type": "model.message.delta",
+ }
+ fields.update(overrides)
+ return ModelMessageDeltaEvent(**fields)
+
+
+def test_is_event_delta() -> None:
+ assert is_event_delta(_delta())
+ assert not is_event_delta(_base())
+
+
+def test_merge_appends_content_and_reasoning() -> None:
+ base = _base(content="Hel")
+ merge_event_delta(base, _delta(content="lo", reasoning_content="think"))
+ assert base.content == "Hello"
+ assert base.reasoning_content == "think"
+
+
+def test_merge_noops_on_id_or_type_mismatch() -> None:
+ base = _base(content="Hel")
+ merge_event_delta(base, _delta(id="other", content="lo"))
+ assert base.content == "Hel"
+
+ created = TurnCreatedEvent(
+ id="t1",
+ created_at="2026-01-01T00:00:00Z",
+ turn_id="turn-1",
+ state=TurnStateRunning(),
+ )
+ merge_event_delta(created, _delta(content="lo"))
+
+
+def test_merge_tool_calls_by_index() -> None:
+ base = _base()
+ info = TrueFoundrySystemToolInfo(name="ask_user_question", type="truefoundry-system")
+ merge_event_delta(
+ base,
+ _delta(
+ tool_calls=[
+ ExtendedChunkDeltaToolCall(
+ index=0,
+ id="call-1",
+ type="function",
+ function=ChatCompletionChunkDeltaToolCallFunction(name="ask_user_question", arguments='{"q":'),
+ tool_info=info,
+ )
+ ]
+ ),
+ )
+ merge_event_delta(
+ base,
+ _delta(
+ tool_calls=[
+ ExtendedChunkDeltaToolCall(
+ index=0,
+ function=ChatCompletionChunkDeltaToolCallFunction(arguments='"hi"}'),
+ )
+ ]
+ ),
+ )
+ assert base.tool_calls is not None
+ assert len(base.tool_calls) == 1
+ assert base.tool_calls[0].function.arguments == '{"q":"hi"}'
+
+
+def test_merge_ignores_sparse_tool_call_index() -> None:
+ base = _base()
+ info = TrueFoundrySystemToolInfo(name="ask_user_question", type="truefoundry-system")
+ merge_event_delta(
+ base,
+ _delta(
+ tool_calls=[
+ ExtendedChunkDeltaToolCall(
+ index=1,
+ id="call-2",
+ function=ChatCompletionChunkDeltaToolCallFunction(name="ask_user_question", arguments="{}"),
+ tool_info=info,
+ )
+ ]
+ ),
+ )
+ assert base.tool_calls == []
+
+
+def test_merge_does_not_append_to_content_parts() -> None:
+ parts = [ChatCompletionContentPartText(text="Hel", type="text")]
+ base = _base(content=parts)
+ merge_event_delta(base, _delta(content="lo"))
+ assert isinstance(base.content, list)
+ assert base.content[0].text == "Hel"
+
+
+def test_merge_overwrites_finish_reason_and_refusal() -> None:
+ base = _base()
+ merge_event_delta(base, _delta(finish_reason=FinishReason.STOP, refusal="no"))
+ assert base.finish_reason == FinishReason.STOP
+ assert base.refusal == "no"
+
+
+def test_helpers_are_not_on_package_root() -> None:
+ import trueforge_sdk
+
+ assert not hasattr(trueforge_sdk, "is_event_delta")
+ assert not hasattr(trueforge_sdk, "merge_event_delta")