SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsarkcli-agent

arkcli-agent

Agents & models

View repository

Updated 10-16 10:55

About this skill

arkcli agent

CRITICAL — before starting you MUST first read ../arkcli-shared/SKILL.md。

Use this skill when the user needs to create, query, debug, or connect an ARK Managed Agent. Core principles: first use stable product commands, do not directly guess OpenTOP Actions; Session runtime resources, events, threads, and the Files API use direct data-plane connections; for MCP OAuth login, first query the backend provider, then use arkcli agent +mcp-login。

Before execution, read the corresponding reference according to "choose the path first"; read only the relevant reference, there is no need to load all details at once. If the user request is already clearly a write operation such as create, copy, attach file, chat, MCP login, etc., execute it directly after completing the necessary confirmation/disambiguation, do not just provide command suggestions.

Minimal decision table for creating an Agent

User input AI Agent handling
No model specified Execute only once arkcli agent model list --query "<用户业务意图>" --primary-only --format json, obtain candidates from the complete structured result; do not omit the query value, do not truncate the output with pipes/redirection, and do not piece together model IDs from memory
No Skill specified First query this account's custom skills; if there is no suitable candidate, then query market/SkillHub skills
Provide a local Skill zip First call agent skill create --zip, and after obtaining the returned skill-... ID and version, then create the Agent
No tools specified Use the complete default toolset injected by the CLI; when --tool is explicitly passed, fully replace the default tools
No environment specified When creating a Session, automatically select the latest environment of the current project; only prompt to create one or pass in an environment ID if no environment is available
Creation succeeded Must read back agent agent get <agent-id> --format json, and display the server's final Model, System, Tools, Skills, McpServers, and extended configuration
The user expects an Agent reply For short requests use +new session ... --message or events send ... --stream; for large payloads / long-running tasks use events send --poll, or after send returns immediately poll events by cursor / use +tail, do not make all tasks block and wait

Business goal clarification

When targets such as model, Agent, Skill, MCP provider, etc. cannot be uniquely determined, follow arkcli-shared the 0/1/N structured selection contract: first perform one minimal read-only query, and take options only from the real IDs and distinguishing fields in this round's complete structured result. When multiple candidates would change the remote result, use the host's structured selection capability; if there is a unique candidate, continue directly. Selecting a target only completes disambiguation, and does not equal authorization for subsequent creation, update, or deletion.

Model selection is a mandatory stopping point for creating an Agent: only the hard constraints explicitly given by the user and the product eligibility fields may be used to filter the above query results; relevance, return order, recommendations, or the Agent's own "more suitable" judgment cannot turn multiple candidates into a unique candidate. If after filtering there are N (N > 1), the real items[].model must be given to the user to choose; before the user selects, do not query Agent Skill, and do not execute any preview,agent agent create/update、 +new-agent or +iterate. This is also the hard return point for the current turn: after displaying candidates, end the turn immediately, and do not further probe the above write commands' --help, it does not prepare subsequent parameters, nor does it query Skill/MCP candidates. Recommendations may be annotated with reasons, but they cannot make the choice on behalf of the user.

Choose the path first

User intent Preferred command Details
Create / update / delete a Managed Agent arkcli agent agent ... references/agent.md
Copy an existing Agent and rename it / partially override the configuration arkcli +new-agent --fork <agent-id> [--name <new-name>] references/agent.md
Select an available model for creating an Agent arkcli agent model list references/agent.md
Select a Skill when creating an Agent By default, query custom first, and if there is no hit then query market; when the user explicitly specifies market, skip custom references/skills.md
Query/use this account's custom skill First agent skill list --source custom --limit 100, and when there is no match, follow NextPage pass --page to continue; when the complete candidates are needed, then use --page-all / --skill <skill-id> references/skills.md
Upload a local custom skill zip arkcli agent skill create --zip <file> or agent agent create --skill-zip <file> references/skills.md
Manage custom Skill versions / delete a Skill First list all versions completely, then delete in the dependency order "non-latest -> latest -> Skill" references/skills.md
Create a runtime environment / session arkcli agent env ... / arkcli agent session ... references/session-files.md
Environment initialization script arkcli agent env create/update --setup-script @./bootstrap.sh references/session-files.md
Session one-time override of Agent / Environment arkcli agent session create --agent-overrides ... --environment-overrides ... references/session-files.md
Bind a TOS directory when the Session is created Use after the user explicitly provides the address arkcli agent session create --tos-path tos://<bucket>/<prefix>/; if not provided, ask first and do not guess the path references/session-files.md
Select/continue a Managed Agent session arkcli +new session references/events-chat.md
Directly create a new session and chat arkcli +new session <agent-id> --environment-id <env-id> references/events-chat.md
Send a message to an existing session or view replies in real time By default, events send is only responsible for writing; when an SSE reply is needed, add --stream to automatically follow the event cursor (--wait is retained as a compatibility alias), and the real-time entry requests by default agent.message / agent.thinking Event Deltas; you can also use +tail/events stream，--no-event-deltas to fall back to complete events;+new session/+iterate internally automatically uses the compensation channel references/events-chat.md
View session diagnostics / export a diagnostic package arkcli +debug <session-id> / arkcli +export <session-id> references/debug-export.md
Upload a file and attach it to an existing session arkcli agent session resources add <session-id> --path <file> references/session-files.md
Only upload / query Files API files arkcli agent file upload/list/get/wait/delete references/session-files.md
Manage memory store / memories arkcli agent memory-store ... references/interfaces-gaps.md
Query mountable MCP / manage Vault / Credential / MCP OAuth arkcli agent vault oauth-provider list / arkcli agent vault ... / arkcli agent +mcp-login ... references/mcp-vault.md

