# `Nous.AgentRegistry`
[🔗](https://github.com/nyo16/nous/blob/v0.17.1/lib/nous/agent_registry.ex#L1)

Unique-key `Registry` mapping session IDs to running `Nous.AgentServer` processes.

This is one of the two processes Nous starts in its own supervision tree
(see `Nous.Application`): the registry names agents, and
`Nous.AgentDynamicSupervisor` owns their lifecycle. Nothing registers here
directly — `Nous.AgentDynamicSupervisor.start_agent/3` passes
`via_tuple(session_id)` as the child's `:name`, so an `AgentServer` is
registered by `Registry` at start and unregistered automatically when it
exits. Keys are `:unique`, so a session ID can only ever have one live
agent; starting a second one for the same ID returns
`{:error, {:already_started, pid}}`.

The registry is partitioned across `System.schedulers_online/0`, because the
read path is a hot one: a LiveView fan-in resolves the session's agent on
every event, from a different process each time.

## Examples

    config = %{model: "openai:gpt-4o-mini", instructions: "You are helpful."}
    {:ok, _pid} = Nous.AgentDynamicSupervisor.start_agent("session-42", config)

    # Resolve the pid when you need it
    {:ok, pid} = Nous.AgentRegistry.lookup("session-42")
    Nous.AgentServer.send_message(pid, "Hello")

    # ...or let Registry route a GenServer call for you
    GenServer.call(Nous.AgentRegistry.via_tuple("session-42"), :get_history)

    Nous.AgentRegistry.lookup("no-such-session")
    #=> {:error, :not_found}

# `key`

```elixir
@type key() :: String.t() | tuple()
```

A registry key.

Usually a session id string. `Nous.Teams.Coordinator` registers team members
under a `{:team, team_id, member_name}` tuple, so the key is any term the
caller can reproduce — not just a binary.

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

Child spec for the supervision tree; started by `Nous.Application`.

# `lookup`

```elixir
@spec lookup(key()) :: {:ok, pid()} | {:error, :not_found}
```

Look up the running agent process registered under `key`.

# `via_tuple`

```elixir
@spec via_tuple(key()) :: {:via, Registry, {module(), key()}}
```

Build the `:via` tuple that names the agent process for `key`.

Pass it as `:name` when starting an `AgentServer`, or as the server
reference to any `GenServer` call.

---

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