send_mail

Send one piece of mail to another agent, addressed by its id or by its name.

Agentwritesnot idempotentMCP tool

An id is taken as it stands, so an id no agent holds is not_found rather than being tried as a name. A name is looked for among the live agents of your own workflow first, then of every workflow, where one that more than one workflow holds is refused as invalid_argument listing each holder with its id and workflow, so address that one by id. Nothing is delivered to a pane: the mail waits in the panel until the recipient reads its mail, so the recipient will not see it while it is busy and may not see it for a while. The response carries a warning when the recipient is dormant, since nothing runs behind it and the mail waits until it is resumed. Use this to ask an agent working alongside you something only it knows, or to hand it a result it is waiting on, and say who you are and what you need in the mail itself. Set replyTo to the id of the mail you are answering so the two read as a thread. There is a limit on how much mail you and one other agent may exchange, counted in both directions over every thread, so opening a new subject is not a way around it and a send past the limit is refused for good. Wind an exchange up with a clear answer or a decision rather than another round once it feels like it is dragging, since the limit is there to be nowhere near rather than to be spent. Each call sends another piece of mail, so do not retry a call that may have succeeded, and do not send to yourself, which is refused. Returns not_found when no agent answers to the address, failed_precondition when the recipient is archived, and resource_exhausted when the recipient is already holding a full mailbox of unread mail or when you and the recipient have hit the limit on what one pair may exchange. A child agent may only mail its parent and its parent's other children; anything else is refused as permission_denied, so reply to your parent rather than looking for another way around.

Calling it#

curl -X POST http://127.0.0.1:8787/agent.v1.AgentService/SendMail \
  -H 'Content-Type: application/json' \
  -d '{
  "to": "<to>",
  "body": "<body>"
}'

komrad rpc send-mail \
  --to <string> \
  --body <string>

{
  "name": "send_mail",
  "arguments": {
    "to": "<to>",
    "body": "<body>"
  }
}

Offered by the komrad MCP server to implementer, reviewer, orchestrator agents.

Request#

SendMailRequest#

Field Type Description

Field	Type	Description
`to`	string	Who to send to: an agent's id, or the name of a live agent. required
`body`	string	What to say, which has to carry who is asking and what is wanted. required, at most 10000 characters
`replyTo`	string	The mail being answered, so the exchange reads as a thread.

to

string

Who to send to: an agent's id, or the name of a live agent.

required

body

string

What to say, which has to carry who is asking and what is wanted.

required, at most 10000 characters

replyTo

string

The mail being answered, so the exchange reads as a thread.

Response#

SendMailResponse#

Field	Type	Description
`mail`	Mail	The mail as recorded, whose id an answer can reply to.
`warning`	string	Why the recipient will not read this soon, set when nothing runs behind it.

Types#

Mail#

Field	Type	Description
`id`	string	Set this as reply_to on an answer so the two read as a thread.
`fromAgentId`	string	Which agent sent it, unset when komrad sent it itself.
`fromName`	string	What to show as the sender, which is komrad's own name for a notice it raised.
`toAgentId`	string	The agent it is waiting for.
`body`	string	What the sender wrote.
`replyTo`	string	The mail this one answers, unset when it opens a subject.
`createdAt`	string	When it was sent, in RFC 3339.
`claimedAt`	string	When the recipient took it, unset while it is still waiting.
`expiresAt`	string	When it stops being offered, whether or not it was ever taken.
`kind`	MailKind	Whether an agent wrote it or komrad raised it.

MailKind#

MailKind tells an agent's own mail from a notice komrad raised itself.

Value	Description
`MAIL_KIND_PLAIN`	One agent writing to another, or the person writing to an agent.
`MAIL_KIND_REVIEW_ACTIVITY`	Komrad saying a review has moved, naming the file the comments were written to.
`MAIL_KIND_EXCHANGE_CAPPED`	Komrad telling an agent that it and one other have spent their mail limit.