Authentication and Profile

  • Before business commands, first arkcli auth status --format json. When not logged in, when SSO has expired, or when STS refresh fails, handle login first.
  • The current data plane Files / Session resources / events / threads requires a usable ARK API Key. By default, the CLI uses the Key resolved from the profile / identity; you can also use the global --api-key to override for this call. If you also customize --base-url, the two must be explicitly provided as a pair; stateless mode without a Profile must also provide them as a pair.
  • The online environment is ready, use by default --env prod, and do not run stg by default anymore.
  • Non-interactive SSO login is two-stage: first arkcli auth login --no-browser to get the URL; after the user pastes back the base64 code, then run arkcli auth login --no-browser --code <code>。

List pagination

  • Lists that support the pagination contract can add the global --page-all; when the single-page size is not explicitly passed, the CLI defaults to 100 items per page. By default, it requests at most 10 pages, which can be increased with --page-limit <N> ,--page-delay <ms> controls the page interval.
  • Supported: Agent/version, Env, Session, Skill market/custom, Memory Store/Memories, Vault/Credentials/OAuth Provider, Files, Session Events/Threads. The CLI uses them separately according to the backend contract Page、PageNumber、PageToken、after, and merges the results.
  • agent model list、memory-store creators、session resources list have no available pagination contract; do not assume --page-all can complete the results for them. After hitting --page-limit , check the returned NextPage、has_more or TotalCountto determine whether there is still unfetched data.

Deletion confirmation

  • Managed Agent's destructive delete command, on a real TTY and without --yes passed, displays an irreversible warning and asks [y/N]; only when y/yes is entered will the backend be called; any other input cancels.
  • Non-interactive environments (AI Agent, CI, pipes) do not read stdin; when --yes is not passed, it returns type=requires_confirmationand does not call the backend. Only after the user has explicitly confirmed the deletion target may the caller add --yes to retry.
  • --dry-run is not a global capability. It is available only when the command itself --help lists that flag; currently it mainly covers Env/Session/Memory/Vault/Credential write requests that can be determined by the local payload, as well as agent agent create/update/delete、agent skill create/update/delete and agent file upload/delete, and agent skill download、 +export。+new-agent、+iteratewhich writes local files, MCP login, and all pure read commands are not registered. Client Preview only generates a zero-network preview.v1 plan; it does not replace provisioning, version/dependency validation, or deletion confirmation before real execution.

Long-running process execution rules

  • One shell/tool call executes only one arkcli command. Do not chain session create, write IDs,events send、events list with &&、;, pipes, or heredocs into one long command.
  • session create, Agent creation, file upload, and other write operations succeed, immediately extract and save the ID from the structured output; the next call uses the already-confirmed literal ID, and do not rely on variable assignment in the same shell to continue execution.
  • When any step exceeds the expected time, first end that step and separately run session get、events list or +debug for diagnosis; do not let subsequent commands be masked by a preceding blocking step.
  • Do not parse large JSON or large text through a Python/Node pipe in the same shell call; first let arkcli --format json return independently, then parse the result in the next step. This way, even if the request times out, you can distinguish whether the failure occurred at the creation, sending, or query-back stage.

