ClaudeCode.Agent (ClaudeCode v0.20.0)

Struct and builder for custom subagent configurations.

Provides a structured alternative to raw maps when configuring the :agents option for sessions and queries.

Examples

# Build agents with the struct builder
reviewer = ClaudeCode.Agent.new(
  name: "code-reviewer",
  description: "Expert code reviewer",
  prompt: "You review code for quality and best practices.",
  tools: ["View", "Grep", "Glob"],
  model: "sonnet"
)

planner = ClaudeCode.Agent.new(
  name: "architect",
  description: "Software architect",
  prompt: "You design system architectures."
)

{:ok, session} = ClaudeCode.start_link(agents: [reviewer, planner])

# Raw maps still work too
{:ok, session} = ClaudeCode.start_link(agents: %{
  "code-reviewer" => %{"description" => "Expert code reviewer", ...}
})

Summary

Types

t()

Functions

new(opts)

Creates a new Agent struct.

to_agents_map(agents)

Converts a list of Agent structs to the map format expected by the CLI.

Types

t()

@type t() :: %ClaudeCode.Agent{
  description: String.t() | nil,
  model: String.t() | nil,
  name: String.t(),
  prompt: String.t() | nil,
  tools: [String.t()] | nil
}

Functions

new(opts)

@spec new(keyword()) :: t()

Creates a new Agent struct.

Options

:name - (required) Agent name used as the identifier
:description - What the agent does (shown to Claude for dispatch)
:prompt - System prompt for the agent
:model - Model to use (e.g. "sonnet", "haiku", "opus")
:tools - List of tool names the agent can access

Examples

iex> ClaudeCode.Agent.new(name: "reviewer", prompt: "Review code.")
%ClaudeCode.Agent{name: "reviewer", prompt: "Review code.", description: nil, model: nil, tools: nil}

iex> ClaudeCode.Agent.new(name: "planner", description: "Plans work", prompt: "You plan.", model: "haiku", tools: ["View"])
%ClaudeCode.Agent{name: "planner", description: "Plans work", prompt: "You plan.", model: "haiku", tools: ["View"]}

to_agents_map(agents)

@spec to_agents_map([t()]) :: %{
  required(String.t()) => %{required(String.t()) => any()}
}

Converts a list of Agent structs to the map format expected by the CLI.

Returns %{name => %{"description" => ..., "prompt" => ..., ...}}.

Examples

iex> agents = [ClaudeCode.Agent.new(name: "reviewer", prompt: "Review code.", model: "haiku")]
iex> ClaudeCode.Agent.to_agents_map(agents)
%{"reviewer" => %{"prompt" => "Review code.", "model" => "haiku"}}