[WIP] API updates, documentation

Author: wdoppenberg

rust-sdk/Cargo.lock

@@ -8,3 +8,6 @@ serde = { version = "^1", features = ["derive"] }
 serde_json = "^1"
 uuid = { version = "1.17.0", features = ["v4", "serde"] }
 
+[patch.crates-io]
+ag-ui-core = { path = "crates/ag-ui-core" }
+ag-ui-client = { path = "crates/ag-ui-client" }

rust-sdk/Cargo.toml

@@ -1,9 +1,11 @@
-- [ ] Agent "state" handling
-- [ ] Run parameters DX improvements
+- [ ] Agent "state" handling (possibly with actor model)
+- [X] Run parameters DX improvements
 - [ ] More elaborate error handling (especially for deserialization errors)
 - [ ] Retries?
 - [ ] Documentation
 - [ ] JSON Patch types in `ag-ui-core`
 - [ ] Builder patterns on most-used structs
 - [ ] Review EventHandler & Mutations
 - [ ] Subscriber + mutations DX improvement
+- [ ] Not all messages are being saved?
+- [ ] SSE review

rust-sdk/TODO

@@ -1,3 +1,3 @@
 fn main() {
-    println!("Hello, world!");
+    todo!()
 }

rust-sdk/crates/ag-ui-cli/src/main.rs

@@ -24,9 +24,6 @@ tokio = "1.36.0"
 env_logger = "0.11.8"
 tokio = { version = "1.36.0", features = ["full"] }
 
-[patch.crates-io]
-ag-ui-core = { path = "../ag-ui-core" }
-
 [[example]]
 name = "http-agent"
 path = "examples/basic_agent.rs"

rust-sdk/crates/ag-ui-client/Cargo.toml

@@ -1 +1,36 @@
 # AG-UI Rust Client
+
+Rust client for working with the AG-UI protocol. The client API has been designed to mimic the Typescript client as 
+close as possible. However, a key difference is that state & messages are not yet an attribute of an implementation of 
+[`Agent`](src/agent.rs) because it would require `&mut self` for straightforward implementations. This is a work in 
+progress.
+
+## Example
+
+For each example make sure to read the instructions on starting the associated AG-UI server.
+
+### Basic 
+
+```rust
+use std::error::Error;
+use ag_ui_client::{core::types::Message, Agent, HttpAgent, RunAgentParams};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>>{
+	let agent = HttpAgent::builder()
+		.with_url_str("http://127.0.0.1:3001/")?
+		.build()?;
+
+	let message = Message::new_user("Can you give me the current temperature in New York?");
+	// Create run parameters
+	let params = RunAgentParams::new().add_message(message);
+
+	// Run the agent with the subscriber
+	let result = agent.run_agent(&params, ()).await?;
+
+    println!("{:#?}", result);
+    Ok(())
+}
+```
+
+For more examples check the [examples folder](examples). 

rust-sdk/crates/ag-ui-client/README.md

@@ -1,48 +1,19 @@
-use ag_ui_client::Agent;
-use ag_ui_client::agent::{AgentError, RunAgentParams};
-use ag_ui_client::http::HttpAgent;
-
-use ag_ui_core::JsonValue;
-use ag_ui_core::types::ids::MessageId;
-use ag_ui_core::types::message::Message;
-use log::info;
-use reqwest::Url;
+use ag_ui_client::{Agent, HttpAgent, RunAgentParams, core::types::Message};
+use std::error::Error;
 
 #[tokio::main]
