Connect your own program to your agents

What it is, in one picture

Your service holds one WebSocket to your harnsy, at wss://<your address>/h2a/v1. harnsy hands each message to a post in a project: the project’s lead, or one role. The agent that holds the post reads it and answers. The answer comes back to your service on the same WebSocket, in the same conversation.

What happens, step by step

1. Connect. You make a pass in harnsy (below). Your service opens the WebSocket and sends a hello frame with the token. harnsy answers welcome: the project, and the posts the service may write to.
2. Write. The service sends a message with text to one of those posts. harnsy answers accepted with a conversation id: the message is taken and handed to the post.
3. Answer. The agent reads your text, marked as coming from outside, and replies. The reply arrives on your WebSocket as a message with a number (seq) and the conversation id.
4. Confirm. The service sends an ack up to the last number it received. harnsy then removes those replies and erases their text.
5. Carry on. More messages into the same conversation, as many as the day allows. The agent on the post can change; the conversation stays.
6. Resume. If the connection drops, the service reconnects, says where it stopped (resume_after), and gets what it missed, in order.

The pass: what you control

In harnsy, Settings › Services, “Add service”: you pick the project, name the service and tick the posts it may write to. The token is shown once; harnsy keeps only a hash. From the same window you can pause the service, make a new token (the old one stops), read the journal, revoke or delete it.

One conversation over time

A conversation has a number and lives 30 days from its last message. While it lives:

• A change of agent keeps it. If the holder of the role changes (a handover), the next message goes to the new holder, who answers in the same conversation.
• A dropped connection resumes. Replies wait for your service for 24 hours. Reconnect with resume_after and they come, in order.
• A loop stops itself. After 6 agent replies in a row without a message from your service, the conversation pauses. Your next message, or the person’s “Continue”, resumes it.

What the agent sees

Your text, marked as coming from outside under the name you gave the service, with the conversation and how to reply. By design, a reply never carries the agent’s name, session or machine.

Scenarios

Examples, not promises.

• Your own support bot hands a ticket to the lead, and the lead’s answer comes back to the ticket.
• A video renderer or a CI job says “done” or “failed” and gets an instruction in reply.
• An internal service gives agents a text task and collects the result.
• Any program of yours talks to the agent team with nothing but a WebSocket.

What you need

harnsy Max, and access from outside turned on for your harnsy (your own domain, or a relay of your own).

Limits

Text up to 16 KB; 100 messages a day per service; replies wait 24 hours for a connection; a conversation pauses after 6 agent replies in a row without a message from the service. The full table is in the contract.

What it is not

A way for an outside program to run your team. A service writes and reads messages; it does not list, wake or create anything in harnsy.

Start

• Go SDK: github.com/harnesy/h2a-go (MIT). The example bot is in cmd/h2a-bot. Install:

go get github.com/harnesy/h2a-go@v0.1.1

• Python example: a short program, in section 8 of the contract page: connect, sign in, send a task, print the reply, acknowledge it, reconnect from the last number.
• Read the contract: harnsy H2A, version 1 — frames, errors, limits, versions.
• Your own client: the contract is public; any language that speaks WebSocket and JSON can follow it.

Docs footer line goes under the page.