Improved run_agent API: added agent_id support, enhanced documentation, and updated subscriber handling.

Author: wdoppenberg

sdks/community/rust/crates/ag-ui-client/examples/basic_agent.rs

@@ -11,7 +11,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     // Create run parameters
     let params = RunAgentParams::new().add_message(message);
 
-    // Run the agent with the subscriber
+    // Run the agent without subscriber
     let result = agent.run_agent(&params, ()).await?;
 
     println!("{:#?}", result);

sdks/community/rust/crates/ag-ui-client/src/agent.rs

@@ -146,24 +146,49 @@ where
         input: &RunAgentInput<StateT, FwdPropsT>,
     ) -> Result<EventStream<'async_trait, StateT>, AgentError>;
 
-    // TODO: Expand documentation
-    /// The main execution method, containing the full pipeline logic.
+    /// Triggers an Agent run.
+    ///
+    /// # Parameters
+    /// * `params`: The run parameters as given in [RunAgentParams]
+    /// * `subscribers`: A (sequence of) type(s) that implement [crate::subscriber::AgentSubscriber];
+    /// can also be a unit type `()` or `None` if none are needed. Valid types are `T`, `(T,)`,
+    /// `Vec<T>`, `&[T]`, `()`, `Option<()>` where `T: AgentSubscriber`.
+    ///
+    /// # Examples
+    /// ```no_run
+    /// # use ag_ui_client::{Agent, HttpAgent, RunAgentParams, core::types::Message};
+    /// # use std::error::Error;
+    ///
+    /// # #[tokio::main]
+    /// # async fn main() -> Result<(), Box<dyn Error>> {
+    ///  let agent = HttpAgent::builder()
+    ///     .with_url_str("http://127.0.0.1:3000/")?
+    ///     .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 without subscriber
+    ///  let result = agent.run_agent(&params, ()).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
+    ///
+    /// # Notes
+    /// Currently the subscriber pattern is the only way to subscriber to an Agent run's lifecycle.
     async fn run_agent(
         &self,
         params: &RunAgentParams<StateT, FwdPropsT>,
         subscribers: impl IntoSubscribers<StateT, FwdPropsT>,
     ) -> Result<RunAgentResult<StateT>, AgentError> {
-        // TODO: Use Agent ID?
-        let _agent_id = AgentId::random();
-
         let input = RunAgentInput {
             thread_id: ThreadId::random(),
             run_id: params.run_id.clone().unwrap_or_else(RunId::random),
             state: params.state.clone(),
             messages: params.messages.clone(),
             tools: params.tools.clone(),
             context: params.context.clone(),
-            // TODO: Find suitable default value
             forwarded_props: params.forwarded_props.clone(),
         };
         let current_message_ids: HashSet<&MessageId> =
@@ -210,4 +235,8 @@ where
             new_state: event_handler.state,
         })
     }
+
+    fn agent_id(&self) -> Option<&AgentId> {
+        None
+    }
 }

sdks/community/rust/crates/ag-ui-client/src/http.rs

@@ -1,22 +1,23 @@
-use async_trait::async_trait;
-use futures::StreamExt;
-use log::{debug, trace};
-use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
-use reqwest::{Client as HttpClient, Url};
-use std::str::FromStr;
-
 use crate::Agent;
 use crate::agent::AgentError;
 use crate::core::event::Event;
 use crate::core::types::RunAgentInput;
 use crate::core::{AgentState, FwdProps};
 use crate::sse::SseResponseExt;
 use crate::stream::EventStream;
+use ag_ui_core::types::AgentId;
+use async_trait::async_trait;
+use futures::StreamExt;
+use log::{debug, trace};
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
+use reqwest::{Client as HttpClient, Url};
+use std::str::FromStr;
 
 pub struct HttpAgent {
     http_client: HttpClient,
     base_url: Url,
     header_map: HeaderMap,
+    agent_id: Option<AgentId>,
 }
 
 impl HttpAgent {
@@ -29,6 +30,7 @@ impl HttpAgent {
             http_client,
             base_url,
             header_map,
+            agent_id: None,
         }
     }
 
@@ -41,14 +43,13 @@ pub struct HttpAgentBuilder {
     base_url: Option<Url>,
     header_map: HeaderMap,
     http_client: Option<HttpClient>,
+    agent_id: Option<AgentId>,
 }
 
 impl HttpAgentBuilder {
     pub fn new() -> Self {
         Self {
-            base_url: None,
-            header_map: HeaderMap::new(),
-            http_client: None,
+            ..Default::default()
         }
     }
 
@@ -113,6 +114,12 @@ impl HttpAgentBuilder {
         self
     }
 
+    /// Set Agent ID
+    pub fn with_agent_id(mut self, agent_id: AgentId) -> Self {
+        self.agent_id = Some(agent_id);
+        self
+    }
+
     pub fn build(self) -> Result<HttpAgent, AgentError> {
         let base_url = self.base_url.ok_or(AgentError::Config {
             message: "Base URL is required".to_string(),
@@ -131,6 +138,7 @@ impl HttpAgentBuilder {
             http_client,
             base_url,
             header_map: self.header_map,
+            agent_id: self.agent_id,
         })
     }
 }
@@ -185,4 +193,8 @@ impl<StateT: AgentState, FwdPropsT: FwdProps> Agent<StateT, FwdPropsT> for HttpA
             .boxed();
         Ok(stream)
     }
+
+    fn agent_id(&self) -> Option<&AgentId> {
+        self.agent_id.as_ref()
+    }
 }

sdks/community/rust/crates/ag-ui-client/src/subscriber.rs

@@ -15,7 +15,7 @@ pub struct AgentSubscriberParams<'a, StateT: AgentState, FwdPropsT: FwdProps> {
     pub input: &'a RunAgentInput<StateT, FwdPropsT>,
 }
 
-/// Subscriber trait for handling agent events
+/// Subscriber trait for hooking into Agent run lifecycle events.
 #[async_trait::async_trait]
 pub trait AgentSubscriber<StateT = JsonValue, FwdPropsT = JsonValue>: Send + Sync
 where
@@ -376,6 +376,17 @@ where
     }
 }
 
+// Implementation for no subscriber
+impl<StateT, FwdPropsT> IntoSubscribers<StateT, FwdPropsT> for Option<()>
+where
+    StateT: AgentState,
+    FwdPropsT: FwdProps,
+{
+    fn into_subscribers(self) -> Subscribers<StateT, FwdPropsT> {
+        Subscribers::new(vec![])
+    }
+}
+
 // Implementation for single subscribers, as a unit-sized tuple
 impl<StateT, FwdPropsT, T> IntoSubscribers<StateT, FwdPropsT> for (T,)
 where