Client API (#147)

Implement interfaces to use AG-UI client side.

Author: mme

docs/concepts/events.mdx

@@ -95,12 +95,14 @@ The `RunFinished` event indicates that an agent has successfully completed all
 its work for the current run. Upon receiving this event, frontends should
 finalize any UI states that were waiting on the agent's completion. This event
 marks a clean termination point and indicates that no further processing will
-occur in this run unless explicitly requested.
+occur in this run unless explicitly requested. The optional `result` field can
+contain any output data produced by the agent run.
 
 | Property   | Description                   |
 | ---------- | ----------------------------- |
 | `threadId` | ID of the conversation thread |
 | `runId`    | ID of the agent run           |
+| `result`   | Optional result data from run |
 
 ### RunError
 

docs/docs.json

@@ -68,7 +68,12 @@
               },
               {
                 "group": "@ag-ui/client",
-                "pages": ["sdk/js/client/overview"]
+                "pages": [
+                  "sdk/js/client/overview",
+                  "sdk/js/client/abstract-agent",
+                  "sdk/js/client/http-agent",
+                  "sdk/js/client/subscriber"
+                ]
               },
               "sdk/js/encoder",
               "sdk/js/proto"

docs/sdk/js/client/abstract-agent.mdx

@@ -53,10 +53,10 @@ class MyAgent extends AbstractAgent {
 
 ### runAgent()
 
-The primary method for executing an agent and receiving the event stream.
+The primary method for executing an agent and processing the result.
 
 ```typescript
-runAgent(parameters?: RunAgentParameters): Observable<RuntimeProtocolEvent>
+runAgent(parameters?: RunAgentParameters, subscriber?: AgentSubscriber): Promise<RunAgentResult>
 ```
 
 #### Parameters
@@ -70,6 +70,31 @@ interface RunAgentParameters {
 }
 ```
 
+The optional `subscriber` parameter allows you to provide an
+[AgentSubscriber](/sdk/js/client/subscriber) for handling events during this
+specific run.
+
+#### Return Value
+
+```typescript
+interface RunAgentResult {
+  result: any // The final result returned by the agent
+  newMessages: Message[] // New messages added during this run
+}
+```
+
+### subscribe()
+
+Adds an [AgentSubscriber](/sdk/js/client/subscriber) to handle events across
+multiple agent runs.
+
+```typescript
+subscribe(subscriber: AgentSubscriber): { unsubscribe: () => void }
+```
+
+Returns an object with an `unsubscribe()` method to remove the subscriber when
+no longer needed.
+
 ### abortRun()
 
 Cancels the current agent execution.

docs/sdk/js/client/http-agent.mdx

@@ -39,21 +39,40 @@ const agent = new HttpAgent({
 
 ### runAgent()
 
-Executes the agent by making an HTTP request to the configured endpoint. Returns
-an observable event stream.
+Executes the agent by making an HTTP request to the configured endpoint.
 
 ```typescript
-runAgent(parameters?: RunHttpAgentConfig): Observable<RuntimeProtocolEvent>
+runAgent(parameters?: RunAgentParameters, subscriber?: AgentSubscriber): Promise<RunAgentResult>
 ```
 
 #### Parameters
 
+The `parameters` argument follows the standard `RunAgentParameters` interface.
+The optional `subscriber` parameter allows you to provide an
+[AgentSubscriber](/sdk/js/client/subscriber) for handling events during this
+specific run.
+
+#### Return Value
+
 ```typescript
-interface RunHttpAgentConfig extends RunAgentParameters {
-  abortController?: AbortController // For canceling the HTTP request
+interface RunAgentResult {
+  result: any // The final result returned by the agent
+  newMessages: Message[] // New messages added during this run
 }
 ```
 
+### subscribe()
+
+Adds an [AgentSubscriber](/sdk/js/client/subscriber) to handle events across
+multiple agent runs.
+
+```typescript
+subscribe(subscriber: AgentSubscriber): { unsubscribe: () => void }
+```
+
+Returns an object with an `unsubscribe()` method to remove the subscriber when
+no longer needed.
+
 ### abortRun()
 
 Cancels the current HTTP request using the AbortController.

docs/sdk/js/client/overview.mdx

@@ -60,3 +60,28 @@ Concrete implementation for HTTP-based agent connectivity:
   Ready-to-use HTTP implementation for agent connectivity, using a highly
   efficient event encoding format
 </Card>
+
+## AgentSubscriber
+
+Event-driven subscriber system for handling agent lifecycle events and state
+mutations during agent execution:
+
+- [Event Handlers](/sdk/js/client/subscriber#event-handlers) - Lifecycle,
+  message, tool call, and state events
+- [State Management](/sdk/js/client/subscriber#state-management) - Mutation
+  control and propagation handling
+- [Usage Examples](/sdk/js/client/subscriber#usage-examples) - Logging,
+  persistence, and error handling patterns
+- [Integration](/sdk/js/client/subscriber#integration-with-agents) - Registering
+  and using subscribers with agents
+
+<Card
+  title="AgentSubscriber Reference"
+  icon="bolt"
+  href="/sdk/js/client/subscriber"
+  color="#3B82F6"
+  iconType="solid"
+>
+  Comprehensive event system for reactive agent interaction and middleware-style
+  functionality
+</Card>