-async fn main() -> Result<(), AgentError> {
-    env_logger::Builder::from_default_env().init();
-
-    // Base URL for the mock server
-    // Run the following command to start the mock server:
-    // `uv run rust-sdk/crates/ag-ui-client/scripts/basic_agent.py`
-    let base_url = Url::parse("http://127.0.0.1:3001/").map_err(|e| AgentError::ConfigError {
-        message: e.to_string(),
-    })?;
-
-    // Create agent
-    let agent = HttpAgent::builder().with_url(base_url).build()?;
+async fn main() -> Result<(), Box<dyn Error>> {
+    let agent = HttpAgent::builder()
+        .with_url_str("http://127.0.0.1:3001/")?
+        .build()?;
 
+    let message = Message::new_user("Can you give me the current temperature in New York?");
     // Create run parameters
-    let params = RunAgentParams::<JsonValue, _> {
-        forwarded_props: Some(serde_json::json!({})),
-        messages: vec![Message::User {
-            id: MessageId::random(),
-            content: "Can you give me the current temperature in New York?".into(),
-            name: None,
-        }],
-        ..Default::default()
-    };
-
-    info!("Running agent...");
+    let params = RunAgentParams::new().add_message(message);
 
     // Run the agent with the subscriber
     let result = agent.run_agent(&params, ()).await?;
 
-    info!(
-        "Agent run completed with {} new messages",
-        result.new_messages.len()
-    );
-    info!("Result: {:#?}", result);
-
+    println!("{:#?}", result);
     Ok(())
 }

rust-sdk/crates/ag-ui-client/examples/basic_agent.rs

@@ -1,37 +1,25 @@
 use std::error::Error;
-use std::fmt::{Debug, Display, Formatter};
+use std::fmt::Debug;
 
 use async_trait::async_trait;
 use log::info;
 use reqwest::Url;
-use reqwest::header::HeaderMap;
 use serde::{Deserialize, Serialize};
 
 use ag_ui_client::agent::{AgentError, AgentStateMutation, RunAgentParams};
+use ag_ui_client::core::AgentState;
+use ag_ui_client::core::event::{StateDeltaEvent, StateSnapshotEvent};
+use ag_ui_client::core::types::Message;
 use ag_ui_client::subscriber::{AgentSubscriber, AgentSubscriberParams};
 use ag_ui_client::{Agent, HttpAgent};
-use ag_ui_core::event::{StateDeltaEvent, StateSnapshotEvent};
-use ag_ui_core::types::ids::MessageId;
-use ag_ui_core::types::message::Message;
-use ag_ui_core::{AgentState, FwdProps, JsonValue};
 
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Hash)]
+#[serde(rename_all = "lowercase")]
 pub enum StepStatus {
-    #[serde(rename = "pending")]
     Pending,
-    #[serde(rename = "completed")]
     Completed,
 }
 
