From 864675213928b755b56f12f18859582e22f594a4 Mon Sep 17 00:00:00 2001
From: worldmozara <worldmozara@163.com>
Date: Tue, 14 Jul 2026 17:45:47 +0800
Subject: [PATCH] core/agent: add AgentEvent types and ChatClient protocol

---
 src/plyngent/agent/client.py | 30 ++++++++++++++++++++++++++++++
 src/plyngent/agent/events.py | 30 ++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 src/plyngent/agent/client.py
 create mode 100644 src/plyngent/agent/events.py

diff --git a/src/plyngent/agent/client.py b/src/plyngent/agent/client.py
new file mode 100644
index 0000000..6711f71
--- /dev/null
+++ b/src/plyngent/agent/client.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, Protocol, overload
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from plyngent.lmproto.openai_compatible.model import (
+        ChatCompletionChunk,
+        ChatCompletionResponse,
+        ChatCompletionsParam,
+    )
+
+
+class ChatClient(Protocol):
+    """Structural protocol for OpenAI-compatible chat completion clients."""
+
+    @overload
+    async def chat_completions(
+        self, param: ChatCompletionsParam, *, stream: Literal[False] = False
+    ) -> ChatCompletionResponse: ...
+
+    @overload
+    async def chat_completions(
+        self, param: ChatCompletionsParam, *, stream: Literal[True]
+    ) -> AsyncIterator[ChatCompletionChunk]: ...
+
+    async def chat_completions(
+        self, param: ChatCompletionsParam, *, stream: bool = False
+    ) -> ChatCompletionResponse | AsyncIterator[ChatCompletionChunk]: ...
diff --git a/src/plyngent/agent/events.py b/src/plyngent/agent/events.py
new file mode 100644
index 0000000..1cd9c55
--- /dev/null
+++ b/src/plyngent/agent/events.py
@@ -0,0 +1,30 @@
+from msgspec import Struct
+
+from plyngent.lmproto.openai_compatible.model import (  # noqa: TC001
+    AnyAssistantToolCall,
+    AssistantChatMessage,
+    ToolChatMessage,
+)
+
+
+class TextDeltaEvent(Struct, tag_field="type", tag="text_delta"):
+    content: str
+
+
+class AssistantMessageEvent(Struct, tag_field="type", tag="assistant_message"):
+    message: AssistantChatMessage
+
+
+class ToolCallEvent(Struct, tag_field="type", tag="tool_call"):
+    tool_call: AnyAssistantToolCall
+
+
+class ToolResultEvent(Struct, tag_field="type", tag="tool_result"):
+    message: ToolChatMessage
+
+
+class MaxRoundsEvent(Struct, tag_field="type", tag="max_rounds"):
+    rounds: int
+
+
+type AgentEvent = TextDeltaEvent | AssistantMessageEvent | ToolCallEvent | ToolResultEvent | MaxRoundsEvent