ClaudeCode.Agent (ClaudeCode v0.29.0)

View Source

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: ["Read", "Grep", "Glob"],
  disallowed_tools: ["Write", "Edit"],
  model: "sonnet",
  permission_mode: :plan
)

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

{: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

isolation_mode()
memory_scope()
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

isolation_mode()

@type isolation_mode() :: :worktree

memory_scope()

@type memory_scope() :: :user | :project | :local

t()

@type t() :: %ClaudeCode.Agent{
  background: boolean() | nil,
  description: String.t() | nil,
  disallowed_tools: [String.t()] | nil,
  hooks: map() | nil,
  isolation: isolation_mode() | nil,
  max_turns: pos_integer() | nil,
  mcp_servers: map() | nil,
  memory: memory_scope() | nil,
  model: String.t() | nil,
  name: String.t(),
  permission_mode: ClaudeCode.Types.permission_mode() | nil,
  prompt: String.t() | nil,
  skills: [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", "inherit")
  • :tools - List of tool names the agent can access
  • :disallowed_tools - Tools to deny, removed from inherited or specified list
  • :permission_mode - Permission mode (:default, :accept_edits, :dont_ask, :bypass_permissions, :delegate, :plan)
  • :max_turns - Maximum number of agentic turns before the agent stops
  • :skills - Skills to load into the agent's context at startup
  • :mcp_servers - MCP servers available to this agent (map of server configs)
  • :hooks - Lifecycle hooks scoped to this agent (map of hook configs)
  • :memory - Persistent memory scope (:user, :project, or :local)
  • :background - Set to true to always run as a background task
  • :isolation - Set to :worktree to run in a temporary git worktree

Examples

iex> ClaudeCode.Agent.new(name: "reviewer", prompt: "Review code.")
%ClaudeCode.Agent{name: "reviewer", prompt: "Review code.", description: nil, model: nil, tools: nil, disallowed_tools: nil, permission_mode: nil, max_turns: nil, skills: nil, mcp_servers: nil, hooks: nil, memory: nil, background: nil, isolation: 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"], disallowed_tools: nil, permission_mode: nil, max_turns: nil, skills: nil, mcp_servers: nil, hooks: nil, memory: nil, background: nil, isolation: nil}

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"}}