Skip to main content
Version: 2.7.0

Write a good message

This page explains how to write a message to the agent. Read it if you have never worked with an agent before. You need no special syntax for a normal question.

What does the agent need from you?​

Write to the agent as you would write to a capable new colleague. The colleague knows the technology well. The colleague does not know your systems, your incident, or your goal.

So give the agent the same context you would give that colleague. Name the symptom, the resource, and the time window.

How does a vague message differ from a specific one?​

A vague message:

The checkout service is broken.

A specific message:

The checkout service returns 500 errors since 09:00 today. Check the pods in the production cluster. List the three most likely causes.

Both messages are short. The second one names the symptom, the resource, the time window, and the form of the answer.

Say what, where, and when​

Give the agent three facts in every message:

  • The symptom. Describe what you see, not what you suspect.
  • The resource. Name the service, the cluster, or the namespace.
  • The time window. Write "in the last hour" or "between 09:00 and 10:00 today".

A message without a time window leaves the choice to the agent. The chosen window is often wider or narrower than your incident.

Keep one goal in one message​

Ask for one thing at a time. Send the next question after you read the reply.

The agent keeps the history of the session. You do not have to repeat the context in every message.

In a long session, repeat a value the agent must have exactly. See What the agent remembers.

Paste the error text​

Do not describe an error. Paste it.

Write this:

This request fails with: dial tcp 10.0.4.19:8080: i/o timeout. Find the cause.

Not this:

There is some timeout error somewhere in the network.

The same rule applies to a log line, a command output, or a configuration snippet. An exact string is something the agent can search for. A description is not.

Ask for the form of the answer​

State how you want to read the answer. The agent uses that form in its reply.

Useful forms:

  • "Answer in three bullet points."
  • "Give me the command to run, and nothing else."
  • "Write a short summary for a non-technical reader."
  • "Rank the causes by likelihood."

A stated form saves you the work of pulling the answer out of a long text.

What comes next?​

You often need more than one message. See Get better answers for how to steer the agent after its first reply.