ClaudeAgentSDK.Agent (claude_agent_sdk v0.5.3)

View Source

Agent definition for custom agent profiles.

An Agent represents a custom persona or role for Claude with specific:

  • Description: Human-readable description of the agent's purpose
  • Prompt: System prompt that defines the agent's behavior
  • Allowed Tools: Optional list of tools the agent can use
  • Model: Optional model specification (e.g., "claude-sonnet-4", "opus")

Agents enable switching between different Claude behaviors at runtime while maintaining conversation context.

Examples

# Define a code review agent
code_agent = Agent.new(
  name: :code_reviewer,
  description: "Expert code reviewer",
  prompt: "You are an expert code reviewer. Analyze code for bugs, performance, and best practices.",
  allowed_tools: ["Read", "Grep"],
  model: "claude-sonnet-4"
)

# Define a documentation agent
doc_agent = Agent.new(
  description: "Documentation specialist",
  prompt: "You excel at writing clear, comprehensive documentation.",
  allowed_tools: ["Read", "Write"]
)

# Use agents in options
options = Options.new(
  agents: %{
    coder: code_agent,
    writer: doc_agent
  },
  agent: :coder  # Start with code agent
)

Python SDK Compatibility

Maps to Python's AgentDefinition:

# Python
AgentDefinition(
    description="Expert code reviewer",
    prompt="You are an expert...",
    tools=["Read", "Grep"],
    model="sonnet"
)

# Elixir equivalent
Agent.new(
    description: "Expert code reviewer",
    prompt: "You are an expert...",
    allowed_tools: ["Read", "Grep"],
    model: "sonnet"
)

Summary

Types

t()

Functions

new(attrs)

Creates a new Agent struct.

to_cli_map(agent)

Converts an Agent to a CLI-compatible map.

validate(agent)

Validates an Agent struct.

Types

t()

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

Functions

new(attrs)

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

Creates a new Agent struct.

Parameters

  • attrs - Keyword list of agent attributes

Required Fields

  • :description - Description of the agent's purpose (string)
  • :prompt - System prompt defining the agent's behavior (string)

Optional Fields

  • :name - Agent identifier (atom)
  • :allowed_tools - List of tool names the agent can use (list of strings)
  • :model - Model to use for this agent (string, e.g., "sonnet", "claude-opus-4")

Returns

A new ClaudeAgentSDK.Agent.t/0 struct.

Examples

# Minimal agent
Agent.new(
  description: "Simple helper",
  prompt: "You are a helpful assistant"
)

# Complete agent
Agent.new(
  name: :researcher,
  description: "Research specialist",
  prompt: "You excel at research and analysis",
  allowed_tools: ["WebSearch", "WebFetch"],
  model: "claude-opus-4"
)

to_cli_map(agent)

@spec to_cli_map(t()) :: map()

Converts an Agent to a CLI-compatible map.

Transforms the Agent struct into a map format expected by the Claude CLI, converting field names to match the CLI's JSON schema:

  • prompt → "prompt"
  • description → "description"
  • allowed_tools → "tools"
  • model → "model"

Omits nil fields from the output map.

Parameters

  • agent - Agent struct to convert

Returns

A map with string keys suitable for JSON encoding and passing to the CLI.

Examples

agent = Agent.new(
  description: "Code reviewer",
  prompt: "You review code",
  allowed_tools: ["Read", "Grep"],
  model: "sonnet"
)

Agent.to_cli_map(agent)
#=> %{
#=>   "description" => "Code reviewer",
#=>   "prompt" => "You review code",
#=>   "tools" => ["Read", "Grep"],
#=>   "model" => "sonnet"
#=> }

validate(agent)

@spec validate(t()) :: :ok | {:error, atom()}

Validates an Agent struct.

Ensures that required fields are present and all fields have valid values.

Validation Rules

  • description must be present and non-empty
  • prompt must be present and non-empty
  • allowed_tools must be a list of strings (if present)
  • model must be a string (if present)

Parameters

  • agent - Agent struct to validate

Returns

  • :ok if validation succeeds
  • {:error, reason} if validation fails

Examples

agent = Agent.new(
  description: "Valid agent",
  prompt: "You are helpful"
)
Agent.validate(agent)
#=> :ok

invalid = Agent.new(
  description: "",
  prompt: "Prompt"
)
Agent.validate(invalid)
#=> {:error, :description_required}