AgentSession

Send a message to an agent

Changed on

Queues a message for the agent running this session. The agent reads it when it next runs — this does not start one, so a message to a session with nothing running waits rather than waking it. Who may send is decided by the session's agent type, not by the caller's say-so, and the sender recorded is the authenticated caller rather than anything the body claims. The session's inbox is created by the first message sent to it, so there is nothing to set up.

post/agentSession/{id}/inbox/messages

Request

  • Base URL: https://api.mabl.com
  • URL: https://api.mabl.com/agentSession/{id}/inbox/messages
  • Auth: one of:
    • HTTP basic
    • API key in header Authorization

Path parameters

idstring required

Request body

messagestring required

What to tell the agent.

idempotency_keystring

Makes a retry safe. Sending the same key to the same session twice returns the message stored the first time and queues nothing new — including when the second call carries different text, because the first one is what the agent will act on.

Response

The queued message. On a repeat of an idempotency key this is the message stored the first time, and nothing new was queued.

message_indexinteger required

Position in this session's inbox, assigned by the server and dense from zero. Ordering is the point: an agent reads what it was told in the order it was told, and the index is what a cursor moves through.

message_idstring required

Server-assigned id for this message.

sender_idstring required

The authenticated caller who sent it, never anything the request body said. Recorded so a message can be attributed after the fact.

sender_type'user' | 'system' | 'agent' required

Who the message is from, which decides how it reaches the model. user is a person, and their text is marked as human authorship. system is mabl speaking — a notification, a trigger — and is deliberately NOT marked that way, so an agent is never fed its own machinery back as "what the user asked for". agent is another agent session speaking, which names itself in sender_agent_session_id. Derived from the authenticated caller, never sent: a caller with nobody behind it cannot claim a person typed something. An agent's credential names its session, and that is the more specific fact about a caller who is also acting for a person — so a credential naming a session is read as agent rather than as the person it acts on behalf of.

sender_agent_session_idstring

The agent session this came from, when an agent is speaking. Read off the caller's verified credential rather than the request body, so it attests the topology rather than asserting it. Absent for any other sender.

messagestring required

What the agent is being told. Bounded because it becomes a permanent turn in a conversation that is re-sent to the model on every turn after it, not merely a request body.

idempotency_keystring

The key this message was stored under, when one was supplied.

created_timeinteger required

Commit time, assigned by the database rather than the caller.

Changes