Multi-agent orchestration

Documentation Index

Fetch the complete documentation index at: https://cognis.vasanth.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​

What it is

let orch = MultiAgentOrchestrator::new(strategy)
    .add("name1", agent1)
    .add("name2", agent2);

let resp: AgentResponse = orch.run(input).await?;

​

Pick a strategy

use cognis::{AgentBuilder, MultiAgentOrchestrator, Sequential};
use cognis_llm::Client;

let planner = AgentBuilder::new().with_llm(Client::from_env()?)
    .with_system_prompt("Break the request into 3 numbered steps.").build()?;

let executor = AgentBuilder::new().with_llm(Client::from_env()?)
    .with_system_prompt("Receive a numbered plan; reply with one paragraph.").build()?;

let orch = MultiAgentOrchestrator::new(Sequential)
    .add("planner", planner)
    .add("executor", executor);

let resp = orch.run("Help me prep for a 5-min team standup.").await?;

use cognis::{MultiAgentOrchestrator, Supervisor};

let orch = MultiAgentOrchestrator::new(Supervisor::new())
    .add("supervisor", supervisor_agent)   // first agent is the router
    .add("researcher", researcher_agent)
    .add("writer", writer_agent);

use std::sync::Arc;

let orch = MultiAgentOrchestrator::new(
    Supervisor::new().with_parser(Arc::new(|reply: &str| {
        // return Some((agent_id, prompt_for_that_agent))
        // or None to keep the supervisor's reply as the final answer.
        None
    }))
);

use cognis::{MultiAgentOrchestrator, ParallelVote};

let orch = MultiAgentOrchestrator::new(ParallelVote)
    .add("a", a)
    .add("b", b)
    .add("c", c);

use cognis::{MultiAgentOrchestrator, RoundRobin};

let orch = MultiAgentOrchestrator::new(RoundRobin::new())
    .add("worker_a", worker_a)
    .add("worker_b", worker_b)
    .add("worker_c", worker_c);

​

How it works

• Each strategy is a struct that implements HandoffStrategy. That trait has one required async method: run(&self, agents, input, bus) -> Result<AgentResponse>. The strategy decides everything that happens between the user’s input and the final response.
• Agents inside the orchestrator are still Agents. Each runs its own loop with its own memory, tools, and middleware. The orchestrator only decides who runs next.
• Errors propagate. If an agent inside the orchestrator returns Err, the orchestrator returns Err. Wrap a sub-agent’s client with with_fallback if you want graceful degradation.
• The orchestrator returns an AgentResponse. Same shape as a single agent — drop-in callers don’t change.
• Other strategies in the box. Beyond the four covered above, cognis::multi_agent also ships Hierarchical (manager → workers tree) and Consensus (quorum-based voting).

​

Custom handoff

use std::sync::Arc;
use async_trait::async_trait;
use tokio::sync::Mutex;
use cognis::multi_agent::{HandoffStrategy, MessageBus};
use cognis::{Agent, AgentResponse, Message, Result};

struct EscalateOnUnsure;

#[async_trait]
impl HandoffStrategy for EscalateOnUnsure {
    async fn run(
        &self,
        agents: &[(String, Arc<Mutex<Agent>>)],
        input: Message,
        bus: Arc<dyn MessageBus>,
    ) -> Result<AgentResponse> {
        // 1. Run a primary agent.
        // 2. If its reply is unsure, route to a senior agent.
        // 3. Return the chosen reply.
        todo!()
    }

    fn name(&self) -> &str { "EscalateOnUnsure" }
}

​

AgentBus and AgentEventBus

• AgentBus — generic typed pub/sub. Any T: Clone + Send + Sync + 'static can be a topic value.
• AgentEventBus — pre-typed for AgentEvents emitted during the loop (request started, tool called, response produced, …).

use cognis::AgentBus;

let bus = AgentBus::new();
let mut sub = bus.subscribe::<MyEvent>("topic.events");
bus.publish("topic.events", MyEvent { /* … */ }).await?;
let ev = sub.recv().await?;

​

See also