Timeouts and retries

  • Only perform limited retries for network timeouts, connection interruptions, 429, or 5xx; parameter validation, authentication failures, not provisioned, insufficient permissions, and explicit business errors are thrown directly and must not be retried.
  • session create After a timeout, the result may be unknown. First use session list/get to check whether it has already been created based on the returned title, Agent, environment, and creation time, then decide whether to retry; without an idempotency key, do not blindly repeat the creation.
  • events send After a timeout, it may also have already been received by the server. First use the returned event cursor, send time, or the most recent user event to query events list; only after confirming there is no receipt record is retry allowed, to avoid sending the user message repeatedly.
  • events send --stream After reaching the stream wait limit, it automatically switches to events list polling, waiting another 120 seconds by default;--wait retains the same behavior as a compatibility alias. Only when both phases time out does it return a non-zero error with a cursor recovery command. At this point, do not resend the original message; continue to list/poll the same cursor.
  • events list/get This is a read-only request and may be retried a limited number of times with exponential backoff; continue using the same after cursor, and do not re-read from the beginning of the history because of a retry.
  • At each step, retain the step name, Session ID, event cursor, attempt count, and last error; after reaching the retry limit, throw an error with context, and do not disguise a timeout as success.

Command Quick Reference

Command Description
arkcli agent agent list/get/create/update/delete/versions Agent CRUD + versions
arkcli agent model list Query the Managed Agent model allowlist;--query enrich/sort the allowlist with model catalog details; output items[].model can be used directly as --model
arkcli +new-agent Agent create enhanced entry point; supports --fork/--from creating a new Agent after copying an existing Agent
arkcli +iterate Update the Agent configuration, create a new Session, and enter one-shot/REPL trial run;--environment-id/--env-id optional; when omitted, the latest environment is selected automatically
arkcli agent skill search/list/get/create/update/delete/versions/download Market skill search, custom skill query for this account, custom Skill zip upload, version update, version list, and download; deletion must be performed in the order “non-latest → latest → Skill”; custom queries go through TOP ListSkills
arkcli agent env list/get/create/update/delete Environment CRUD; currently env list does not have --status, for status filtering rules see session-files.md
arkcli agent session list/get/create/update/delete Session CRUD
arkcli agent session resources list/add/get Data plane session resources; get is CLI local filtering based on list
arkcli agent session events list/send/stream Data plane events; stream requests Event Deltas by default and outputs SSE/NDJSON lines;--no-event-deltas falls back to full events;user.custom_tool_result must include custom_tool_use_id，user.tool_result only allows self_hosted, and the CLI performs a pre-check
arkcli agent session threads list/get Data plane threads
arkcli agent file list/get/upload/wait/delete Data plane Files API
arkcli agent memory-store list/get/create/update/delete Memory Store CRUD
arkcli agent memory-store memories list/get/create/batch-create/update/delete Memory CRUD
arkcli agent vault list/get/create/update/delete Vault CRUD
arkcli agent vault oauth-provider list Query MCP Providers registered on the backend; the returned MCP server information can be used for Agent --mcp-server
arkcli agent vault oauth-flow create Bare creation of a Vault OAuth Flow, suitable for scripts that bring their own redirect URL
arkcli agent vault credentials list/get/create/update/delete Credential CRUD
arkcli agent +mcp-login Managed MCP OAuth login: local callback + CreateVaultOAuthFlow + wait for credential creation
arkcli +chat <prompt> Responses API quick conversation; do not use it as a Managed Agent session entry point
arkcli +tail <session-id> Human-readable event stream
arkcli +new session Managed Agent session selector; can continue an existing session, or select an agent/env to start a new session
arkcli +new session <agent-id> --environment-id <env-id> Direct entry point for a new Managed Agent session; always creates a new session first, then REPL / one-shot
arkcli +debug <session-id> Aggregate session, events, resources, and threads for diagnostics
arkcli +export <session-id> Export a diagnostic tar.gz

Complex fields such as Tools、Skills、McpServers、Multiagent、Metadata、Tags support JSON/YAML files, stdin, or structured flags. The request structure aligns with TOP CamelCase; inline objects are compatible with common lower/snake case aliases. A successful creation response must display the server's final identity, model,System, Tools, Skills, MCP, and extended configuration, and must not display only a summary; when the complete result needs to be verified, use agent agent get <agent-id> --format json or --format yaml。

The semantics of Memory get's --view : by default, request by basic and return only metadata and ContentSha256；--view full retain Content. If the server still returns Content under basic, the CLI strips Content at the output layer, but this can only control output and cannot undo network transmission that has already occurred; the server still needs to correctly implement the View parameter to save bandwidth.

Reference