Crate neuromance_agent 

neuromance-agent

Agent framework for autonomous task execution with LLMs.

This crate provides high-level abstractions for building autonomous agents that can execute multi-step tasks, maintain state and memory, and use tools to accomplish goals. Agents wrap the lower-level neuromance::Core functionality with task management, state persistence, and sequential execution capabilities.

Core Components

• Agent: Trait defining the agent interface with state management and execution
• BaseAgent: Default implementation with conversation history and tool support
• AgentBuilder: Fluent builder for constructing agents with custom configuration
• AgentTask: Task abstraction for defining agent objectives and validation

Agent State Management

Agents maintain several types of state (from neuromance_common::agents):

• Conversation History: Full message history and responses
• Memory: Short-term and long-term memory with working memory for active data
• Context: Task definition, goals, constraints, and environment variables
• Statistics: Execution metrics like token usage and tool call counts

Example: Creating and Running an Agent

use neuromance_agent::{BaseAgent, Agent};
use neuromance::Core;
use neuromance_client::OpenAIClient;
use neuromance_common::{Config, Message};

// Create an LLM client
let config = Config::new("openai", "gpt-4")
    .with_api_key("sk-...");
let client = OpenAIClient::new(config)?;

// Build an agent
let mut agent = BaseAgent::builder("research-agent", client)
    .with_system_prompt("You are a research assistant that finds information.")
    .with_user_prompt("Find the population of Tokyo.")
    .build()?;

// Execute the agent
let response = agent.execute(None).await?;
println!("Agent response: {}", response.content.content);

Example: Using the Agent Builder

The AgentBuilder provides a fluent API for agent configuration:

use neuromance_agent::BaseAgent;
use neuromance_client::OpenAIClient;
use neuromance_common::Config;

let config = Config::new("openai", "gpt-4o-mini");
let client = OpenAIClient::new(config)?;

let agent = BaseAgent::builder("task-agent", client)
    .with_system_prompt("You are a task completion agent.")
    .with_user_prompt("Complete the following task: organize these files.")
    .with_max_turns(5)
    .with_auto_approve_tools(true)
    .build()?;

Task-Based Execution

The task module provides task abstractions for defining agent objectives:

use neuromance_agent::{AgentTask, BaseAgent};
use neuromance_common::Message;

// Define a task with validation
let task = AgentTask::new("research_task")
    .with_description("Research the history of Rust programming language")
    .with_validation(|response| {
        // Custom validation logic
        Ok(response.content.content.len() > 100)
    });

// Execute the task
let response = task.execute(&mut agent).await?;

Agent Lifecycle

Agents follow a standard lifecycle:

1. Creation: Built with configuration and system/user prompts
2. Execution: Process messages through LLM with tool support
3. State Updates: Maintain conversation history and statistics
4. Reset: Clear state for fresh execution (via Agent::reset)

Tool Integration

Agents automatically integrate with neuromance_tools for tool execution. Tools can be added to the agent’s Core instance and will be available during execution:

use neuromance_agent::BaseAgent;
use neuromance_tools::{ToolExecutor, ThinkTool};

let mut agent = BaseAgent::new("agent-id".to_string(), Core::new(client));

// Add tools to the agent's core
agent.core.tool_executor.add_tool(ThinkTool);

// Tools are now available during execution

Memory and Context

Agents maintain structured state via AgentState:

• Memory: Stores short-term context and long-term knowledge
• Context: Task definition, goals, constraints, environment
• Stats: Execution metrics for monitoring and debugging

This state can be serialized for persistence or debugging.

Re-exports

pub use builder::AgentBuilder;

pub use task::AgentTask;

pub use task::TaskResponse;

pub use task::TaskState;

Modules

builder

task

Structs

BaseAgent

Base agent implementation with common functionality

Traits

Agent