# `LlmCore.Agent`
[🔗](https://github.com/fosferon/llm_core/blob/v0.3.0/lib/llm_core/agent.ex#L1)

Agent struct representing a registered LLM provider with a human-friendly name.

Each agent encapsulates:

  * A name/alias for routing lookups
  * The underlying provider module or CLI config
  * Default configuration (model, temperature, etc.)

Agents are registered by the config loader from TOML `[providers.*]` blocks.
They are keyed by the provider's aliases, not by `agent.name`.

## Accessing Agents

    # By alias (from TOML or runtime)
    {:ok, agent} = LlmCore.Agent.Registry.get("claude")

    # Get the dispatchable provider
    provider = LlmCore.Agent.dispatch_provider(agent)

# `t`

```elixir
@type t() :: %LlmCore.Agent{
  config: map(),
  name: String.t(),
  provider: module() | struct(),
  provider_struct: term(),
  registered_at: DateTime.t()
}
```

# `dispatch_provider`

```elixir
@spec dispatch_provider(t()) :: module() | struct()
```

Returns the dispatchable provider value.

For struct-based providers (CLIProvider, Appliance), returns the struct.
For module-based providers, returns the module atom.

# `new`

```elixir
@spec new(String.t(), module(), map()) :: {:ok, t()} | {:error, :invalid_name}
```

Creates a new Agent struct with validation.

## Parameters

  * `name` - Human-friendly alias (lowercase alphanumeric with dashes/underscores)
  * `provider` - Module implementing `LlmCore.LLM.Provider` behaviour
  * `config` - Provider-specific configuration map (default: %{})

## Returns

  * `{:ok, Agent.t()}` - Valid agent
  * `{:error, :invalid_name}` - Invalid name format

## Examples

    iex> Agent.new("steve", LlmCore.LLM.CLIProvider, %{model: "claude-3-opus"})
    {:ok, %Agent{name: "steve", provider: LlmCore.LLM.CLIProvider, ...}}

    iex> Agent.new("INVALID", LlmCore.LLM.CLIProvider, %{})
    {:error, :invalid_name}

# `valid_name?`

```elixir
@spec valid_name?(String.t()) :: boolean()
```

Validates an agent name format.

Valid names must:
- Start with lowercase letter or number
- Contain only lowercase letters, numbers, dashes, and underscores
- Not be empty

## Examples

    iex> Agent.valid_name?("steve")
    true

    iex> Agent.valid_name?("claude-code")
    true

    iex> Agent.valid_name?("UPPERCASE")
    false

    iex> Agent.valid_name?("")
    false

---

*Consult [api-reference.md](api-reference.md) for complete listing*