V2 redesign: Platform-agnostic runtime with zero-cost trait-based abstractions

[Copilot]

Complete rewrite of Amico as a platform-agnostic AI agent runtime. V1 lacked architectural clarity and relied on dynamic dispatch; V2 adopts modern patterns from Vercel's AI SDK with Rust's zero-cost abstraction principles.

Architecture

Four-layer design with trait-based abstractions:

• amico-models: Provider-agnostic model interface categorized by capability (language, image, video, speech, embedding)
• amico-system: Platform abstraction for tools, side-effects, and permissions
• amico-runtime: Workflow execution supporting both long-lived (OS processes) and short-lived (serverless) runtimes
• amico-workflows: Preset patterns (tool loops, ReAct, chain-of-thought, reflection)
• amico: Event-driven handler interface similar to web frameworks

Design Principles

• Traits + generics over dyn dispatch for compile-time polymorphism
• impl Future instead of Pin<Box<dyn Future>>
• Lifetimes and references instead of Box/Arc where possible
• Platform-agnostic: OS, browsers, mobile, embedded

Example

use amico::{EventHandler, workflows::ToolLoopAgent};

struct MyAgent {
    agent: ToolLoopAgent<Model, Tools, Context>,
}

impl EventHandler<MessageEvent> for MyAgent {
    type Context = AgentContext;
    type Response = MessageResponse;
    type Error = HandlerError;
    
    async fn handle(&self, event: MessageEvent, ctx: &Self::Context) 
        -> Result<Self::Response, Self::Error> 
    {
        self.agent.execute(ctx, event.content).await
            .map(MessageResponse::from)
    }
}

Migration

V1 completely removed (6 crates, 127 files). No backward compatibility. Architecture documented in ARCHITECTURE.md with Haskell-style type signatures and Rust trait examples.

Original prompt

Background

Amico is an agent development framework for Rust.

This is the V1 of Amico. As you can see, when building this framework a year ago, we don't have much experience on building AI agents. We have no idea what a good AI agent framework should look like.

Nowadays, good AI agent frameworks come up, and our team have more mature understanding on AI agents. We want to restart this project - let's build Amico V2.

Amico V1 does have some good design though. For example, the event-based architecture, and the platform agnostic archtecture is a great idea.

System Design

Now you should re-design the system from the start. Here's our understanding on what Amico should provide:

Amico should be a platform-agnostic runtime for AI agents. As a framework, it provides a platform for developers to develop their business logic - just like web frameworks like axum or rocket.

Like vercel's AI sdk (in typescript), the framework should first abstract away "models" and parameters. Just categorize models by its responsibility - language, image generation, video, speech, embedding, etc. Agent "business logic" only performs on tools, prompts, context and categorized models. We can provide some presets like "tool loop agents" based on this layer. You can research how vercel's AI sdk do this. We can learn from it.

Another layer is step-by-step agent workflows and the runtime. Workflows runs on runtimes. Some runtimes lives long, like the operating system or cloudflare workers. Some runtimes lives short, like cloud functions. Vercel developed a "workflow" SDK for long-running workflows on short-lived cloud functions. The runtime in Amico should be abstract enough for any unified workflow logic to run on that.

The bottom level is the "system". This layer defines how agents can watch for and perform side-effects. This is how agent do the actual work, usually via tools. The "system" layer enable agents to observe and change the real world. The system layer usually depends on the underlying system - OS, browsers, mobile, or even embedded devices. Different system provides different interfaces. We can also enable secured, permissioned access to system resources like files or networks. Task scheduling is also implemented on this layer, but we can utilize existing utilities like tokio, embessy, etc.

We can provide an event handler interface for developers - just like REST endpoint handlers for web frameworks. Developers may define when an event is triggered, some workflow is executed, and which tools / models etc. should be used with the workflow.

Design Patterns

Always use traits + generics to describe and combine abstract concepts in high abstraction level utilities, and always avoid boxing or dynamic dispatching.

Compile-time types or statics evaluation is welcomed. Referencing and lifetime marking is encouraged, rather than using Boxes or Arcs.

Abstract asynchronous tasks with Future traits, not Pin Box dyn Futures, unless doing so is safe on a known platform - never use this in high-level utilities.

Organize crates properly. Seperate core utilities, and combine them in a high-level "entry" crate.

Your Task

You should deprecate ALL V1 implementations - this is a total of shit. PLEASE REMOVE ALL OF THEM.

You should create a doc to design the architecture. Keep functional design in mind. The full system should be describable with a set of haskell-style function definitions. In the doc, you should describe the system in this way along with natural language descriptions and rust traits and type examples.

Remove all the existing crates, and create new ones to represent your architecture. The system don't need to be functional now. Just show your conceptual design.

Created from VS Code.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.