[WIP] Builder; package metadata fields; README.md

wdoppenberg · wdoppenberg · commit 38a905789c69 · 2025-08-12T14:59:54.000+02:00
diff --git a/rust-sdk/TODO b/rust-sdk/TODO
@@ -1,5 +1,9 @@
-* Agent "state" handling
-* Run parameters DX improvements
-* More elaborate error handling (especially for deserialization errors)
-* Retries?
-* Documentation
+- [ ] Agent "state" handling
+- [ ] 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
diff --git a/rust-sdk/crates/ag-ui-client/Cargo.toml b/rust-sdk/crates/ag-ui-client/Cargo.toml
@@ -2,6 +2,9 @@
 name = "ag-ui-client"
 version = "0.1.0"
 edition = "2024"
+description = "Client library for the AG-UI protocol."
+license = "MIT"
+readme = "README.md"
 
 [dependencies]
 ag-ui-core = { path = "../ag-ui-core"}
diff --git a/rust-sdk/crates/ag-ui-client/README.md b/rust-sdk/crates/ag-ui-client/README.md
@@ -0,0 +1 @@
+# AG-UI Rust Client
diff --git a/rust-sdk/crates/ag-ui-client/examples/basic_agent.rs b/rust-sdk/crates/ag-ui-client/examples/basic_agent.rs
@@ -1,41 +1,36 @@
+use ag_ui_client::Agent;
 use ag_ui_client::agent::{AgentError, RunAgentParams};
 use ag_ui_client::http::HttpAgent;
-use reqwest::Url;
-use reqwest::header::{HeaderMap, HeaderValue};
 
-use ag_ui_client::Agent;
+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;
 
 #[tokio::main]
 async fn main() -> Result<(), AgentError> {
-    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
-
-    // Create a base URL for the mock server
-    // Note: Make sure the mock server is running on this address
-    let base_url = Url::parse("http://127.0.0.1:3001/")
-        .map_err(|e| AgentError::ConfigError {message: e.to_string() })?;
+    env_logger::Builder::from_default_env().init();
 
-    // Create headers
-    let mut headers = HeaderMap::new();
-    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
+    // 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 the HTTP agent
-    let agent = HttpAgent::new(base_url, headers);
+    // Create agent
+    let agent = HttpAgent::builder().with_url(base_url).build()?;
 
     // Create run parameters
-    let params = RunAgentParams {
-        run_id: None,
-        tools: None,
-        context: None,
+    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,
         }],
-        state: serde_json::json!({}),
+        ..Default::default()
     };
 
     info!("Running agent...");
diff --git a/rust-sdk/crates/ag-ui-client/examples/generative_ui.rs b/rust-sdk/crates/ag-ui-client/examples/generative_ui.rs
@@ -152,13 +152,15 @@ where
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
-    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+    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/generative_ui.py`
     let base_url = Url::parse("http://127.0.0.1:3001/")?;
-    let headers = HeaderMap::new();
 
     // Create the HTTP agent
-    let agent = HttpAgent::new(base_url, headers);
+    let agent = HttpAgent::builder().with_url(base_url).build()?;
 
     let subscriber = GenerativeUiSubscriber::new();
 
diff --git a/rust-sdk/crates/ag-ui-client/examples/logging_subscriber.rs b/rust-sdk/crates/ag-ui-client/examples/logging_subscriber.rs
@@ -27,16 +27,14 @@ use std::fmt::Debug;
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
     env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
-    // Create a base URL for the mock server
-    // Note: Make sure the mock server is running on this address
-    let base_url = Url::parse("http://127.0.0.1:3001/")?;
 
-    // Create headers
-    let mut headers = HeaderMap::new();
-    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
+    // 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/")?;
 
     // Create the HTTP agent
-    let agent = HttpAgent::new(base_url, headers);
+    let agent = HttpAgent::builder().with_url(base_url).build()?;
 
     // Create a simple subscriber
     let subscriber = LoggingSubscriber::new(true);
diff --git a/rust-sdk/crates/ag-ui-client/examples/shared_state.rs b/rust-sdk/crates/ag-ui-client/examples/shared_state.rs
@@ -6,13 +6,12 @@ use ag_ui_core::types::ids::MessageId;
 use ag_ui_core::types::message::Message;
 use ag_ui_core::{AgentState, FwdProps, JsonValue};
 use async_trait::async_trait;
+
 use log::info;
 use reqwest::Url;
-use reqwest::header::{HeaderMap, HeaderValue};
 use serde::{Deserialize, Serialize};
 use std::error::Error;
 use std::fmt::{Debug, Display, Formatter};
-use std::sync::Arc;
 
 #[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq, Eq, Hash)]
 pub enum SkillLevel {
@@ -146,13 +145,15 @@ where
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn Error>> {
-    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+    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/shared_state.py`
     let base_url = Url::parse("http://127.0.0.1:3001/")?;
