Issho.Agents (Issho v0.2.0)

Copy Markdown View Source

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.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get(instance, key, room, name, default \\ nil)

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

join(instance, actor, room, opts \\ [])

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(instance, key, room)

Takes the agent out of the room.

participant(instance, key, room)

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

put(instance, key, room, name, value)

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(instance, key)

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

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get(instance, key, room, name, default \\ nil)

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

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

join(instance, actor, room, opts \\ [])

@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(instance, key, room)

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

Takes the agent out of the room.

participant(instance, key, room)

@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(instance, key, room, name, value)

@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(instance, key)

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

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