agentrs_core/
lib.rs

1#![forbid(unsafe_code)]
2
3//! Foundational traits and shared types for the `agentrs` SDK.
4
5pub mod error;
6pub mod streaming;
7pub mod testing;
8pub mod types;
9
10use async_trait::async_trait;
11use futures::stream::BoxStream;
12
13pub use error::{AgentError, BoxError, McpError, MemoryError, ProviderError, Result, ToolError};
14pub use types::{
15    AgentEvent, AgentOutput, CompletionRequest, CompletionResponse, ContentPart, Message,
16    MessageContent, Role, StopReason, StreamChunk, ToolCall, ToolCallDelta, ToolContent,
17    ToolDefinition, ToolOutput, Usage,
18};
19
20/// Unified contract for chat-completion capable LLM providers.
21#[async_trait]
22pub trait LlmProvider: Send + Sync + 'static {
23    /// Executes a single non-streaming completion request.
24    async fn complete(&self, req: CompletionRequest) -> Result<CompletionResponse>;
25
26    /// Executes a streaming completion request.
27    async fn stream(&self, req: CompletionRequest) -> Result<BoxStream<'_, Result<StreamChunk>>>;
28
29    /// Returns the provider name.
30    fn name(&self) -> &str;
31}
32
33/// Unified contract for agent tools.
34#[async_trait]
35pub trait Tool: Send + Sync + 'static {
36    /// Returns the public tool name.
37    fn name(&self) -> &str;
38
39    /// Returns a short tool description.
40    fn description(&self) -> &str;
41
42    /// Returns a JSON schema describing the tool input.
43    fn schema(&self) -> serde_json::Value;
44
45    /// Executes the tool.
46    async fn call(&self, input: serde_json::Value) -> Result<ToolOutput>;
47}
48
49/// Contract for agent memory backends.
50#[async_trait]
51pub trait Memory: Send + Sync + 'static {
52    /// Stores a message under a logical key.
53    async fn store(&mut self, key: &str, value: Message) -> Result<()>;
54
55    /// Retrieves relevant messages for a query.
56    async fn retrieve(&self, query: &str, limit: usize) -> Result<Vec<Message>>;
57
58    /// Returns the full conversation history.
59    async fn history(&self) -> Result<Vec<Message>>;
60
61    /// Clears the memory backend.
62    async fn clear(&mut self) -> Result<()>;
63}
64
65/// Contract for executable agents.
66#[async_trait]
67pub trait Agent: Send + Sync + 'static {
68    /// Runs the agent to completion for a user input.
69    async fn run(&mut self, input: &str) -> Result<AgentOutput>;
70
71    /// Runs the agent as an event stream.
72    async fn stream_run(&mut self, input: &str) -> Result<BoxStream<'_, Result<AgentEvent>>>;
73}
agentrs_core/lib.rs

agentrs_core/
lib.rs
