<span id="消息连接与知识读取对象"></span>

# Message connections and knowledge reading objects

Ingress connections are workspace management resources. Runtime knowledge APIs are for the current agent task and require its identity, source scope, and short-lived authorization.

<span id="连接与输入标识"></span>

## Connection and input identifiers

| Variable | Source |
| --- | --- |
| `WORKSPACE_ID`, `AI_STUDIO_API_KEY` | Workspace in the current environment and a personal access token with the required privileges. |
| `AGENT_WORKSPACE_ID`, `AGENT_ID` | Actual owning workspace and ID of the agent selected from the catalog. |
| `AGENT_MODEL` | Runtime model available to the current target; required explicitly for agent targets. |
| `CONNECTION_ID` | id from a creation response or the same target's connection list. |
| `ASSOCIATION_VERSION` | association_version from the latest connection details. |
| `CONFIG_VERSION` | config_version from the latest connection details. |
| `MANAGED_CREDENTIALS_FILE` | JSON file containing credentials required to create the selected platform's managed connection. Restrict access and do not write it to logs or the repository. |
| `CALLBACK_URL` | Full HTTPS callback URL for the deployment; its path matches callback_path in connection details. |

The owning workspace must match the path and X-Workspace-ID. A team target belongs to that workspace. An agent target belongs to the current or system workspace. Use actual catalog values rather than inventing workspace identifiers.

<span id="消息接收连接"></span>

## Ingress connections

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Ingress connection ID. |
| `workspace_id` | string | Execution workspace. |
| `target.kind` | string | agent or team. |
| `target.workspace_id` | string | Workspace that owns the target. |
| `target.id` | string | Target identifier. |
| `provider` | string | Selected platform. |
| `channel_type` | string | Selected channel type. |
| `receive_mode` | string | managed_stream, callback, or mail_polling. |
| `channel_instance_id` | string | Independent channel instance referenced by callback/mail_polling. |
| `provider_config` | object | Readable nonsensitive platform configuration. |
| `agent_model` | string | Model selected for the agent target. |
| `association_version` | integer | Target association version. |
| `config_version` | integer | Current connection configuration version. |
| `connected_by_user_id` | string | User who established the connection. |
| `enabled` | boolean | Whether enabled. |
| `account_identity` | string | Associated platform account identity. |
| `desired_state` | string | enabled or disabled. |
| `observed_state` | string | State currently observed by the receiver. |
| `last_receive_at` | string | Last receive time; returned when present. |
| `last_error_code` | string | Most recent runtime error code; returned when present. |
| `callback_path` | string | Deployment-relative callback path in callback mode; returned when present. |
| `created_at` | string | Creation time. |
| `updated_at` | string | Update time. |

`starting/reconnecting` means establishing or recovering a connection. For `auth_failed/config_invalid`, fix credentials or configuration first. `connected` describes only the connection layer; verify actual messages, target tasks, and replies. `waiting_for_first_message` waits for the first external input. `stopped` indicates stopped.

Creating managed_stream enables the connection and enters starting; mail_polling waits for input; callback starts disabled. A successful callback `/test` enables the connection and increments config_version; it is not a read without side effects.

<span id="托管凭据"></span>

### Managed credentials

| Platform combination | Required for creation | Required for update |
| --- | --- | --- |
| wecom / wecom_ai_bot | bot_id、secret | secret |
| slack / slack_app | app_id, app_token, bot_token | app_token or bot_token; both may be updated |
| feishu / feishu_app | app_id、app_secret | app_secret |

Slack App Tokens start with xapp- and Bot Tokens with xoxb-. Do not include fields from another platform. Do not resend the creation App ID/Bot ID during updates. Handle platform account identity separately from rotatable secrets.

<span id="回调校验的两类成功-http-响应"></span>

### Two successful HTTP response shapes for callback verification

Successful verification returns a connection object. If the provider channel test fails, HTTP 200 may instead return a test object containing `ok:false`, `status`, `last_test_status`, `last_test_error`, optional error classifications/suggestions, and `last_tested_at`. Do not check HTTP status alone or read this as a connection object.

Telegram verification registers the current full HTTPS Webhook URL. Other platform branches verify the channel instance; failures appear in a test object or error response. Managed and mail-polling modes do not use this verification operation.

<span id="企业微信扫码"></span>

### WeCom QR authorization

The pending QR API response includes session_token, qr_url, and expires_at. Poll with the original token while retaining the same account, target, and workspace. authorized returns bot_id/secret but has not saved an actual ingress connection; call creation next. End the old session after expired and honor 429/Retry-After rather than polling indefinitely. Pass these tokens and secrets only to a protected client.

<span id="任务知识连接"></span>

## Task knowledge connections

