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.mdnew file mode 100644index 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.mdindex 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/.gitignoreindex 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 filediff --git a/docs/api/overview.mdx b/docs/api/overview.mdxindex 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.mdxindex 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 wrapimport osfrom trueforge_sdk import TrueForge+from trueforge_sdk.events import is_event_delta, merge_event_deltaclient = 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] = eventif 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 wrapimport osfrom trueforge_sdk import TrueForge+from trueforge_sdk.events import is_event_delta, merge_event_deltaclient = 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 = Nonestream = 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] = eventif 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.typimport jsonimport osfrom trueforge_sdk import TrueForge+from trueforge_sdk.events import is_event_delta, merge_event_deltaclient = 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 = Nonestream = 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] = eventif 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 wrapimport osfrom trueforge_sdk import TrueForge+from trueforge_sdk.events import is_event_delta, merge_event_deltaclient = 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.dataif 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] = eventelse:# 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.```mermaidsequenceDiagram@@ -951,6 +962,7 @@ for await (const { data: event } of stream.withMetadata()) {```python Python wrapimport osfrom trueforge_sdk import TrueForge+from trueforge_sdk.events import is_event_delta, merge_event_deltaclient = 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)continuebucket = 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] = eventif 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 activitydiff --git a/packages/trueforge/src/apis/codesnippet-templates/python.ts b/packages/trueforge/src/apis/codesnippet-templates/python.tsindex 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-sdkfrom trueforge_sdk import TrueForge+from trueforge_sdk.events import is_event_delta, merge_event_deltaclient = 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-sdkdiff --git a/packages/trueforge/tests/unit/apis/agents.test.ts b/packages/trueforge/tests/unit/apis/agents.test.tsindex 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/.fernignorenew file mode 100644index 000000000..98192b7ca--- /dev/null+++ b/python/trueforge_sdk/.fernignore@@ -0,0 +1,2 @@+src/trueforge_sdk/events.py+tests/test_events.pydiff --git a/python/trueforge_sdk/src/trueforge_sdk/events.py b/python/trueforge_sdk/src/trueforge_sdk/events.pynew file mode 100644index 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.pynew file mode 100644index 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")