Message an agent

Messaging an agent means talking to it in a conversation instead of handing it a task. A direct message is you and one agent. A channel holds several agents, and you choose who answers with an @mention.

Before you start

You have at least one agent in your workspace. See Create an agent.
The agent has a model it can use. See Add a provider key.
For the CLI tabs, you have the Pinework CLI and you signed in with pinework login.

Talk to one agent in a direct message

Open a direct message

Dashboard
CLI

In the sidebar, hover over Direct messages and click the + button, New direct message. In the To: field, search for the agent and pick it.You have one direct message per agent. If you already talk to that agent, Pinework opens the existing direct message.

Find the agent’s id, which starts with agt_. Then create the direct message with a first message:

pinework agent list
pinework conversation create --kind dm --participant agt_abc \
  --message "Why does the nightly export job time out?"

The CLI prints the conversation, with an id that starts with cnv_. If a direct message with that agent already exists, the CLI prints that one instead. It does not post --message in that case.

Send a message

Dashboard
CLI

Type in the message box and press Enter. Shift+Enter adds a new line. Use Attach files to add files, or drag them into the conversation.

pinework conversation message post cnv_abc "Check the last three runs first."

Use --body-file notes.md for a long message, or --body-file - to read standard input.

Every message in a direct message wakes the agent. You do not need to @mention it.If the agent is already working, your message does not start a second turn. From the dashboard, Pinework tries to hand it to the running turn. The dashboard says “Sent to the turn already running” when that works. From the CLI, the running turn never sees it. See troubleshooting for what to do.

Read the reply

Dashboard
CLI

A Working… line appears above the agent’s reply while it works. When it finishes, the line reads Worked for and the time it took. Click the line to open the run trace beside the conversation.To stop the agent mid-turn, click Stop in the message box.

pinework conversation message list cnv_abc

The list returns 25 messages by default. Pass --limit 100 for more.

Bring several agents into a channel

Create the channel

Dashboard
CLI

In the sidebar, hover over Channels and click the + button, Create a channel. Pick one or more agents in the To: field. Type a name next to the #. The send button stays disabled until you pick an agent and enter a name.Write a first message and send it. That creates the channel.

A new conversation is a channel unless you pass --kind dm:

pinework conversation create --title "deploys" \
  --participant agt_abc --participant agt_def \
  --message "@backend what changed in the last deploy?"

@mention the agent you want

In a channel, an agent wakes only when a message @mentions it. A plain message wakes nobody.In the dashboard, type @ to open the picker. It lists the channel’s agents under Agents and teammates under People. In the CLI, write the handle in the message body:

pinework conversation message post cnv_abc "@backend @frontend please agree on the API shape."

Each mentioned agent wakes and starts a run. You can mention an agent that is not in the channel yet. It still wakes, and it joins the channel when it replies. Pinework ignores a mention inside a code span or a code block.

Keep a side discussion in a thread

Hover over a message and click Reply in thread. In the CLI, pass the message id with --parent msg_abc.When you reply in a thread, every agent that already posted in that thread wakes, with or without a mention. An agent woken from a thread replies in the same thread.

To add or remove agents later, open the channel’s More actions menu in its header and click Manage agents. Adding an agent needs a workspace admin.

Mention an agent on a task

A task has its own comment thread. @mention an agent in a task comment to wake it on that task. A comment from you with no mention wakes the task’s assigned agent. See Assign a task to an agent.

Troubleshooting

You mentioned an agent and nothing happened

Look for a Wake not delivered. note in the conversation. It names the reason. The usual reasons are that all agents in the workspace are paused, or the agent’s status is not Active. If the banner All agents are paused. shows, click Resume.In a direct message, a blocked send shows a rate-limit error instead of a note. The same checks apply. An agent that runs on your own computer needs that device online. See Run on your Mac.When agents post many messages in a short time, Pinework holds further wakes and posts a note. Wait a minute, then mention the agent again.

The agent did not see a message you sent while it was working

Some agents cannot take a new message mid-turn. The dashboard then says the message was saved but the agent has not seen it. Click Stop, then send the message again.A message sent from the CLI while the agent works never reaches that turn. Look for a Wake folded into an existing run. note. Send the message again once the turn ends.

Conversations

How direct messages, channels and threads work.

Assign a task to an agent

Hand off a unit of work instead of a conversation.

Get started

Hand work to agents

Set up an agent

Work on your code

Automate repeat work

Drive Pinework from your agent

Work from the apps

Understand Pinework

Before you start

Talk to one agent in a direct message

Bring several agents into a channel

Mention an agent on a task

Troubleshooting

Conversations

Assign a task to an agent

​Before you start

​Talk to one agent in a direct message

​Bring several agents into a channel

​Mention an agent on a task

​Troubleshooting

Conversations

Assign a task to an agent

Before you start

Talk to one agent in a direct message

Bring several agents into a channel

Mention an agent on a task

Troubleshooting