# `Issho.Agents`
[🔗](https://github.com/hattoriai/issho/blob/v0.2.0/lib/issho/agents.ex#L1)

Agents in rooms for front ends without a lasting connection: an MCP
server, whose every tool call is its own request, a webhook, a chat
bot. An agent joins a room on its first call and stays, present and
where it last pointed, between calls; it leaves after `:idle`
milliseconds with no call (ten minutes), or when told.

    {:ok, claude} = Issho.Agents.join(MyApp.Issho, agent, "board:42", on_behalf_of: ada)
    {:ok, _snapshot} = Issho.Participant.open(claude, "board:42")
    Issho.Participant.place(claude, %{"doc" => "board:42", "at" => %{"node" => "n7"}})

`join/4` gives the agent's `Issho.Participant`, the same one each time
for the same actor and room, and starts the idle time again. People
see the agent as they see anyone: its name, its place, its changes.

The agents of a node are found on that node; an MCP endpoint behind a
load balancer needs session affinity, or one node for its agents.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `get`

```elixir
@spec get(atom(), String.t(), String.t(), term(), term()) :: term()
```

A value the agent kept in the room, or `default`.

# `join`

```elixir
@spec join(atom(), Issho.Actor.t(), String.t(), keyword()) ::
  {:ok, pid()} | {:error, term()}
```

The agent's participant in the room, joining it on the first call.
Options: those of `Issho.join_as/4` (`:can`, `:on_behalf_of`,
`:claims`) and `:idle`.

# `leave`

```elixir
@spec leave(atom(), String.t(), String.t()) :: :ok
```

Takes the agent out of the room.

# `participant`

```elixir
@spec participant(atom(), String.t(), String.t()) :: pid() | nil
```

The participant of the agent with this key in the room, if it is there.

# `put`

```elixir
@spec put(atom(), String.t(), String.t(), term(), term()) ::
  :ok | {:error, :not_there}
```

Keeps a value for the agent in the room, for its later calls (what it
copied, what it was asked to remember), until it leaves.

# `rooms`

```elixir
@spec rooms(atom(), String.t()) :: [String.t()]
```

The rooms the agent with this key is in, on this node.

---

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