-    let headers = HeaderMap::new();
 
     // Create the HTTP agent
-    let agent = HttpAgent::new(base_url, headers);
+    let agent = HttpAgent::builder().with_url(base_url).build()?;
 
     let subscriber = RecipeSubscriber::new();
 
diff --git a/rust-sdk/crates/ag-ui-client/examples/sse_example.rs b/rust-sdk/crates/ag-ui-client/examples/sse_example.rs
@@ -1,5 +1,4 @@
 use ag_ui_client::sse::SseResponseExt;
-use ag_ui_core::event::Event;
 use futures::StreamExt;
 use serde::Deserialize;
 use std::error::Error;
diff --git a/rust-sdk/crates/ag-ui-client/src/agent.rs b/rust-sdk/crates/ag-ui-client/src/agent.rs
@@ -41,7 +41,7 @@ where
 
 /// Parameters for running an agent.
 #[derive(Debug, Clone, Default)]
-pub struct RunAgentParams<StateT: AgentState, FwdPropsT = JsonValue> {
+pub struct RunAgentParams<StateT: AgentState = JsonValue, FwdPropsT: FwdProps = JsonValue> {
     pub run_id: Option<RunId>,
     pub tools: Option<Vec<Tool>>,
     pub context: Option<Vec<Context>>,
@@ -90,6 +90,7 @@ pub enum AgentError {
     },
 }
 
+// TODO: Expand documentation
 /// Agent trait
 #[async_trait::async_trait]
 pub trait Agent<StateT = JsonValue, FwdPropsT = JsonValue>: Send + Sync
@@ -102,6 +103,7 @@ where
         input: &RunAgentInput<StateT, FwdPropsT>,
     ) -> Result<EventStream<'async_trait, StateT>, AgentError>;
 
