Crews — AgentSea for Elixir

agentsea_crews models a crew as a DynamicSupervisorof agents with a gen_statem coordinator. See the API on HexDocs.

Roles & capabilities

Crew agents carry a role with capabilities. The delegation strategy uses them to pick who handles each task:

elixir

alias AgentSea.{Agent, Role, Capability}

coder = %Agent.Config{
  name: :coder,
  model: "claude-opus-4-8",
  provider: {AgentSea.Providers.Anthropic, []},
  role: %Role{name: "coder", capabilities: [%Capability{name: "coding", proficiency: :expert}]}
}

writer = %Agent.Config{
  name: :writer,
  model: "claude-haiku-4-5",
  provider: {AgentSea.Providers.Anthropic, []},
  role: %Role{name: "writer", capabilities: [%Capability{name: "writing", proficiency: :expert}]}
}

Building & running a crew

Define a Crew.Spec, start it (under your supervision tree in real apps), add tasks, then kickoff/1. Tasks with satisfied dependencies run concurrently; the call returns when everything settles.

elixir

spec = %AgentSea.Crew.Spec{
  name: :build_crew,
  agents: [coder, writer],
  strategy: AgentSea.Crew.Delegation.BestMatch
}

{:ok, _pid} = start_supervised({AgentSea.Crew, spec})

{:ok, impl} =
  AgentSea.Crew.add_task(:build_crew,
    description: "implement the feature",
    required_capabilities: ["coding"]
  )

{:ok, _docs} =
  AgentSea.Crew.add_task(:build_crew,
    description: "document the feature",
    required_capabilities: ["writing"],
    depends_on: [impl.id]            # runs only after the coding task succeeds
  )

{:ok, result} = AgentSea.Crew.kickoff(:build_crew)

result.success          # true if no task failed
result.results          # %{task_id => response}
result.failures         # %{task_id => reason}

Delegation strategies

How a task is assigned to an agent:

AgentSea.Crew.Delegation.BestMatch — the most capable agent for the task's required capabilities.
AgentSea.Crew.Delegation.RoundRobin — even distribution.
AgentSea.Crew.Delegation.Auction — a timed GenServerfan-out where agents bid (role match × model price tier); highest bid wins.

Lifecycle controls

The coordinator is a state machine: :idle → :running → :completed, with :paused and :aborted branches.

elixir

AgentSea.Crew.pause(:build_crew)    # stop dispatching new tasks; in-flight finish
AgentSea.Crew.resume(:build_crew)   # continue from where it left off
AgentSea.Crew.abort(:build_crew)    # cancel in-flight tasks; kickoff caller gets {:error, :aborted}
AgentSea.Crew.status(:build_crew)   # :idle | :running | :paused | :completed | :aborted

Observability

Every kickoff, task, and delegation emits :telemetry events ([:agentsea, :crew, :kickoff | :task, …]). Attach your own handler, or run agentsea_web for a live Phoenix LiveView dashboard of the whole fleet. See the gateway page for routing and the OpenAI-compatible endpoint.