Documents, tools, and artifacts
Platform capabilities reach your agent as MCP tools, not protocol extensions. The worker runtime passes an MCP server in session/new.mcpServers with a short-lived, session-scoped token already embedded. Your agent connects with any MCP client, or just uses the tools if your framework auto-discovers them.
The server is offered over stdio (every ACP agent must support stdio MCP servers). Agents that advertise mcpCapabilities.http get the HTTP transport directly. The server includes block tools, review verdict reporting when the step permits it, and report_result. Plan, research, and review routing require declaring the mode in the manifest and passing conformance; the tools on this page are what that check exercises.
Shipping modes: ["code"]? You can skip most of this page. The artifact-block model below matters for plan, research, and review turns. A code-only runtime needs just two sections: result summaries and credentials.
Workflow artifacts
Each linked task keeps one canonical artifact per workflow artifact type, addressed by a target parameter: "plan", "research", "review", or "code_summary". Your agent never needs to track an artifact's storage ID. Artifacts are structured as addressable blocks, and six tools operate at block level so parallel steps never clobber each other: list_artifact_blocks, load_artifact_blocks, append_artifact_block, replace_artifact_block_body, update_artifact_block_metadata, and find_related_blocks. See the MCP tool reference for their exact parameters.
This is a different thing from a task's manually linked documents (specs, requirements, and similar reference material a person attached to the task) — those have their own list_linked_documents / read_linked_document tools, also on the MCP tool reference page.
A plan turn fulfills its contract with calls like:
append_artifact_block { "target": "plan", "id": "PLAN-TASK-003", "type": "implementation_task", "title": "Separate pass-scoped retry accounting", "markdownBody": "Extract the retry accounting into pass-scoped counters in retry.py."}
| Artifact | Written by | Common block types |
|---|---|---|
| Plan | plan turns | goal, requirement, implementation_task, decision, risk, open_question |
| Research | research turns | research_question, context, existing_solutions, approach, findings, options, tradeoffs, recommendation, open_questions, sources |
| Review | review turns | review_finding (severity + lifecycle status) |
| Result summary | code turns | implementation_note, fixed_finding, blocker |
Expected inputs and outputs are declared per workflow step and enforced by the tools: a code step can read review findings but not rewrite the review artifact.
Never rewrite whole workflow artifacts, and never commit artifact files into the product repository. Operate at block level through the tools above.
Review verdicts
review turns finish through one tool:
report_workflow_verdict { "verdict": "approve" | "feedback" | "reject", "summary": "One paragraph a human reads in the run timeline."}
Record findings as review_finding blocks first, then report the verdict. An end_turn on a review turn without this call fails the turn; the host cannot guess a verdict from prose.
Result summaries
Every mode can end with an explicit result:
report_result { "summary": "Fixed the retry accounting; two tests added; branch pushed."}
This is the preferred way to say what happened: validated at call time and rendered verbatim in the run timeline. Agents that never call it (a stock ACP agent that does not know these tools) fall back to their final message text.
The design rule: anything the model decides is a tool call; anything your agent code already knows (tokens, status, progress text) is an ACP event. Tool calls give model decisions schemas, validation errors, and retries. Events give mechanical facts a cheap streaming channel.
Visual artifacts
_meta["onehorizon.ai"].artifactsDir (also exported as ONE_WORKER_ARTIFACTS_DIR) names a writable directory for verification media: screenshots, screen recordings, rendered diffs. Files your agent leaves there are uploaded by the host after the turn and attached to the session, no tool call needed. Use it for evidence, not build output. Uploads accept images and video only, up to the size cap in limits and security.
Task interaction
The task's title, bounded description, and existing comments arrive as untrusted prompt content, not through a tool call. The same MCP server adds get_task_details for fetching the complete current task, get_parent_details for fetching the linked parent initiative when one exists, and list_task_comments for checking comments added since the turn started. All three take no task ID input — they always resolve to the turn's own fixed task (and its parent) rather than an agent-supplied one — and stay inside the turn's workspace; see the MCP tool reference for their parameters.
There is no separate tool for posting a progress comment: report_result (above) is what the platform surfaces as the task's comment. There is no tool for linking a pull request either. Creating and linking the PR or MR is automatic once your agent pushes a branch, handled by the workspace's connected GitHub or GitLab integration, not by a tool call from your agent.
Credentials and scope
- The MCP token is minted per turn, scoped to the session's task, workflow run, and declared artifacts. It expires when the turn ends.
- Your agent never receives the user's OAuth token, workspace API keys, or other sessions' data.
- Tool calls that exceed the step's declared outputs fail with a descriptive error. Treat that as a contract signal, not a retry candidate.