| Variable | Source |
| --- | --- |
| `MOI_ENDPOINT` | Product service prefix injected into the current task. Do not replace it with another environment or an address saved in the terminal. |
| `MOI_API_KEY` | Technical connection credential for the current task. |
| `MOI_WORKSPACE_ID` | Execution workspace of the current task. |
| `MOI_RUNTIME_AUTHORIZATION` | Complete short-lived authorization header value injected into the task; retain unchanged. |
| `REQUEST_ID` | Distinct ID generated for each new operation. Retain this ID and original input when replaying the same request. |
| `KNOWLEDGE_QUERY` | Effective retrieval text for the current question. |
| `ARTIFACT_ID` | Original artifact_id from retrieval/query within the same task. |
| `CHUNK_ID` | Original chunk_id of the selected text evidence. |
| `FILE_ID` | file_id of the same text evidence. |
| `SEMANTIC_MODEL_ID` | Actual integer model ID returned with the same evidence. |
| `MARKDOWN_FILE_ID` | Parsed-source location ID from evidence. Do not derive it from the original file ID. |
| `TABLE_NAME` | Table name allowed for the task by describe-tables. |
| `KNOWLEDGE_SQL_FILE` | Read-only SQL text file prepared from the schema read and the question. |
| `CITATION_SOURCES_FILE` | JSON array containing all sources actually used in the current answer. |

These APIs do not accept a regular PAT in place of task identity or allow switching task, user, or role in the body. request_id must be 1–256 bytes, have no surrounding whitespace, and not start with audit:. Do not use a new ID to bypass replay checks for the same operation.

<span id="知识结果与读取模式"></span>

## Knowledge results and read modes

Successful runtime knowledge HTTP envelopes use code="OK". data includes call_id, output, and optional failed/artifacts/metadata. failed=true is still a business failure. All output retains task evidence identity; do not reconstruct file, model, or artifact IDs from names.

Complete text retrieval chunks are stored in artifacts[].data.chunks. When reading, retain the same artifact_id and chunk_id/file_id/semantic_model_id. output may be a bounded view. A preview or truncated text cannot establish a complete-read proof.

| Read mode | Input | Completion and continuation |
| --- | --- | --- |
| Single evidence chunk | artifact_id, chunk_id, and file_id/semantic_model_id as needed; integer cursor | Original text in output.content; continue with the original next_cursor when has_more is true. |
| Evidence list | artifact_id without single-chunk selection; explicitly start with object cursor={item_index:0,content_offset:0} | output.items contains the page window. complete=true means finished; otherwise continue with object next_cursor. |
| Fixed artifact part | artifact_id, part_index | output.part and part_count. Do not combine with chunk, character pagination, or local-read proof fields. |
| Register a complete local read | Single-chunk identity and local_content_sha256, or local_reads array | Registered after the server verifies the original content digest. Do not combine with pagination parameters. |
| Parsed Markdown | markdown_file_id, integer cursor | output.content. Stop when next_cursor=0; there is no has_more. |

Evidence character windows range from 1 to 8000; omitted/0 uses 2000. Cursors count Unicode characters, not UTF-8 bytes. Nonpositive Markdown windows use 8000, maximum 20000. Markdown and evidence windows have different defaults.

With artifact_id alone and no read mode, generic reads may instead return the artifact object and part_count. Do not assume evidence-list pagination was selected.

A local single-chunk read proof requires artifact_id/chunk_id and the complete content digest; file_id/semantic_model_id locate the content. Each local_reads item supplies this identity and digest. Do not combine the batch form with top-level single-chunk fields. Success registers a complete read of that task's original chunk only, not the entire source or knowledge base.

Parsed source text is reconstructed from currently effective chunks. Persisted evidence artifacts and current parsed-source projections serve different purposes. The fact that current chunk reads reflect deletion/disabling does not imply every historical artifact is rewritten.

<span id="检索和引用"></span>

### Retrieval and citations

Regular search requires valid keywords and max_hits greater than 0. source_page mode uses model ID, file ID, page size, and opaque cursor and cannot be combined with regular search fields. Stop according to output.source_page.has_more. Listing enabled indexed chunks by source is not semantic ranking and does not prove unindexed content is absent.

Image retrieval returns output.results, count, the applicable mode, and corresponding artifacts. Query image IDs and returned image-evidence identifiers are not interchangeable. API parameters do not accept model-internal query_visual or multi-image fields.

Structured queries allow read-only SELECT on tables permitted for the current task. Results include actual SQL, columns, rows, row count, truncation, and source artifacts. Omitting semantic_claims does not bypass mandatory semantic conditions saved by the server. Read schemas and constraints before querying and selecting sources.

cite submits the complete source set for the current answer. Text sources must retain at least type=rag_chunk, artifact_id, chunk_id, and original identity. Explicitly send sources:[] when there is no evidence. Check output.accepted. If not accepted, read the returned unread windows before selecting again. After acceptance, write the answer from the evidence.

<span id="错误与环境"></span>

## Errors and environments

Ingress business success uses numeric code 0. Business errors use numeric code/message/details.reason, while admission may use string code/msg. Runtime knowledge usually uses string code/msg. Handle data.failed or output.accepted=false separately even under HTTP 200.

A capability list proves only declared implementation, not environment readiness. Callback verification and QR requests may call providers and require temporary accounts, controlled targets, and a cleanup plan. Do not reuse callbacks or task authorizations between environments.
