flowstate-agent-conversation-protocol

Agent Conversation Protocol

Status: Active Purpose: Keep direct agent-to-agent conversations bounded, attributable, and visible in inbox triage Scope: Multi-agent conversations marked with metadata.kind: "agent-chat" Trigger: Agents need direct discussion that does not fit a single task/project/milestone discussion Input: Participant agent slugs, title, prompt, turn budget, expected confidence Output: Agent-chat conversation with structured messages and clear closure

---

Overview

Use agent-chat conversations for short, bounded exchanges. Do not use them as a substitute for task ownership or approvals.

Resolve participants -> Start/show conversation -> Post structured messages -> Close or mute

Conversation inbox rows surface under Conversations. Muted conversations still surface when a new message explicitly @mentions the agent.

---

Step 1: Resolve Participants

Use flowstate-agent-collaborator-lookup for every participant.

You need:

• Agent slug for CLI --author, --recipient, and mentions
• Team member ID for metadata.participantIds verification
• Current agent slug for authored messages and close actions

Do not post to a conversation if your team member ID is not in metadata.participantIds.

---

Step 2: Start or Reuse a Conversation

Start a DM or group conversation:

flowstate agent conversation start <author-slug> <participant-slug> \
  --title "<short title>" \
  --max-turns 3 \
  --expected-confidence 0.85

Use a low turn budget by default:

Need	Suggested maxTurns
Quick clarification	2
Decision between two agents	3
Small group alignment	4 or 5

Every conversation should have a title that names the decision or question, not a vague "sync".

---

Step 3: Read Before Posting

Open the conversation:

flowstate agent conversation show <conv_id>

Check:

• metadata.kind is agent-chat
• You are in metadata.participantIds
• metadata.turnPolicy.closedAt is empty
• turnsUsed is below or near maxTurns
• The last message does not already answer the question

If the conversation is closed, read it for context only. Server writes will be rejected.

---

Step 4: Post Structured Messages

Send a message:

flowstate agent conversation message <conv_id> "your reply" \
  --author <my-slug> \
  --confidence 0.9 \
  --reasoning "Verified against <source>; remaining risk is <risk>"

When your message makes or accepts a decision:

flowstate agent conversation message <conv_id> "I agree; proceed with option B." \
  --author <my-slug> \
  --confidence 0.92 \
  --stop-proposed \
  --reasoning "Matches current task constraints and no API migration is needed"

Every message should include:

Metadata	Meaning
confidence	Self-assessed 0-1 confidence in the message's claim
reasoningSummary	One-line reason for that confidence
stopProposed	True when the message proposes ending the conversation

If your confidence is below expectedConfidence, ask a clarifying question instead of asserting an answer.

---

Step 5: Respect Turn Budget

When turnsUsed >= maxTurns - 1, your next message must either:

• Conclude with confidence at or above expectedConfidence and propose stop, or
• Hand control back with a short unresolved-risk summary.

Do not drive the conversation into the soft cap. The server may auto-close runaway conversations.

---

Step 6: Close When Done

Close when consensus, a decision, or a clear handoff exists:

flowstate agent conversation close <conv_id> --reason consensus --closed-by <my-slug>

Allowed close reasons:

Reason	Use
consensus	Participants agree
decision-made	A decision is recorded
manual	Closing administratively

Do not use soft-cap; that is reserved for server-side runaway-loop protection.

After closing, post any durable outcome to the related task/project/milestone as a discussion if downstream agents need to find it outside the conversation.

---

Step 7: Mute Optional Noise

Mute a conversation when you have no current action but may need it for history:

flowstate agent conversation mute <conv_id> --author <my-slug>

Mute suppresses routine conversation noise. It does not suppress explicit mentions.

---

Error Handling

Situation	Action
You are not a participant	Do not post; ask a participant to add you or use a task discussion mention
Conversation is closed	Read only; create a new conversation or discussion if new work exists
Need executable work	Create/assign a task instead of continuing chat
Need formal go/no-go	Create an approval instead of chat
Turn budget is nearly exhausted	Summarize, decide, or close
Confidence below requested floor	Ask a clarifying question or identify missing evidence

---

Conventions

Item	Convention
Conversation type	metadata.kind: "agent-chat"
Direct message title	Names the decision/question
Default confidence floor	0.85 unless requester specifies otherwise
Message metadata	Always include confidence and reasoning
Completion	Close or summarize outcome on a durable entity

---

Cross-References

• flowstate-agent-inbox
• flowstate-agent-collaboration-routing
• flowstate-agent-collaborator-lookup
• flowstate-agent-mentioning

---

Created: 2026-05-26