aether-agent-core 0.6.22

A minimal Rust library for building AI agents with MCP tool integration
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

use crate::events::{ToolEvent, TurnEvent};
use std::sync::{Arc, Mutex};

use crate::events::{AgentEvent, LlmCallOutcome, LlmCallPurpose, TurnOutcome};

/// A recorded agent event stream (as seen by an
/// [`AgentObserver`](crate::events::AgentObserver)), with assertion helpers
/// for trace-shaped tests. Build one with
/// [`TestAgentBuilder::run_trace`](crate::testing::TestAgentBuilder::run_trace).
pub struct AgentTrace {
    events: Vec<AgentEvent>,
}

impl AgentTrace {
    pub fn from_events(events: Vec<AgentEvent>) -> Self {
        Self { events }
    }

    pub fn from_observer_events(events: &Arc<Mutex<Vec<AgentEvent>>>) -> Self {
        Self::from_events(events.lock().unwrap().clone())
    }

    pub fn events(&self) -> &[AgentEvent] {
        &self.events
    }

    pub fn assert_names(&self, expected: &[&str]) {
        assert_eq!(map_event_names(&self.events), expected, "unexpected trace: {:?}", self.events);
    }

    /// Index into [`Self::events`] of the first event matching `predicate`.
    pub fn position(&self, predicate: impl Fn(&AgentEvent) -> bool) -> usize {
        self.events
            .iter()
            .position(predicate)
            .unwrap_or_else(|| panic!("expected event not found in trace: {:?}", self.events))
    }

    /// Indexes into [`Self::events`] of every event matching `predicate`.
    pub fn positions(&self, predicate: impl Fn(&AgentEvent) -> bool) -> Vec<usize> {
        self.events.iter().enumerate().filter(|(_, event)| predicate(event)).map(|(index, _)| index).collect()
    }

    pub fn call_usage(&self, for_purpose: LlmCallPurpose) -> Option<llm::TokenUsage> {
        self.events.iter().find_map(|event| match event {
            AgentEvent::Turn(TurnEvent::LlmCallEnded { purpose, outcome: LlmCallOutcome::Completed { usage, .. } })
                if *purpose == for_purpose =>
            {
                *usage
            }
            _ => None,
        })
    }
}

/// Maps trace-relevant events to compact names for order assertions,
/// skipping content messages.
pub fn map_event_names(events: &[AgentEvent]) -> Vec<String> {
    events
        .iter()
        .filter_map(|event| match event {
            AgentEvent::Turn(TurnEvent::Started { .. }) => Some("turn_started".to_string()),
            AgentEvent::Turn(TurnEvent::Ended { outcome }) => {
                let outcome = match outcome {
                    TurnOutcome::Completed => "completed",
                    TurnOutcome::Cancelled => "cancelled",
                    TurnOutcome::Failed { .. } => "failed",
                };
                Some(format!("turn_ended:{outcome}"))
            }
            AgentEvent::Turn(TurnEvent::RetryScheduled { purpose, attempt, .. }) => {
                Some(format!("retry_scheduled:{purpose:?}:{attempt}"))
            }
            AgentEvent::Turn(TurnEvent::LlmCallStarted { purpose, attempt, .. }) => {
                Some(format!("call_started:{purpose:?}:{attempt}"))
            }
            AgentEvent::Turn(TurnEvent::LlmCallEnded { purpose, outcome }) => {
                let outcome = match outcome {
                    LlmCallOutcome::Completed { .. } => "completed",
                    LlmCallOutcome::Failed { will_retry: true, .. } => "failed_will_retry",
                    LlmCallOutcome::Failed { will_retry: false, .. } => "failed_terminal",
                    LlmCallOutcome::Cancelled => "cancelled",
                };
                Some(format!("call_ended:{purpose:?}:{outcome}"))
            }
            AgentEvent::Tool(ToolEvent::ExecutionStarted { .. }) => Some("tool_execution_started".to_string()),
            AgentEvent::Tool(ToolEvent::DefinitionsUpdated { .. }) => Some("tool_definitions".to_string()),
            _ => None,
        })
        .collect()
}