Build agents

Chat agents are Eve projects. RobotRock proxies browser traffic to your deployment, verifies the signed-in user, and renders HITL UI for tool approvals and ask_question prompts.

Scaffold and docs

npx eve init my-agent
cd my-agent

Eve ships full documentation in node_modules/eve/docs/ — read README.md there before authoring tools, skills, or hooks.

Install the RobotRock skill for SDK patterns:

npx skills add robotrock-io/robotrock-skills --skill robotrock

Advertise RobotRock readiness

On connect, RobotRock calls GET /eve/v1/info on your deployment. A deployment is RobotRock-ready when the manifest includes the robotrock-ready hook slug.

Example hook marker:

// agent/hooks/robotrock-ready.ts
export { robotrockReadyHook as default } from "robotrock/eve/agent";

For dashboard chat, auth, audit, and tools, use the SDK — see Build agents and robotrock/eve/agent + robotrock/eve/tools.

User context from the dashboard

When a user chats in the inbox, RobotRock proxies requests to /{tenant}/api/eve/{connectionId}/… and attaches a user-context payload so your agent knows tenantSlug, userId, connectionId, and related fields.

Use this context when scoping tools (for example checking group membership before a refund).

ask_question (mandatory for choices)

RobotRock renders action buttons only when the agent calls Eve's ask_question tool. Do not ask users to pick from numbered lists in prose.

{
  "prompt": "Which integration path should we use?",
  "options": [
    { "id": "polling", "label": "Polling" },
    { "id": "webhooks", "label": "Webhooks" }
  ]
}

• Up to six options → one button each
• More than six → radio form in the action panel
• Use allowFreeform: true when the user may type outside listed options
• After calling ask_question, stop — do not repeat the same options in text

Gated tools

Mark dangerous tools for human approval in Eve (for example deploy or large refunds). When the model calls them, the chat pauses until the user approves or denies in the action panel. After denial, continue from the decision — do not retry the same action blindly.

create_robotrock_task

The RobotRock Eve integration exposes create_robotrock_task so agents can delegate inbox work:

• Call it only when the user explicitly asked to send an approval, or confirmed via ask_question.
• Set assignTo with user emails and/or group slugs.
• Set delegationReason when the chat user cannot self-approve.
• Link context data / ui for rich inbox widgets (same schema as sendToHuman).

When the assignee handles the task, RobotRock resumes the Eve session with a handled-task message so the agent can summarize the outcome in chat.

From your own backend (outside Eve), use client.tasks.create or sendToHuman instead.

Environment variables

Self-hosted (per workspace)

Set on your Eve deployment after connecting in Settings → Agents:

Multi-tenant (developer registry)

Reference implementation

The monorepo includes @robotrock/robotrock-agent — the hosted demo at https://robotrock-agent.vercel.app. Its agent/instructions.md shows delegation rules, ask_question examples, and refund threshold behavior.

Tool result display (OpenUI)

Eve tools return plain domain JSON plus optional replyGuidance via robotrock/eve formatTool* helpers. The agent must emit OpenUI Lang (```openui fences) for user-visible structured data — without it, results stay trail-only. See the RobotRock skill (tool-result-display and openui-lang references).

Related docs

• Connect an agent — wire the deployment to a workspace
• Chats API — spawn chats from cron jobs or other agents
• Send to human — task schema for delegated approvals
• Webhooks — how handled tasks notify external systems (chat resume uses the same payload shape internally)