# mosoo Docs

> Product and developer documentation for building, publishing, operating, and integrating mosoo Agents.

## Direct answers

- What is mosoo? mosoo is an open-source Agent runtime and API for coding agents. It provides durable Threads, Runs, files, sandboxed execution, tool events, and API access around published Agents.
- How does a product call an Agent? Publish the Agent, create a Project API key (msp_) in the same Project, keep it on a trusted backend, create a Thread with an application userId, send user events, and read or stream Thread events. Legacy account tokens are rejected.
- What runtime concepts matter? Projects isolate Agents, configuration resources, files, and usage. Agents define behavior and runtime, Threads keep durable user work, and Runs execute a published Agent version.
- How do I self-host mosoo? Deploy the open-source stack on Cloudflare Workers with the documented GitHub Actions or local Wrangler flow, then configure your model provider credentials.
- Where are the exact API schemas? Use the API reference and its OpenAPI 3.1 contract. The Public Thread API interacts with published Agents; it does not create, configure, or publish Agents.

## Start here

- [Product tour](https://mosoo.ai/docs/product-tour/)
- [Create your first Agent](https://mosoo.ai/docs/first-agent/)
- [Publish and API access](https://mosoo.ai/docs/publish-and-api-access/)
- [API quickstart](https://mosoo.ai/docs/quickstart/)
- [Authentication and Project API keys](https://mosoo.ai/docs/auth-and-access/)
- [API reference](https://mosoo.ai/docs/api-reference/)
- [OpenAPI 3.1](https://cloud.mosoo.ai/api/v1/openapi.json)
- [Deploy mosoo on Cloudflare](https://mosoo.ai/docs/deploy-mosoo/)
- [Errors and limits](https://mosoo.ai/docs/errors-and-limits/)
- [Complete documentation](https://mosoo.ai/docs/llms-full.txt)

## Page index

### mosoo Docs

- [mosoo documentation](https://mosoo.ai/docs/): Build, run, publish, and integrate managed AI Agents with mosoo.

- **Getting started**
- [Product tour](https://mosoo.ai/docs/product-tour/): Understand how Organizations, Projects, Agents, and runs fit together in mosoo.
- [Create your first Agent](https://mosoo.ai/docs/first-agent/): Configure, test, and publish an Agent from the mosoo console.
- CLI
  - [CLI](https://mosoo.ai/docs/cli/overview/): Install, authenticate, inspect, and operate mosoo from the terminal.
- [Deploy mosoo on Cloudflare](https://mosoo.ai/docs/deploy-mosoo/): Deploy mosoo with Cloudflare Workers from GitHub Actions or a local Wrangler toolchain.

- **Build agents**
- [Projects, Agents, and runtimes](https://mosoo.ai/docs/concepts/): Learn how mosoo's open-source agent runtime uses Projects, Agents, Threads, Runs, and sandbox drivers for coding agents.
- [Configure an Agent](https://mosoo.ai/docs/agent-configuration/): Set Agent identity, type, runtime, model, instructions, tools, and Environment.
- [Providers and models](https://mosoo.ai/docs/providers-and-models/): Add Project-level model credentials and make runtimes ready.
- [Skills and MCP servers](https://mosoo.ai/docs/skills-and-mcp/): Give Agents reusable instructions and authorized external tools.
- [Environments](https://mosoo.ai/docs/environments/): Create reusable runtime templates for Agent sessions.
- [Preview and debug](https://mosoo.ai/docs/test-and-debug/): Test an Agent and inspect Logs, Cost, Terminal, and working state.

- **Publish and operate**
- [Publish and API access](https://mosoo.ai/docs/publish-and-api-access/): Publish an Agent and choose Thread, API, or coding-agent delivery.
- [Runs, files, and usage](https://mosoo.ai/docs/operations/): Operate Agent work and understand its artifacts and model usage.
- [Import, export, fork, and versions](https://mosoo.ai/docs/import-export-versions/): Reuse Agent configuration safely and understand published history.
- [Common Agent patterns](https://mosoo.ai/docs/use-cases/): Choose an Agent type and mosoo features for common workflows.

- **API integration**
- [Quickstart](https://mosoo.ai/docs/quickstart/): Create a Thread on a published mosoo Agent with curl.
- [Agent API Endpoints](https://mosoo.ai/docs/agent-api-endpoints/): How a published mosoo Agent becomes callable from the public API.
- [Threads and Runs](https://mosoo.ai/docs/threads-and-runs/): How mosoo maps a published Agent call to Thread and Run lifecycle state.
- [Events and streaming](https://mosoo.ai/docs/events-and-streaming/): Read Thread output through event snapshots or Server-Sent Events.
- [Files](https://mosoo.ai/docs/files/): Upload files and mount them into mosoo API Threads.
- [Authentication and access](https://mosoo.ai/docs/auth-and-access/): How API tokens, Agent API Endpoints, and Thread visibility work together.

- **Reference**
- API Reference
  - [API Reference](https://mosoo.ai/docs/api-reference/): Generated reference for the mosoo Public Thread API.
  - [Create a Thread for an Agent API Endpoint](https://mosoo.ai/docs/api-reference/create-a-thread-for-an-agent-api-endpoint/): Creates a Thread and the backing AgentSession for the required application `userId`. If input is present, mosoo also queues the initial Run.
  - [List Threads for an Agent API Endpoint](https://mosoo.ai/docs/api-reference/list-threads-for-an-agent-api-endpoint/): Returns Threads created by the authenticated API token caller.
  - [Retrieve Thread summary](https://mosoo.ai/docs/api-reference/retrieve-thread-summary/): Returns the current Thread summary, its most recent Run, and links.
  - [Archive a Thread](https://mosoo.ai/docs/api-reference/archive-a-thread/): Archives the Thread so it is hidden from default Thread lists.
  - [Unarchive a Thread](https://mosoo.ai/docs/api-reference/unarchive-a-thread/): Restores a previously archived Thread to active Thread lists.
  - [Delete a Thread](https://mosoo.ai/docs/api-reference/delete-a-thread/): Permanently deletes the Thread and its backing AgentSession.
  - [Send user messages, permission decisions, or interrupts to a Thread](https://mosoo.ai/docs/api-reference/send-user-messages-permission-decisions-or-interrupts-to-a-thread/): Applies a batch of events to the Thread: send user messages, answer pending permission requests, or interrupt the current Run.
  - [List Thread events](https://mosoo.ai/docs/api-reference/list-thread-events/): Returns the latest public event log entries for this Thread in chronological order.
  - [Stream Thread events](https://mosoo.ai/docs/api-reference/stream-thread-events/): Streams public Thread event log entries as Server-Sent Events. Each `thread.event` data payload uses the same ThreadEventLogEntry shape…
  - [Upload an Agent file](https://mosoo.ai/docs/api-reference/upload-an-agent-file/): Uploads a file into the Agent API Endpoint's Project draft scope before a Thread exists. Use the returned file ID in create-thread or send-events resources.
  - [Retrieve file metadata](https://mosoo.ai/docs/api-reference/retrieve-file-metadata/): Returns public file metadata for a pre-Thread uploaded file or a file attached to a public Thread visible to the API token caller.
  - [List Thread files](https://mosoo.ai/docs/api-reference/list-thread-files/): Lists files attached to the Thread, including caller attachments and Agent artifacts.
  - [Download Thread file content](https://mosoo.ai/docs/api-reference/download-thread-file-content/): Downloads bytes for a ready Thread attachment or Agent artifact. The file must belong to a public Thread visible to the API token caller.
  - [Delete a file](https://mosoo.ai/docs/api-reference/delete-a-file/): Deletes a pre-Thread uploaded file or a file attached to a public Thread visible to the API token caller.
  - [Remove a Thread file](https://mosoo.ai/docs/api-reference/remove-a-thread-file/): Detaches a file from the Thread.
- [Errors and limits](https://mosoo.ai/docs/errors-and-limits/): Handle mosoo API errors, retries, idempotency, and public API limits.
- [mosoo API for coding agents](https://mosoo.ai/docs/coding-agents/): Machine-oriented guide for calling published mosoo Agents through the public API.
- [Changelog](https://mosoo.ai/docs/changelog/)

### mosoo 文档

- [mosoo 文档](https://mosoo.ai/docs/zh-Hans/): 使用 mosoo 构建、运行、发布并集成托管 AI Agent。

- **入门**
- [产品导览](https://mosoo.ai/docs/zh-Hans/product-tour/): 了解 mosoo 中组织、Project、Agent 与运行记录之间的关系。
- [创建第一个 Agent](https://mosoo.ai/docs/zh-Hans/first-agent/): 在 mosoo 控制台中配置、测试并发布一个 Agent。
- CLI
  - [命令行工具](https://mosoo.ai/docs/zh-Hans/cli/overview/): 从终端安装、认证、检查并操作 mosoo。
- [在 Cloudflare 上部署 mosoo](https://mosoo.ai/docs/zh-Hans/deploy-mosoo/): 通过 GitHub Actions 云端部署，或在本地使用 Wrangler 工具链部署 mosoo。

- **构建 Agent**
- [Project、Agent 与运行时](https://mosoo.ai/docs/zh-Hans/concepts/): 了解 mosoo 开源 Agent runtime 如何用 Project、Agent、Thread、Run 和 sandbox driver 支撑 Coding Agent。
- [配置 Agent](https://mosoo.ai/docs/zh-Hans/agent-configuration/): 设置 Agent 身份、类型、runtime、模型、指令、工具和 Environment。
- [模型服务商与模型](https://mosoo.ai/docs/zh-Hans/providers-and-models/): 添加 Project 级模型凭据并让 runtime 进入可用状态。
- [技能与 MCP 服务器](https://mosoo.ai/docs/zh-Hans/skills-and-mcp/): 为 Agent 添加可复用指令和已授权外部工具。
- [环境](https://mosoo.ai/docs/zh-Hans/environments/): 为 Agent session 创建可复用 runtime template。
- [预览与调试](https://mosoo.ai/docs/zh-Hans/test-and-debug/): 测试 Agent，并检查 Logs、Cost、Terminal 和工作状态。

- **发布与运营**
- [发布与 API 访问](https://mosoo.ai/docs/zh-Hans/publish-and-api-access/): 发布 Agent，并选择 Thread、API 或 coding-agent 交付方式。
- [运行、文件与用量](https://mosoo.ai/docs/zh-Hans/operations/): 运营 Agent 工作，理解 artifacts 与模型用量。
- [导入、导出、Fork 与版本](https://mosoo.ai/docs/zh-Hans/import-export-versions/): 安全复用 Agent 配置并理解发布历史。
- [常见 Agent 模式](https://mosoo.ai/docs/zh-Hans/use-cases/): 为常见工作流选择 Agent type 和 mosoo 功能。

- **API 集成**
- [快速开始](https://mosoo.ai/docs/zh-Hans/quickstart/): 用 curl 在已发布的 mosoo Agent 上创建 Thread。
- [Agent API 端点](https://mosoo.ai/docs/zh-Hans/agent-api-endpoints/): 已发布 mosoo Agent 如何变成可通过公开 API 调用的入口。
- [对话与运行](https://mosoo.ai/docs/zh-Hans/threads-and-runs/): mosoo 如何把已发布 Agent 调用映射为 Thread 和 Run 生命周期状态。
- [事件与流式传输](https://mosoo.ai/docs/zh-Hans/events-and-streaming/): 通过事件快照或 Server-Sent Events 读取 Thread 输出。
- [文件](https://mosoo.ai/docs/zh-Hans/files/): 上传文件并挂载到 mosoo API Thread。
- [认证和访问控制](https://mosoo.ai/docs/zh-Hans/auth-and-access/): API token、Agent API Endpoint 和 Thread 可见性如何配合。

- **参考**
- API 参考
  - [API 参考](https://mosoo.ai/docs/zh-Hans/api-reference/): mosoo 公开 Thread API 的生成参考。
  - [为 Agent API Endpoint 创建 Thread](https://mosoo.ai/docs/zh-Hans/api-reference/create-a-thread-for-an-agent-api-endpoint/): 为必需的应用 `userId` 创建 Thread 及其底层 AgentSession。如果提供 input，mosoo 也会排队启动初始 Run。如果省略 input，Thread 会立即以 IDLE 状态可见，且没有 Run。
  - [列出 Agent API Endpoint 的 Thread](https://mosoo.ai/docs/zh-Hans/api-reference/list-threads-for-an-agent-api-endpoint/): 返回由已认证 API token 调用方创建的 Thread。
  - [读取 Thread 摘要](https://mosoo.ai/docs/zh-Hans/api-reference/retrieve-thread-summary/): 返回当前 Thread 摘要、最近一次 Run 和链接。
  - [归档 Thread](https://mosoo.ai/docs/zh-Hans/api-reference/archive-a-thread/): 归档该 Thread，使其从默认 Thread 列表中隐藏。
  - [取消归档 Thread](https://mosoo.ai/docs/zh-Hans/api-reference/unarchive-a-thread/): 将之前归档的 Thread 恢复到活动 Thread 列表。
  - [删除 Thread](https://mosoo.ai/docs/zh-Hans/api-reference/delete-a-thread/): 永久删除该 Thread 及其底层 AgentSession。
  - [向 Thread 发送用户消息、权限决策或中断](https://mosoo.ai/docs/zh-Hans/api-reference/send-user-messages-permission-decisions-or-interrupts-to-a-thread/): 向 Thread 应用一批事件：发送用户消息、回答待处理的权限请求，或中断当前 Run。当 Thread 空闲时，用户消息会排队启动新的 Run。
  - [列出 Thread 事件](https://mosoo.ai/docs/zh-Hans/api-reference/list-thread-events/): 按时间顺序返回此 Thread 的最新公开事件日志条目。如果因为达到上限而省略了更早的公开条目，`truncated` 会为 true。事件 ID 是稳定的，因此调用方可以重试或轮询，而不会把同一个 ID 当作新事件处理。
  - [流式读取 Thread 事件](https://mosoo.ai/docs/zh-Hans/api-reference/stream-thread-events/): 以 Server-Sent Events 形式流式返回公开 Thread 事件日志条目。每个 `thread.event` data payload 都使用与 GET /threads/{threadId}/events 相同的 ThreadEventLogEntry 结构。
  - [上传 Agent file](https://mosoo.ai/docs/zh-Hans/api-reference/upload-an-agent-file/): 在 Thread 创建前，将文件上传到 Agent API Endpoint 所属 Project 的 draft scope。将返回的文件 ID 用于 create-thread 或 send-events 的 resources。
  - [读取 file metadata](https://mosoo.ai/docs/zh-Hans/api-reference/retrieve-file-metadata/): 返回 pre-Thread 上传文件或 API token 调用方可见公开 Thread 文件的公开 metadata。
  - [列出 Thread 文件](https://mosoo.ai/docs/zh-Hans/api-reference/list-thread-files/): 列出附加到 Thread 的文件，包括调用方附件和 Agent artifact。
  - [下载 Thread 文件内容](https://mosoo.ai/docs/zh-Hans/api-reference/download-thread-file-content/): 下载已准备好的 Thread 附件或 Agent artifact 的字节内容。该文件必须属于 API token 调用方可见的公开 Thread。
  - [删除 file](https://mosoo.ai/docs/zh-Hans/api-reference/delete-a-file/): 删除 pre-Thread 上传的文件，或删除 API token 调用方可见的公开 Thread 中的文件。
  - [移除 Thread 文件](https://mosoo.ai/docs/zh-Hans/api-reference/remove-a-thread-file/): 从 Thread 中移除文件关联。
- [错误与限制](https://mosoo.ai/docs/zh-Hans/errors-and-limits/): 处理 mosoo API 错误、重试、幂等和公开 API 限制。

### mosoo ドキュメント

- [mosoo ドキュメント](https://mosoo.ai/docs/ja/): mosoo でマネージド AI Agent を構築、実行、公開、統合します。

- **はじめに**
- [製品ツアー](https://mosoo.ai/docs/ja/product-tour/): mosoo における Organization、Project、Agent、Run の関係を理解します。
- [最初の Agent を作成](https://mosoo.ai/docs/ja/first-agent/): mosoo console で Agent を設定、テスト、公開します。
- CLI
  - [CLI](https://mosoo.ai/docs/ja/cli/overview/): terminal から mosoo をインストール、認証、確認、操作します。
- [Cloudflare に mosoo をデプロイ](https://mosoo.ai/docs/ja/deploy-mosoo/): GitHub Actions またはローカルの Wrangler toolchain から Cloudflare Workers に mosoo をデプロイします。

- **Agent を構築**
- [Project、Agent、runtime](https://mosoo.ai/docs/ja/concepts/): mosoo のオープンソース Agent runtime が Project、Agent、Thread、Run、sandbox driver で Coding Agent を支える仕組み。
- [Agent を設定](https://mosoo.ai/docs/ja/agent-configuration/): Agent の識別情報、タイプ、runtime、モデル、指示、tool、Environment を設定します。
- [Provider とモデル](https://mosoo.ai/docs/ja/providers-and-models/): Project レベルのモデル認証情報を追加し、runtime を利用可能にします。
- [Skill と MCP server](https://mosoo.ai/docs/ja/skills-and-mcp/): Agent に再利用可能な指示と認証済み外部 tool を追加します。
- [Environment](https://mosoo.ai/docs/ja/environments/): Agent session 向けの再利用可能な runtime template を作成します。
- [プレビューとデバッグ](https://mosoo.ai/docs/ja/test-and-debug/): Agent をテストし、Logs、Cost、Terminal、作業 state を確認します。

- **公開と運用**
- [公開と API access](https://mosoo.ai/docs/ja/publish-and-api-access/): Agent を公開し、Thread、API、coding-agent の提供方法を選択します。
- [Run、ファイル、使用量](https://mosoo.ai/docs/ja/operations/): Agent の作業を運用し、artifact とモデル使用量を理解します。
- [インポート、エクスポート、fork、バージョン](https://mosoo.ai/docs/ja/import-export-versions/): Agent 設定を安全に再利用し、公開履歴を理解します。
- [一般的な Agent パターン](https://mosoo.ai/docs/ja/use-cases/): 一般的な workflow に合う Agent タイプと mosoo 機能を選択します。

- **API 統合**
- [クイックスタート](https://mosoo.ai/docs/ja/quickstart/): curl を使って公開済み mosoo Agent に Thread を作成します。
- [Agent API Endpoint](https://mosoo.ai/docs/ja/agent-api-endpoints/): 公開済み mosoo Agent を public API から呼び出せるようにする仕組みです。
- [Thread と Run](https://mosoo.ai/docs/ja/threads-and-runs/): mosoo が公開済み Agent の呼び出しを Thread と Run の lifecycle state に対応付ける方法です。
- [イベントとストリーミング](https://mosoo.ai/docs/ja/events-and-streaming/): event snapshot または Server-Sent Events から Thread output を読み取ります。
- [ファイル](https://mosoo.ai/docs/ja/files/): ファイルを upload して mosoo API Thread に mount します。
- [認証とアクセス](https://mosoo.ai/docs/ja/auth-and-access/): API token、Agent API Endpoint、Thread visibility の連携を説明します。

- **リファレンス**
- API リファレンス
  - [API リファレンス](https://mosoo.ai/docs/ja/api-reference/): mosoo Public Thread API の自動生成リファレンスです。
  - [Agent API Endpoint の Thread を作成する](https://mosoo.ai/docs/ja/api-reference/create-a-thread-for-an-agent-api-endpoint/): 必須のアプリケーション `userId` に対して Thread とその裏側の AgentSession を作成します。input がある場合、mosoo は最初の Run もキューに入れます。input を省略すると、Thread は Run なしの IDLE 状態ですぐに表示されます。
  - [Agent API Endpoint の Thread をリストする](https://mosoo.ai/docs/ja/api-reference/list-threads-for-an-agent-api-endpoint/): 認証された API token 呼び出し元によって作成された Thread を返します。
  - [Thread の概要を取得](https://mosoo.ai/docs/ja/api-reference/retrieve-thread-summary/): 現在の Thread の概要、最新の Run、およびリンクを返します。
  - [Thread をアーカイブする](https://mosoo.ai/docs/ja/api-reference/archive-a-thread/): Thread をアーカイブして、デフォルトの Thread リストから非表示にします。
  - [Thread のアーカイブを解除する](https://mosoo.ai/docs/ja/api-reference/unarchive-a-thread/): 以前にアーカイブされた Thread をアクティブな Thread リストに復元します。
  - [Thread を削除する](https://mosoo.ai/docs/ja/api-reference/delete-a-thread/): Thread とそのバッキング AgentSession を完全に削除します。
  - [ユーザー メッセージ、権限決定、または割り込みを Thread に送信します。](https://mosoo.ai/docs/ja/api-reference/send-user-messages-permission-decisions-or-interrupts-to-a-thread/): Thread に一連のイベントを適用します。user message の送信、保留中の permission request への回答、現在の Run の中断ができます。Thread が idle の場合、user message は新しい Run を queue に追加します。
  - [Thread イベントのリスト](https://mosoo.ai/docs/ja/api-reference/list-thread-events/): この Thread の最新のパブリック イベント ログ エントリを時系列順に返します。制限に達したために古いパブリック エントリが省略された場合、`truncated` は true になります。
  - [Thread イベントをストリーミングする](https://mosoo.ai/docs/ja/api-reference/stream-thread-events/): パブリック Thread イベント ログ エントリをサーバー送信イベントとしてストリーミングします。各 `thread.event` データ ペイロードは、GET /threads/{threadId}/events と同じ ThreadEventLogEntry 形状を使用します。
  - [Agent ファイルをアップロードする](https://mosoo.ai/docs/ja/api-reference/upload-an-agent-file/): Thread 作成前に Agent API Endpoint の Project draft scope にファイルをアップロードします。返された file ID を create-thread または send-events の resources で使用します。
  - [ファイルのメタデータを取得する](https://mosoo.ai/docs/ja/api-reference/retrieve-file-metadata/): Thread より前のアップロード ファイル、または API token 呼び出し元に表示されるパブリック Thread に添付されたファイルのパブリック ファイル メタデータを返します。
  - [Thread ファイルをリストする](https://mosoo.ai/docs/ja/api-reference/list-thread-files/): 発信者の添付ファイルや Agent アーティファクトなど、Thread に添付されたファイルをリストします。
  - [Thread ファイルコンテンツをダウンロード](https://mosoo.ai/docs/ja/api-reference/download-thread-file-content/): 準備ができた Thread 添付ファイルまたは Agent アーティファクトのバイトをダウンロードします。ファイルは、API token 呼び出し元に表示されるパブリック Thread に属している必要があります。
  - [ファイルを削除する](https://mosoo.ai/docs/ja/api-reference/delete-a-file/): Thread より前にアップロードされたファイル、または API token 呼び出し元に表示されるパブリック Thread に添付されたファイルを削除します。
  - [Thread ファイルを削除する](https://mosoo.ai/docs/ja/api-reference/remove-a-thread-file/): Thread からファイルを切り離します。
- [エラーと制限](https://mosoo.ai/docs/ja/errors-and-limits/): mosoo API のエラー、再試行、idempotency、public API limit を処理します。