Merge pull request #30 from irshadnilam/runtime-fixes

feat(radkit):  Single-agent runtime with better api structure

Author: grainier

README.md

@@ -48,7 +48,7 @@ schemars = "1"
 
 #### With Agent Server Runtime
 
-To include the `DefaultRuntime` and enable the full A2A agent server capabilities (on native targets), enable the `runtime` feature:
+To include the runtime server handle and enable the full A2A agent server capabilities (on native targets), enable the `runtime` feature:
 
 ```toml
 [dependencies]
@@ -63,7 +63,7 @@ schemars = "1"
 
 Radkit ships optional capabilities that you can opt into per target:
 
-- `runtime`: Enables the native `DefaultRuntime`, HTTP server, tracing, and other dependencies required to run A2A-compliant agents locally.
+- `runtime`: Enables the native runtime handle, HTTP server, tracing, and other dependencies required to run A2A-compliant agents locally.
 - `dev-ui`: Builds on top of `runtime` and serves an interactive UI (native-only) where you can trigger tasks, and inspect streaming output.
 
 ## Core Concepts
@@ -924,31 +924,27 @@ impl SkillHandler for ReportGeneratorSkill {
 ```rust
 use radkit::agent::{Agent, AgentDefinition};
 use radkit::models::providers::AnthropicLlm;
-use radkit::runtime::DefaultRuntime;
+use radkit::runtime::Runtime;
 