-impl Display for StepStatus {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        match self {
-            StepStatus::Pending => write!(f, "pending"),
-            StepStatus::Completed => write!(f, "completed"),
-        }
-    }
-}
-
 impl Default for StepStatus {
     fn default() -> Self {
         StepStatus::Pending
@@ -71,14 +59,11 @@ impl GenerativeUiSubscriber {
 }
 
 #[async_trait]
-impl<FwdPropsT> AgentSubscriber<Plan, FwdPropsT> for GenerativeUiSubscriber
-where
-    FwdPropsT: FwdProps + Debug,
-{
+impl AgentSubscriber<Plan, ()> for GenerativeUiSubscriber {
     async fn on_state_snapshot_event(
         &self,
         event: &StateSnapshotEvent<Plan>,
-        _params: AgentSubscriberParams<'async_trait, Plan, FwdPropsT>,
+        _params: AgentSubscriberParams<'async_trait, Plan, ()>,
     ) -> Result<AgentStateMutation<Plan>, AgentError> {
         info!("State snapshot received:");
         let plan = &event.snapshot;
@@ -96,7 +81,7 @@ where
     async fn on_state_delta_event(
         &self,
         event: &StateDeltaEvent,
-        _params: AgentSubscriberParams<'async_trait, Plan, FwdPropsT>,
+        _params: AgentSubscriberParams<'async_trait, Plan, ()>,
     ) -> Result<AgentStateMutation<Plan>, AgentError> {
         info!("State delta received:");
         for patch in &event.delta {
@@ -131,7 +116,7 @@ where
 
     async fn on_state_changed(
         &self,
-        params: AgentSubscriberParams<'async_trait, Plan, FwdPropsT>,
+        params: AgentSubscriberParams<'async_trait, Plan, ()>,
     ) -> Result<(), AgentError> {
         info!("Overall state changed");
         let completed_steps = params
@@ -162,20 +147,16 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Create the HTTP agent
     let agent = HttpAgent::builder().with_url(base_url).build()?;
 
+    let message = Message::new_user(
+        "I need to organize a birthday party for my friend. Can you help me \
+				create a plan? When you have created the plan, please fully execute it.",
+    );
+
     let subscriber = GenerativeUiSubscriber::new();
 
     // Create run parameters for testing generative UI with planning
-    let params = RunAgentParams {
-        messages: vec![Message::User {
-            id: MessageId::random(),
-            content: "I need to organize a birthday party for my friend. Can you help me \
-				create a plan? When you have created the plan, please fully execute it."
-                .into(),
-            name: None,
-        }],
-        forwarded_props: Some(JsonValue::Null),
-        ..Default::default()
-    };
+    // State & FwdProps types are defined by GenerativeUiSubscriber
+    let params = RunAgentParams::new_typed().add_message(message);
 
     info!("Starting generative UI agent run...");
     info!("Testing planning functionality with state snapshots and deltas");

rust-sdk/crates/ag-ui-client/examples/generative_ui.rs

@@ -1,25 +1,23 @@
 use ag_ui_client::agent::{AgentError, AgentStateMutation, RunAgentParams};
-use ag_ui_client::http::HttpAgent;
-use ag_ui_client::subscriber::{AgentSubscriber, AgentSubscriberParams};
-use ag_ui_core::event::{
+use ag_ui_client::core::JsonValue;
+use ag_ui_client::core::event::{
     CustomEvent, Event, MessagesSnapshotEvent, RawEvent, RunErrorEvent, RunFinishedEvent,
     RunStartedEvent, StateDeltaEvent, StateSnapshotEvent, StepFinishedEvent, StepStartedEvent,
     TextMessageChunkEvent, TextMessageContentEvent, TextMessageEndEvent, TextMessageStartEvent,
     ThinkingEndEvent, ThinkingStartEvent, ThinkingTextMessageContentEvent,
     ThinkingTextMessageEndEvent, ThinkingTextMessageStartEvent, ToolCallArgsEvent,
     ToolCallChunkEvent, ToolCallEndEvent, ToolCallResultEvent, ToolCallStartEvent,
 };
-use ag_ui_core::{AgentState, FwdProps, JsonValue};
+use ag_ui_client::http::HttpAgent;
+use ag_ui_client::subscriber::{AgentSubscriber, AgentSubscriberParams};
 use async_trait::async_trait;
 use reqwest::Url;
-use reqwest::header::{HeaderMap, HeaderValue};
 use std::error::Error;
 
 // Import our simple subscriber implementation
 use ag_ui_client::Agent;
-use ag_ui_core::types::ids::MessageId;
-use ag_ui_core::types::message::Message;
-use ag_ui_core::types::tool::ToolCall;
+use ag_ui_client::core::types::{Message, ToolCall};
+use ag_ui_client::core::{AgentState, FwdProps};
 use log::info;
 use std::collections::HashMap;
 use std::fmt::Debug;
@@ -40,18 +38,9 @@ async fn main() -> Result<(), Box<dyn Error>> {
     let subscriber = LoggingSubscriber::new(true);
 
     // Create run parameters
-    let params = RunAgentParams {
-        run_id: None,
-        tools: None,
-        context: None,
-        forwarded_props: Some(serde_json::json!({})),
-        messages: vec![Message::User {
-            id: MessageId::random(),
-            content: "Can you give me the current temperature in New York?".into(),
-            name: None,
-        }],
-        state: serde_json::json!({}),
-    };
+    let params = RunAgentParams::new().add_message(Message::new_user(
+        "Can you give me the current temperature in New York?",
+    ));
 
     info!("Running agent with simple subscriber...");