BRIEFLOOP / GUIDES

External agents and CLI

Let your agent submit reports, save revisions and download version-bound Word files.

Current installers: Mac 0.22.2, Windows 0.22.2. Labels and capabilities vary by channel; the installer version is authoritative. Development features are not implied.

Before you start

Use a workspace you can back up. Model tasks require an authenticated runtime and permission to process the chosen materials.

Steps

1. Install the briefloop CLI and open the intended workspace on the same machine. Configure its model, sources and company-context choice.
2. Run discover and proceed only when ready=true. Run skill to obtain the protocol shipped with your installed version.
3. Inspect source IDs, submit with a stable request_id, and query the returned job_id. Preserve failures and any saved drafts.
4. Read a specific version. Revise with the complete editor_document and base_version. Export, query artifact_available, then download.

What success looks like

Real job and version IDs are returned; the CLI verifies the downloaded Word hash. Drafts, revisions and task state stay linked.

If something goes wrong

This connects to an existing local service, not a remote MCP server. Submit uses the workspace model and its billing; revise saves edits made by the external agent. Formal delivery still uses existing checks. Do not edit SQLite directly or retry an unknown result with a new request_id.

Copyable commands and requests

python -m pip install --upgrade briefloop
briefloop external --workspace "/absolute/workspace" discover
briefloop external --workspace "/absolute/workspace" skill
briefloop external --workspace "/absolute/workspace" request --file request.json

Write one JSON object to request.json per operation. Replace example IDs with values returned by the service; do not submit these placeholders unchanged.

inspect

{
  "action": "inspect"
}

submit

{
  "action": "submit",
  "request_id": "report-unique-id",
  "source_ids": [
    "src_actual_id"
  ],
  "requirements": {
    "title": "本期简报",
    "objective": "概括已上传材料的变化及影响",
    "allow_web": false,
    "writing_mode": "general",
    "target_words": 500,
    "max_words": 700
  }
}

query

{
  "action": "query",
  "job_id": "job_actual_id"
}

read

{
  "action": "read",
  "version_id": "brief_actual_id"
}

export

{
  "action": "export",
  "request_id": "export-unique-id",
  "version_id": "brief_actual_id"
}

briefloop external --workspace "/absolute/workspace" download --job job_export_id --output "/existing/output/report.docx"

For internal reports, use internal_report and finish the company-context choice first; do not switch writing mode to bypass it. For edits, read the full document and use revise with a fresh request_id and the exact base_version. Keep the same ID and body when retrying a lost response.

Agent Skill and full protocol · GitHub

← All guides · Installation options →