-pub fn configure_agents() -> Vec<AgentDefinition> {
-    let my_agent = Agent::builder()
+pub fn configure_agent() -> AgentDefinition {
+    Agent::builder()
         .with_id("my-agent-v1")
         .with_name("My A2A Agent")
         .with_description("An intelligent agent with multiple skills")
         // Skills automatically provide metadata from #[skill] macro
         .with_skill(ProfileExtractorSkill)
         .with_skill(ReportGeneratorSkill)
         .with_skill(DataAnalysisSkill)
-        .build();
-
-    vec![my_agent]
+        .build()
 }
 
 // Local development
 #[cfg(not(all(target_os = "wasi", target_env = "p1")))]
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let llm = AnthropicLlm::from_env("claude-sonnet-4-5-20250929")?;
-    let runtime = DefaultRuntime::new(llm);
-
-    runtime
-        .agents(configure_agents())
+    Runtime::builder(configure_agent(), llm)
+        .build()
         .serve("127.0.0.1:8080")
         .await?;
 

docs/src/content/docs/a2a/composing-agents.md

@@ -35,27 +35,24 @@ use radkit::runtime::Runtime;
 # }
 
 
-// This function defines your agents.
-pub fn configure_agents() -> Vec<AgentDefinition> {
-    let my_agent = Agent::builder()
+// This function defines your agent.
+pub fn configure_agent() -> AgentDefinition {
+    Agent::builder()
         .with_id("my-hr-agent-v1")
         .with_name("HR Assistant Agent")
         .with_description("An intelligent agent for handling HR tasks like resume processing and report generation.")
         // Add the skills to the agent
         .with_skill(ProfileExtractorSkill)
         .with_skill(ReportGeneratorSkill)
-        .build();
-
-    // You can define and return multiple agents from the same project
-    vec![my_agent]
+        .build()
 }
 ```
 
 The `Agent::builder()` creates a serializable `AgentDefinition`. This definition is the blueprint for your agent that gets deployed.
 
 ## Running the Agent Locally
 
-To test your agent, you can run it locally. The `DefaultRuntime` provides a simple, A2A-compliant web server for this purpose.
+To test your agent, you can run it locally. The runtime provides a simple, A2A-compliant web server for this purpose.
 
 To enable the server, you must enable the `runtime` feature for Radkit in your `Cargo.toml`:
 
@@ -70,21 +67,18 @@ Then, you can add a `main` function to run the server.
 ```rust
 # use radkit::agent::AgentDefinition;
 # use radkit::models::providers::AnthropicLlm;
-# use radkit::runtime::DefaultRuntime;
-# pub fn configure_agents() -> Vec<AgentDefinition> { vec![] }
+# use radkit::runtime::Runtime;
+# pub fn configure_agent() -> AgentDefinition { unimplemented!() }
 // This main function will only be compiled for native targets, not for WASM.
 #[cfg(not(all(target_os = "wasi", target_env = "p1")))]
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // 1. Create an LLM instance
     let llm = AnthropicLlm::from_env("claude-sonnet-4-5-20250929")?;
 
-    // 2. Create a default runtime environment with the LLM
-    let runtime = DefaultRuntime::new(llm);
-
-    // 3. Add the agents and start the server
-    runtime
-        .agents(configure_agents())
+    // 2. Create a runtime environment with the agent + LLM
+    Runtime::builder(configure_agent(), llm)
+        .build()
         .serve("127.0.0.1:8080")
         .await?;
 

docs/src/content/docs/architecture/deployment.md

@@ -27,11 +27,11 @@ Once the `.wasm` module is uploaded, the cloud platform takes over:
 
 1.  **Instantiation**: The platform loads the `.wasm` module into a high-performance, secure WASM runtime (like Wasmtime).
 
-2.  **Discovery via Configuration Function**: The runtime calls a known function in the module to retrieve the `AgentDefinition`s you have defined. This is typically the `configure_agents()` function.
+2.  **Discovery via Configuration Function**: The runtime calls a known function in the module to retrieve the `AgentDefinition` you have defined. This is typically the `configure_agent()` function.
 
     ```rust
-    pub fn configure_agents() -> Vec<AgentDefinition> {
-        // ... return agent definitions
+    pub fn configure_agent() -> AgentDefinition {
+        // ... return an agent definition
     }
     ```
 
@@ -44,4 +44,4 @@ Once the `.wasm` module is uploaded, the cloud platform takes over:
 -   **Speed**: `.wasm` files are small and can be uploaded and started in seconds. WASM runtimes have near-zero cold start times, allowing agents to scale down to zero and respond to requests instantly.
 -   **Security**: Every agent runs in its own secure, memory-safe sandbox, completely isolated from other agents. The WASI interface ensures that the agent can only access the resources it has been explicitly granted permission to use.
 -   **Portability**: The same `.wasm` file can be run on any server that has a compliant WASM runtime, regardless of the underlying CPU architecture or operating system.
--   **Scalability**: The lightweight nature of WASM instances allows for massive scaling, with thousands of agents running concurrently on a single physical machine.
+-   **Scalability**: The lightweight nature of WASM instances allows for massive scaling, with thousands of agents running concurrently on a single physical machine.

docs/src/content/docs/architecture/runtime.md

@@ -1,50 +1,80 @@
 ---
 title: Runtime
-description: Learn about Radkit's Runtime trait and how it provides service abstraction for agents.
+description: Learn about Radkit's AgentRuntime trait and how it provides service abstraction for agents.
 ---
 
 
 
-The core of Radkit's architecture is the `Runtime` trait. It acts as a centralized **service hub** or dependency injection container for your agent. Instead of passing many different service handles (like a database connector, a logger, etc.) to every function, your `SkillHandler`s receive a single, unified reference: `&dyn Runtime`.
+The core of Radkit's architecture is the `AgentRuntime` trait. It acts as a centralized **service hub** or dependency injection container for your agent. Instead of passing many different service handles (like a database connector, a logger, etc.) to every function, your `SkillHandler`s receive a single, unified reference: `&dyn AgentRuntime`.
 
 This design keeps your agent logic clean, decoupled from infrastructure, and highly portable.
 
-## The `Runtime` Trait
+## The `AgentRuntime` Trait
 
-All runtime environments, whether for local development or cloud deployment, must implement the `Runtime` trait. This guarantees a consistent interface for your skills.
+All runtime environments, whether for local development or cloud deployment, must implement the `AgentRuntime` trait. This guarantees a consistent interface for your skills.
 
 ```rust
-pub trait Runtime {
-    fn task_manager(&self) -> Arc<dyn TaskManager>;
-    fn memory_service(&self) -> Arc<dyn MemoryService>;
-    fn logging_service(&self) -> Arc<dyn LoggingService>;
-    // ... other services
+pub trait AgentRuntime {
+    fn auth(&self) -> Arc<dyn AuthService>;
+    fn memory(&self) -> Arc<dyn MemoryService>;
+    fn logging(&self) -> Arc<dyn LoggingService>;
+    fn default_llm(&self) -> Arc<dyn BaseLlm>;
 }
 ```
 
 Your skill code is written against this abstraction, not a concrete implementation. A skill simply asks the runtime for a service:
 
 ```rust
-// Inside a SkillHandler method...
-let memory_service = runtime.memory_service();
-memory_service.save(auth_ctx, "some_key", &data).await?;
+let memory = runtime.memory();
+memory.save(auth_ctx, "some_key", &data).await?;
 ```
 
 The skill doesn't know or care if `memory_service` is writing to an in-memory map for local testing or a massive, persistent cloud database.
 
 ## Core Services
 
-The `Runtime` provides access to a set of essential services, each defined by its own trait.
+`AgentRuntime` provides access to a set of essential services, each defined by its own trait.
 
--   **`TaskManager`**: A Data Access Object (DAO) for persisting and retrieving the state of A2A `Task`s and their event histories. This is crucial for multi-turn conversations and auditing.
+-   **`TaskManager`**: A Data Access Object (DAO) for persisting and retrieving the state of A2A `Task`s and their event histories. This is crucial for multi-turn conversations and auditing. The core runtime uses it internally so skill authors don't have to.
 -   **`MemoryService`**: Provides a persistent, tenant-aware key-value store. This is ideal for giving your agent long-term memory or for implementing Retrieval-Augmented Generation (RAG).
 -   **`LoggingService`**: A structured logging interface that streams logs to the console during local development or to a cloud observability UI in production.
 -   **`AuthService`**: Identifies the current user and tenant, ensuring that all other services are properly namespaced and data is kept secure.
 
 ## Provided Runtimes
 
-Radkit provides a `DefaultRuntime` for local development, and the architecture allows for custom runtimes for production or specialized environments.
+Radkit provides a `RuntimeBuilder` plus a concrete `Runtime` implementation for local development, and the architecture allows for custom runtimes for production or specialized environments.
 
-### `DefaultRuntime`
+### `Runtime` (native implementation)
 
-Included with the `runtime` feature flag, `DefaultRuntime` is an out-of-the-box implementation that works on both native and WASM targets. It provides simple, in-memory versions of all the core services, allowing you to get up and running instantly with no configuration.
+Included with the `runtime` feature flag, the builder returns an out-of-the-box runtime that works on both native and WASM targets. It provides simple, in-memory versions of all the core services, allowing you to get up and running instantly with no configuration.
+
+```rust
+use radkit::models::providers::OpenRouterLlm;
+use radkit::runtime::Runtime;
+
+# fn configure_agent() -> radkit::agent::AgentDefinition {
+#     radkit::agent::Agent::builder()
+#         .with_id("hr-agent")
+#         .with_name("HR Agent")
+#         .build()
+# }
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let llm = OpenRouterLlm::from_env("anthropic/claude-3.5-sonnet")?;
+    Runtime::builder(configure_agent(), llm)
+        .build()
+        .serve("127.0.0.1:8080")
+        .await?;
+    Ok(())
+}
+```
+
+The runtime hosts **exactly one agent definition** per process. When `.serve(..)` is called it automatically exposes the A2A HTTP surface at the root of the bound address:
+
+- `/.well-known/agent-card.json` – serves the agent card
+- `/rpc` – JSON-RPC entry point for `message/send`, `message/stream`, `tasks/resubscribe`, etc.
+- `/message:stream` – streaming API for Server-Sent Events
+- `/tasks/{task_id}/subscribe` – SSE resubscribe endpoint that mirrors the A2A spec
+
+If the optional `dev-ui` feature is enabled, the same server also mounts `/ui/*` routes and serves the React console for the single configured agent.

examples/hr_agent/agent.rs

@@ -1,6 +1,6 @@
 use radkit::agent::{Agent, AgentDefinition};
 use radkit::models::providers::OpenRouterLlm;
-use radkit::runtime::DefaultRuntime;
+use radkit::runtime::Runtime;
 
 // --- Skill Implementations ---
 // The modular skills are defined in their own files.
@@ -9,8 +9,8 @@ use hr_agent_skills::create_it_accounts::CreateItAccountsSkill;
 use hr_agent_skills::generate_onboarding_plan::GenerateOnboardingPlanSkill;
 use hr_agent_skills::summarize_resume::SummarizeResumeSkill;
 
-pub fn configure_agents() -> Vec<AgentDefinition> {
-    let hr_agent = Agent::builder()
+pub fn configure_agent() -> AgentDefinition {
+    Agent::builder()
         .with_id("hr-agent-v1")
         .with_name("HR Agent")
         .with_description(
@@ -22,26 +22,17 @@ pub fn configure_agents() -> Vec<AgentDefinition> {
         .with_skill(SummarizeResumeSkill)
         .with_skill(GenerateOnboardingPlanSkill)
         .with_skill(CreateItAccountsSkill)
-        .build();
-
-    vec![hr_agent]
+        .build()
 }
 
 /// The main entry point for local, native development and testing.
 /// This function is excluded from WASM builds via the `#[cfg]` attribute.
 #[cfg(not(all(target_os = "wasi", target_env = "p1")))]
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // DefaultRuntime requires an LLM instance
     let llm = OpenRouterLlm::from_env("anthropic/claude-3.5-sonnet")?;
-    let runtime = DefaultRuntime::new(llm);
-
-    // The `serve` method on the local runtime takes the agent definitions
-    // and starts a local A2A-compliant web server.
-    // Agent metadata is automatically extracted from #[skill] macros
-    // and exposed via the agent card endpoint.
-    runtime
-        .agents(configure_agents())
+    Runtime::builder(configure_agent(), llm)
+        .build()
         .serve("127.0.0.1:8080")
         .await?;
 

examples/hr_agent/hr_agent_skills/create_it_accounts.rs

@@ -5,7 +5,7 @@ use radkit::errors::AgentError;
 use radkit::macros::skill;
 use radkit::models::Content;
 use radkit::runtime::context::{Context, TaskContext};
-use radkit::runtime::Runtime;
+use radkit::runtime::AgentRuntime;
 
 // --- Skill Logic Implementation ---
 
@@ -33,7 +33,7 @@ impl SkillHandler for CreateItAccountsSkill {
         &self,
         task_context: &mut TaskContext,
         _context: &Context,
-        _runtime: &dyn Runtime,
+        _runtime: &dyn AgentRuntime,
         content: Content,
     ) -> Result<OnRequestResult, AgentError> {
         // Extract role and name from content

examples/hr_agent/hr_agent_skills/generate_onboarding_plan.rs

@@ -7,7 +7,7 @@ use radkit::macros::skill;
 use radkit::models::providers::OpenRouterLlm;
 use radkit::models::Content;
 use radkit::runtime::context::{Context, TaskContext};
-use radkit::runtime::{MemoryServiceExt, Runtime};
+use radkit::runtime::{AgentRuntime, MemoryServiceExt};
 
 fn generate_onboarding_tasks() -> LlmFunction<Vec<String>> {
     let llm = OpenRouterLlm::from_env("anthropic/claude-3.5-sonnet")
@@ -44,7 +44,7 @@ impl SkillHandler for GenerateOnboardingPlanSkill {
         &self,
         task_context: &mut TaskContext,
         context: &Context,
-        runtime: &dyn Runtime,
+        runtime: &dyn AgentRuntime,
         _content: Content,
     ) -> Result<OnRequestResult, AgentError> {
         // Send intermediate update

examples/hr_agent/hr_agent_skills/summarize_resume.rs

@@ -8,8 +8,8 @@ use radkit::macros::{skill, tool, LLMOutput};
 use radkit::models::providers::OpenRouterLlm;
 use radkit::models::Content;
 use radkit::runtime::context::{Context, TaskContext};
-use radkit::runtime::{MemoryServiceExt, Runtime};
-use radkit::tools::ToolResult;
+use radkit::runtime::{AgentRuntime, MemoryServiceExt};
+use radkit::tools::{BaseTool, FunctionTool, ToolResult};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_json::json;
@@ -164,7 +164,7 @@ impl SkillHandler for SummarizeResumeSkill {
         &self,
         task_context: &mut TaskContext,
         context: &Context,
-        runtime: &dyn Runtime,
+        runtime: &dyn AgentRuntime,
         content: Content,
     ) -> Result<OnRequestResult, AgentError> {
         // Send intermediate status update
@@ -230,7 +230,7 @@ impl SkillHandler for SummarizeResumeSkill {
         &self,
         task_context: &mut TaskContext,
         _context: &Context,
-        runtime: &dyn Runtime,
+        runtime: &dyn AgentRuntime,
         content: Content,
     ) -> Result<OnInputResult, AgentError> {
         let slot: ResumeInputSlot = task_context.load_slot()?.unwrap();

radkit-macros/tests/skill_tests.rs

@@ -2,7 +2,7 @@ use radkit::agent::{OnRequestResult, RegisteredSkill, SkillHandler};
 use radkit::errors::AgentError;
 use radkit::models::Content;
 use radkit::runtime::context::{Context, TaskContext};
-use radkit::runtime::Runtime;
+use radkit::runtime::AgentRuntime;
 use radkit_macros::skill;
 
 // Test 1: Basic skill with required fields only
@@ -22,7 +22,7 @@ impl SkillHandler for TestSkill {
         &self,
         _task_context: &mut TaskContext,
         _context: &Context,
-        _runtime: &dyn Runtime,
+        _runtime: &dyn AgentRuntime,
         _content: Content,
     ) -> Result<OnRequestResult, AgentError> {
         Ok(OnRequestResult::Completed {
@@ -57,7 +57,7 @@ impl SkillHandler for FullSkill {
         &self,
         _task_context: &mut TaskContext,
         _context: &Context,
-        _runtime: &dyn Runtime,
+        _runtime: &dyn AgentRuntime,
         _content: Content,
     ) -> Result<OnRequestResult, AgentError> {
         Ok(OnRequestResult::Completed {
@@ -92,7 +92,7 @@ impl SkillHandler for EmptyArraysSkill {
         &self,
         _task_context: &mut TaskContext,
         _context: &Context,
-        _runtime: &dyn Runtime,
+        _runtime: &dyn AgentRuntime,
         _content: Content,
     ) -> Result<OnRequestResult, AgentError> {
         Ok(OnRequestResult::Completed {