When your custom agent works your inbox, what decides what it reads and when it stops?

Back to all essays→

My view is that an inbox agent is useful only when it is predictable. It should read one mailbox you can name, stop when it has none, say plainly when it found nothing, and never keep what it should not. Here is what decides each of those today for a custom agent that has Gmail or Outlook connected.

Each turn finds its mailbox before the agent does anything. If you chose a mailbox for this conversation, the turn uses that one, and the choice is final: the turn does not fall back to another account. Otherwise the turn uses the mailbox you connected for that agent. If you have no connection there, it does not fall back to another mailbox. A turn with no identified person asking has no mailbox at all.

When no mailbox resolves, or the lookup itself fails, the agent does not guess. Its turn starts with this notice in its instructions: "No mailbox is connected. Connect or reconnect your mailbox before asking me to use email tools." The same sentence answers any mailbox tool call the agent makes without a mailbox. A missing connection and a failed lookup produce the same sentence. That asks more of you than it should: the notice does not say which of the two happened, so the only step it offers is to connect or reconnect and ask again.

Exact subjects are matched on Outlook. When your request contains the word "subject", the agent takes the nearest quoted text after that word, in backticks, straight or curly double quotes, or single quotes. If nothing is quoted after the word, it uses the first quoted text in the request. With no quotes at all, it takes the words after a clear cue such as "subject:", "subject is" or "with the subject", up to the end of the sentence.

For example, ask for the email with subject 'Today's meeting' (a made-up subject). The apostrophe inside the single quotes stays part of the subject, so the agent looks for Today's meeting without the quote marks. Before that fix, the quote marks became part of the subject, and the agent could report no match even when the message existed.

A subject counts as found only when a message the agent read in that turn has exactly that subject. Otherwise the answer starts with a fixed line: "No message with that exact subject was found in the messages read." The line covers the messages the agent read, not your whole mailbox.

On Gmail this check does not run, so a Gmail answer gets no fixed no-match line. Bounding the Gmail exact-subject read is open work, and it is not built yet.

Your custom agent can also ask Ground Control to run platform operations for you. When Ground Control refuses one, the tool result is one small object, not a bare refusal. It has at most six keys: code, message, field, reason, required_action and upstream_status. Empty keys are left out, and every value is one the refusing service sent. In one test, the agent sends an operation without a required correlation_id and gets a 400. This is the tool result the agent receives in that test:

{
  "code": "malformed_request",
  "message": "required field correlation_id is missing",
  "field": "correlation_id",
  "reason": "required_field_missing",
  "required_action": "send a non-empty value for correlation_id",
  "upstream_status": "400"
}

The field and reason are the ones the refusing service named, never a placeholder. A malformed request reaches the agent as invalid arguments, and a permission refusal reaches it as denied. Other parts of a refusal, such as a correlation ID, response headers, a secret or a token, do not reach the tool result. My view is that the agent should fix a named field and try once more, and pass you, word for word, any required action that needs a person. One gap remains: an error that is not a refusal from the service still reads only "platform operation refused", so neither the agent nor you learns why.

Some platform operations return a credential that is shown only once, for example the secret of a new machine credential. Before such a result reaches the agent, Ground Control replaces the value of four fields, secret, enrollment_token, handoff_token and csrf_token, wherever they appear in the result. In their place is a fixed marker that tells you to view or rotate the credential in its own screen. Every other field, such as the new credential's ID, stays. The agent never sees the value, and the conversation state that Ground Control stores never holds it.

This also asks more of you: your agent cannot hand you a new secret. You open that credential's own screen to view or rotate it. A person or program that calls the API directly still receives the credential in the response.

What to do with your inbox agent

• If your agent answers with the no-mailbox sentence, connect or reconnect the mailbox for that agent, then ask again.
• With more than one mailbox, choose one for the conversation.
• Put an exact subject in quotes right after the word "subject". Read a no-match answer as "not in the messages read", not "not in my mailbox".
• When a refusal names a field and a required action, let the agent fix the field. When the action needs a person, do it yourself.
• Look for a new secret or token in its own screen, not in the conversation.

The agent guide explains the work and permission model. The quickstart covers connection and first steps. Read both before you give your agent a mailbox.