+    // TODO: Expand documentation
     /// The main execution method, containing the full pipeline logic.
     async fn run_agent(
         &self,
diff --git a/rust-sdk/crates/ag-ui-client/src/event_handler.rs b/rust-sdk/crates/ag-ui-client/src/event_handler.rs
@@ -1,13 +1,13 @@
-use json_patch::PatchOperation;
-use serde_json::Value as JsonValue;
-use std::collections::{HashMap, HashSet};
-
 use ag_ui_core::event::Event;
 use ag_ui_core::types::ids::MessageId;
 use ag_ui_core::types::input::RunAgentInput;
 use ag_ui_core::types::message::{FunctionCall, Message, Role};
 use ag_ui_core::types::tool::ToolCall;
 use ag_ui_core::{AgentState, FwdProps};
+use json_patch::PatchOperation;
+use log::error;
+use serde_json::Value as JsonValue;
+use std::collections::{HashMap, HashSet};
 
 use crate::agent::{AgentError, AgentStateMutation};
 use crate::subscriber::{AgentSubscriberParams, Subscribers};
@@ -528,6 +528,7 @@ where
     }
 
     pub async fn on_error(&self, error: &AgentError) -> Result<(), AgentError> {
+        error!("Agent error: {error}");
         for subscriber in &self.subscribers {
             let _mutation = subscriber
                 .on_run_failed(error, self.to_subscriber_params())
diff --git a/rust-sdk/crates/ag-ui-client/src/http.rs b/rust-sdk/crates/ag-ui-client/src/http.rs
@@ -1,15 +1,17 @@
 use async_trait::async_trait;
 use futures::StreamExt;
 use log::{debug, trace};
-use reqwest::header::{HeaderMap, HeaderValue};
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
 use reqwest::{Client as HttpClient, Url};
+use std::str::FromStr;
 
 use ag_ui_core::event::Event;
 use ag_ui_core::types::input::RunAgentInput;
 use ag_ui_core::{AgentState, FwdProps};
 
 use crate::Agent;
 use crate::agent::AgentError;
+use crate::agent::AgentError::SerializationError;
 use crate::sse::SseResponseExt;
 use crate::stream::EventStream;
 
@@ -20,16 +22,125 @@ pub struct HttpAgent {
 }
 
 impl HttpAgent {
-    pub fn new(base_url: Url, header_map: impl Into<HeaderMap>) -> Self {
+    pub fn new(base_url: Url, header_map: HeaderMap) -> Self {
         let http_client = HttpClient::new();
-        let mut header_map = header_map.into();
+        let mut header_map: HeaderMap = header_map;
+
         header_map.insert("Content-Type", HeaderValue::from_static("application/json"));
         Self {
             http_client,
             base_url,
             header_map,
         }
     }
+
+    pub fn builder() -> HttpAgentBuilder {
+        HttpAgentBuilder::new()
+    }
+}
+
+pub struct HttpAgentBuilder {
+    base_url: Option<Url>,
+    header_map: HeaderMap,
+    http_client: Option<HttpClient>,
+}
+
+impl HttpAgentBuilder {
+    pub fn new() -> Self {
+        Self {
+            base_url: None,
+            header_map: HeaderMap::new(),
+            http_client: None,
+        }
+    }
+
+    /// Set the base URL from a Url instance
+    pub fn with_url(mut self, base_url: Url) -> Self {
+        self.base_url = Some(base_url);
+        self
+    }
+
+    /// Set the base URL from a string, returning Result for validation
+    pub fn with_url_str(mut self, url: &str) -> Result<Self, AgentError> {
+        let parsed_url = Url::parse(url).map_err(|e| AgentError::ConfigError {
+            message: format!("Invalid URL '{url}': {e}"),
+        })?;
+        self.base_url = Some(parsed_url);
+        Ok(self)
+    }
+
+    /// Replace all headers with the provided HeaderMap
+    pub fn with_headers(mut self, header_map: HeaderMap) -> Self {
+        self.header_map = header_map;
+        self
+    }
+
+    /// Add a single header by name and value strings
+    pub fn with_header(mut self, name: &str, value: &str) -> Result<Self, AgentError> {
+        let header_name = HeaderName::from_str(name).map_err(|e| AgentError::ConfigError {
+            message: format!("Invalid header name '{value}': {e}"),
+        })?;
+        let header_value = HeaderValue::from_str(value).map_err(|e| AgentError::ConfigError {
+            message: format!("Invalid header value '{value}': {e}"),
+        })?;
+        self.header_map.insert(header_name, header_value);
+        Ok(self)
+    }
+
+    /// Add a header using HeaderName and HeaderValue directly
+    pub fn with_header_typed(mut self, name: HeaderName, value: HeaderValue) -> Self {
+        self.header_map.insert(name, value);
+        self
+    }
+
+    /// Add an authorization bearer token
+    pub fn with_bearer_token(self, token: &str) -> Result<Self, AgentError> {
+        let auth_value = format!("Bearer {token}");
+        self.with_header("Authorization", &auth_value)
+    }
+
+    /// Set a custom HTTP client
+    pub fn with_http_client(mut self, client: HttpClient) -> Self {
+        self.http_client = Some(client);
+        self
+    }
+
+    /// Set request timeout in seconds
+    pub fn with_timeout(mut self, timeout_secs: u64) -> Self {
+        let client = HttpClient::builder()
+            .timeout(std::time::Duration::from_secs(timeout_secs))
+            .build()
+            .unwrap_or_else(|_| HttpClient::new());
+        self.http_client = Some(client);
+        self
+    }
+
+    pub fn build(self) -> Result<HttpAgent, AgentError> {
+        let base_url = self.base_url.ok_or(AgentError::ConfigError {
+            message: "Base URL is required".to_string(),
+        })?;
+
+        // Validate URL scheme
+        if !["http", "https"].contains(&base_url.scheme()) {
+            return Err(AgentError::ConfigError {
+                message: format!("Unsupported URL scheme: {}", base_url.scheme()),
+            });
+        }
+
+        let http_client = self.http_client.unwrap_or_default();
+
+        Ok(HttpAgent {
+            http_client,
+            base_url,
+            header_map: self.header_map,
+        })
+    }
+}
+
+impl Default for HttpAgentBuilder {
+    fn default() -> Self {
+        Self::new()
+    }
 }
 
 impl From<reqwest::Error> for AgentError {
@@ -63,7 +174,8 @@ impl<StateT: AgentState, FwdPropsT: FwdProps> Agent<StateT, FwdPropsT> for HttpA
                 Ok(event) => {
                     trace!("Received event: {event:?}");
 
-                    let event_data: Event<StateT> = serde_json::from_str(&event.data)?;
+                    let event_data: Event<StateT> = serde_json::from_str(&event.data)
+                        .map_err(|err| SerializationError { source: err })?;
                     debug!("Deserialized event: {event_data:?}");
 
                     Ok(event_data)
diff --git a/rust-sdk/crates/ag-ui-client/src/sse.rs b/rust-sdk/crates/ag-ui-client/src/sse.rs
@@ -65,6 +65,7 @@ pub trait SseResponseExt {
 }
 
 impl SseResponseExt for Response {
+    #[allow(clippy::manual_async_fn)]
     fn event_source(
         self,
     ) -> impl Future<Output = impl Stream<Item = Result<SseEvent, SseError>>> + Send {
@@ -83,6 +84,7 @@ struct SseEventProcessor;
 
 impl SseEventProcessor {
     /// Creates a new SSE event processor
+    #[allow(clippy::new_ret_no_self)]
     fn new(
         stream: impl Stream<Item = Result<Bytes, reqwest::Error>> + 'static,
     ) -> impl Stream<Item = Result<SseEvent, SseError>> {
diff --git a/rust-sdk/crates/ag-ui-client/src/subscriber.rs b/rust-sdk/crates/ag-ui-client/src/subscriber.rs
@@ -349,7 +349,6 @@ where
     }
 }
 
-
 impl<'a, StateT, FwdPropsT> IntoIterator for &'a Subscribers<StateT, FwdPropsT>
 where
     StateT: AgentState,
diff --git a/rust-sdk/crates/ag-ui-client/tests/http_agent_test.rs b/rust-sdk/crates/ag-ui-client/tests/http_agent_test.rs
diff --git a/rust-sdk/crates/ag-ui-core/Cargo.toml b/rust-sdk/crates/ag-ui-core/Cargo.toml
diff --git a/rust-sdk/crates/ag-ui-core/README.md b/rust-sdk/crates/ag-ui-core/README.md
diff --git a/rust-sdk/crates/ag-ui-core/src/types/message.rs b/rust-sdk/crates/ag-ui-core/src/types/message.rs

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`use ag_ui_client::sse::SseResponseExt;`
`2`		`-use ag_ui_core::event::Event;`
`3`	`2`	`use futures::StreamExt;`
`4`	`3`	`use serde::Deserialize;`
`5`	`4`	`use std::error::Error;`