Struct DeepseekAgent 

pub struct DeepseekAgent { /* private fields */ }

An agent that combines a Conversation with a set of callable tools.

Build one with the fluent builder methods, then call chat to start a turn:

use ds_api::{DeepseekAgent, tool};
use serde_json::{Value, json};

struct MyTool;

#[tool]
impl ds_api::Tool for MyTool {
    async fn greet(&self, name: String) -> Value {
        json!({ "greeting": format!("Hello, {name}!") })
    }
}

let agent = DeepseekAgent::new("sk-...")
    .add_tool(MyTool);

Implementations

impl DeepseekAgent

pub fn new(token: impl Into<String>) -> Self

Create a new agent targeting the DeepSeek API with deepseek-chat.

pub fn custom( token: impl Into<String>, base_url: impl Into<String>, model: impl Into<String>, ) -> Self

Create an agent targeting an OpenAI-compatible provider.

All three parameters are set at construction time and never change:

use ds_api::DeepseekAgent;

let agent = DeepseekAgent::custom(
    "sk-or-...",
    "https://openrouter.ai/api/v1",
    "meta-llama/llama-3.3-70b-instruct:free",
);

pub fn add_tool<TT: Tool + 'static>(self, tool: TT) -> Self

Register a tool (builder-style, supports chaining).

The tool’s protocol-level function names are indexed so incoming tool-call requests from the model can be dispatched to the correct implementation.

pub fn chat(self, user_message: &str) -> AgentStream

Push a user message and return an AgentStream that drives the full agent loop (API calls + tool execution).

pub fn chat_from_history(self) -> AgentStream

Start an agent turn from the current history without pushing a new user message first.

Use this when you have already appended the user message manually (e.g. via push_user_message_with_name) and want to drive the agent loop from that point.

pub fn with_streaming(self) -> Self

Enable SSE streaming for each API turn (builder-style).

pub fn with_system_prompt(self, prompt: impl Into<String>) -> Self

Prepend a permanent system prompt to the conversation history (builder-style).

System messages added this way are never removed by the built-in summarizers.

pub fn with_summarizer(self, summarizer: impl Summarizer + 'static) -> Self

Replace the summarizer used for context-window management (builder-style).

pub fn with_history(self, history: Vec<Message>) -> Self

Seed the agent with an existing message history (builder-style).

Used to restore a conversation from persistent storage (e.g. SQLite) after a process restart. The messages are set directly on the underlying Conversation and will be included in the next API call.

Example

use ds_api::DeepseekAgent;
use ds_api::raw::request::message::{Message, Role};

let history = vec![
    Message::new(Role::User, "Hello"),
    Message::new(Role::Assistant, "Hi there!"),
];
let agent = DeepseekAgent::new("sk-...").with_history(history);

pub fn push_user_message_with_name(&mut self, text: &str, name: Option<&str>)

Append a user message with an optional display name to the conversation history.

The name field is passed through to the API as-is (OpenAI-compatible providers use it to distinguish speakers in a shared channel).

Example

use ds_api::DeepseekAgent;

let mut agent = DeepseekAgent::new("sk-...");
agent.push_user_message_with_name("What time is it?", Some("alice"));

pub fn history(&self) -> &[Message]

Read-only view of the current conversation history.

Returns all messages in order, including system prompts, user turns, assistant replies, tool calls, and tool results. Auto-summary messages inserted by the built-in summarizers are also included.

Example

use ds_api::DeepseekAgent;

let agent = DeepseekAgent::new("sk-...");
for msg in agent.history() {
    println!("{:?}: {:?}", msg.role, msg.content);
}

pub fn with_interrupt_channel(self) -> (Self, UnboundedSender<String>)

Attach an interrupt channel to the agent (builder-style).

Returns the agent and the sender half of the channel. Send any String through the UnboundedSender at any time; the message will be picked up after the current tool-execution round finishes and inserted into the conversation history as a Role::User message before the next API turn.

Example

use ds_api::DeepseekAgent;
use tokio::sync::mpsc;

let (agent, tx) = DeepseekAgent::new("sk-...")
    .with_interrupt_channel();

// In another task or callback:
tx.send("Actually, use Python instead.".into()).unwrap();