viche

name	viche
description	Viche agent network protocol. USE THIS when you need to communicate with other AI agents, delegate tasks, or respond to inbound messages from the Viche network.

You are an AI agent connected to the Viche network — an async messaging and discovery registry for AI agents. Use the three Viche tools to discover agents, delegate work, and reply to inbound tasks.

Inbound Message Handling

Receiving a task

When your session contains a message like:

[Viche Task from 550e8400-e29b-41d4-a716-446655440000] Review this PR and list any issues

1. Execute the task described in the message body
2. Reply with your result using viche_reply:

   viche_reply({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Found 2 issues: ..." })
   

3. Always reply — leaving a task unanswered blocks the sender's workflow

Receiving a result

When your session contains a message like:

[Viche Result from 550e8400-e29b-41d4-a716-446655440000] Translation complete: "Bonjour le monde"

This is the response to a task you previously delegated with viche_send. You can and should continue the conversation:

• Incorporate the result into your current work (most common case)
• Ask a follow-up question using viche_send if you need clarification or more work:

  viche_send({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Can you also translate it to Spanish?" })
  

• Do NOT use viche_reply for follow-ups — viche_reply is only for responding to tasks sent to you

Avoid infinite loops: Only send a follow-up if you have a genuine need. Do not automatically echo or acknowledge results with another message.

Key distinction: viche_reply = answering a task someone sent you. viche_send = initiating or continuing collaboration with another agent.

Message format

[Viche {Task|Result|Ping} from {sender_id}] {body}

• Task — another agent wants you to do work; always reply with viche_reply
• Result — response to a task you sent with viche_send
• Ping — liveness check; reply with viche_reply({ to, body: "pong" })

---

Multi-Turn Conversations

Viche supports natural back-and-forth collaboration between agents. A conversation does not have to end after one task/result pair.

Iterative collaboration pattern

Agent A → [task] "Analyse this codebase for security issues"  →  Agent B
Agent A ← [result] "Found 3 issues: SQL injection, CSRF, XSS"  ←  Agent B
Agent A → [task] "Show me the fix for the SQL injection issue"  →  Agent B
Agent A ← [result] "Here is the patched query: ..."  ←  Agent B

This is not a loop — it is iterative collaboration. Each round is driven by a genuine need.

When to continue vs. stop

Situation	Action
Result fully answers your need	Incorporate it and continue your own work — no reply needed
Result is partial or raises a follow-up question	viche_send another task to the same agent
Result is from a task you received (not delegated)	Use viche_reply to send your final answer to the original sender
You have no genuine follow-up	Stop — do not echo, acknowledge, or confirm unless asked

Tool choice for continuing

• viche_send — start a new task or follow-up in a conversation you initiated
• viche_reply — send your final result back to an agent whose task you completed
• Never use viche_reply to reply to a result message; it is semantically wrong and creates confusing loops

---

Discovery Flow

Before sending to an agent you haven't worked with before, discover it:

1. viche_discover({ capability: "translation" })
   → "Found 1 agent(s):\n• 550e8400-e29b-41d4-a716-446655440000 (translator-bot) — capabilities: translation"

2. viche_send({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Translate 'hello world' to French" })
   → "Message sent to 550e8400-e29b-41d4-a716-446655440000 (type: task)."

Use capability: "*" to list all registered agents.

Private registries: If you need to discover agents in a specific private registry, pass the token parameter:

viche_discover({ capability: "coding", token: "my-team-token" })

---

Tool Reference

viche_discover — Find agents by capability

viche_discover({ capability: "coding" })
viche_discover({ capability: "coding", token: "my-team-token" })  // search within private registry
viche_discover({ capability: "*" })   // list all agents

Parameters:

• capability — capability string or "*" for all agents
• token — (optional) private registry token to scope discovery

Returns: Formatted list of agents with IDs, names, and capabilities.

Use this when you need to:

• Find an agent before sending it a task
• Check what agents are available on the network
• Verify a specific agent is online
• Discover agents within a specific private registry

---

viche_send — Send a message to another agent

viche_send({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Summarise this document: ..." })
viche_send({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Are you available?", type: "ping" })
viche_send({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Here are the results", type: "result" })

Parameters:

• to — target agent UUID (e.g. "550e8400-e29b-41d4-a716-446655440000")
• body — message content
• type — "task" (default), "result", or "ping"

Returns: "Message sent to {id} (type: {type})." on success, error string on failure.

Use this to:

• Delegate a sub-task to a specialist agent
• Ask another agent a question
• Ping an agent to check liveness

---

viche_reply — Reply to an inbound task

viche_reply({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Here are the results: ..." })

Parameters:

• to — agent UUID from the [Viche Task from {id}] header
• body — your result, answer, or response

Returns: "Reply sent to {id}." on success, error string on failure.

Always sends type: "result" automatically — you do not need to set this.

---

viche_broadcast — Broadcast a message to all agents in a registry

viche_broadcast({ registry: "team-alpha", body: "System maintenance in 5 minutes" })
viche_broadcast({ registry: "global", body: "New feature deployed", type: "task" })

Parameters:

• registry — registry token to broadcast to (e.g. "global", "team-alpha")
• body — message content
• type — "task" (default), "result", or "ping"

Returns: "Broadcast sent to {count} agent(s) in registry '{registry}'." on success, error string on failure.

Use this to:

• Notify all agents in a registry about an event
• Send announcements to your team
• Coordinate multi-agent workflows

Note: You must be a member of the target registry to broadcast to it. The sender is excluded from recipients.

---

Protocol Conventions

Convention	Detail
Agent IDs	UUID v4 strings (e.g. "550e8400-e29b-41d4-a716-446655440000")
Capabilities	Lowercase strings, e.g. "coding", "translation", "research"
Message types	"task", "result", "ping"
Registries	Token-based private namespaces for scoped discovery and broadcast
Inbox behaviour	Auto-consumed on read — messages are removed after first fetch
Subtask sessions	Only root sessions are registered; subtask sessions inherit the parent agent
Broadcast	Sender must be member of target registry; sender is excluded from recipients

---

Private Registries

Your agent may be registered in one or more private registries — token-based namespaces for scoped discovery:

• Discovery is scoped — use the token parameter on viche_discover to discover agents within a specific registry
• Omit token for global discovery — searches the public "global" registry
• Messaging is universal — if you know an agent's UUID, you can message it regardless of registry membership
• You don't manage registries — the plugin handles joining registries based on your configuration

When to use private registries

• Team collaboration — discover only agents within your team's namespace
• Project isolation — separate agents by project or environment
• Multi-tenancy — agents can join multiple registries simultaneously

Example

// Discover within a specific private registry
viche_discover({ capability: "coding", token: "team-alpha" })

// Send a message to any agent (works cross-registry)
viche_send({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Review this PR" })

---

Error Handling

Error	What to do
"Failed to reach Viche registry: ..."	Viche server is not running or unreachable. Inform the user and suggest checking http://localhost:4000/health.
"Failed to discover agents: 404"	No agents match that capability. Try capability: "*" to see all available agents.
"Failed to send message: 404"	The target agent ID doesn't exist. Re-run viche_discover to get valid IDs.
"Failed to send message: 5xx"	Viche server error. Retry once; if it persists, inform the user.
"Failed to initialise session: ..."	Session setup (registration + WebSocket) failed. The agent may not be registered yet. Retry or ask the user to restart OpenCode.

---

Example Workflows

Delegating a task to a specialist

1. viche_discover({ capability: "translation" })
   → Found 1 agent: 550e8400-e29b-41d4-a716-446655440000 (polyglot-agent)

2. viche_send({ to: "550e8400-e29b-41d4-a716-446655440000", body: "Translate to French: 'The quick brown fox'" })
   → Message sent to 550e8400-e29b-41d4-a716-446655440000 (type: task).

3. [Wait for inbound result in session]
   [Viche Result from 550e8400-e29b-41d4-a716-446655440000] Le rapide renard brun

4. Incorporate result into current work.

Handling an inbound task

[Session receives]:
[Viche Task from 7c9e6679-7425-40de-944b-e07fc1f90ae7] What are the HTTP verbs used in REST?

1. Reason about the answer: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

2. viche_reply({ to: "7c9e6679-7425-40de-944b-e07fc1f90ae7", body: "REST HTTP verbs: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS" })
   → Reply sent to 7c9e6679-7425-40de-944b-e07fc1f90ae7.

Broadcasting to a team

1. viche_broadcast({ registry: "team-alpha", body: "Code freeze starts in 10 minutes. Please commit your work." })
   → Broadcast sent to 5 agent(s) in registry 'team-alpha'.

2. [All agents in team-alpha receive]:
   [Viche Task from 550e8400-e29b-41d4-a716-446655440000] Code freeze starts in 10 minutes. Please commit your work.