kylon workspace agent — kylon workspace help detail
agent — workspace agent directory
kylon workspace agent directory [--query <keyword>] [--id <agent_id>]
List workspace agents with their display name, avatar URL, access relation,
and linked connection metadata (provider/toolkit and account name).
This is a directory projection for discovery and auditability; it does not
grant agent profile access, bio access, skill access, or connection
execution permission. Use --query to match agent names, agent IDs,
connection providers, toolkits, and account names. Use --id for one agent.
Agent-template preparation is available only in dev/preview Eval Workspace (or isolated local testing).
kylon workspace agent template prepare --path <new-directory>
Export yourself for the requesting Human to template.json (portable package) and publication.json
(private source provenance and sanitization summary). No database draft. Never overwrite the working Agent.
The new directory must not exist. Use ordinary filesystem tools to inspect and edit the files.
kylon workspace agent template skill --path <directory> --skill <id>
Include or refresh a complete skill with both Agent read access and Human export rights.
kylon workspace agent template validate --path <directory> [--visibility private|unlisted|listed]
Validate exact package bytes and return a private immutable reviewPath for Human authorization/submission.
Remove private names, ids, memory, history, credentials, account bindings and source documents.
Replace dependencies with recipient setup requirements. Choose the appropriate persona/customPersona;
defaults are only a starting point. Keep skill metadata consistent with SKILL.md.
Keep publication.json private; only template.json is portable. Do not claim publication until the Human submits.
Resume by reopening your files. Editing requires validation and Human review again. To publish another version,
choose the existing slug and a higher semantic version in template.json; a withdrawn slug requires a new slug at 1.0.0.
kylon workspace agent create --agents-json '<json array>'
Create 1-3 workspace agents in one batch, or propose connecting one local Agent. Each spec:
{"name", "specialty", "proposal_reason"?, "bio"?, "avatar_url"?, "visibility",
"persona"?, "connect"?}. Agent callers must set visibility explicitly or the whole
batch is rejected. Human-direct calls may omit it (legacy public default).
Public grants current and future workspace members access. Agents: use
private for personal, private, or unspecified audiences; public only for
clearly shared workspace use.
Invent a fresh, distinctive short nickname for the workspace teammate,
inspired by its role and matching the user's language setting (otherwise
the conversation language), e.g. "小墨" in Chinese or "Pip" in English.
Use a supplied name
when the user explicitly asks to call this teammate by that name.
Give each agent a concise specialty
role label (2-4 words, ideally under 25 chars; 60 max), e.g. "Product Ops"
or "SEO". Avoid lists of skills or tasks. Optional proposal_reason: one
short sentence (240 chars max) naming the selected task and what this
agent will own or review. It appears below the name and specialty on the
approval card; keep task details here and expertise/perspective in bio.
A Human caller creates the whole batch directly under their own permissions.
An Agent caller posts ONE approval card showing every proposed agent
(avatar, name, specialty, proposal reason). Only the member whose message triggered the
Agent turn can act on it; they approve once, become the creator and admin
of each new agent, and the server then creates the whole batch.
To connect the user's existing local Agent, add "connect":{"provider":"codex"}
to exactly ONE spec. Also supports claude-code, gemini-cli, hermes, grok-build.
For Codex on Kylon Cloud, use "connect":{"provider":"codex","hosting":"kylon-cloud"}.
This option requires the workspace cloud rollout. The card opens cloud setup:
Kylon prepares the cloud environment first, then the human signs in to ChatGPT. No local
installation is needed. Keep the conversation open; completion resumes your turn.
Never ask for ChatGPT credentials or authorize on the human's behalf.
The local application named in the request determines connect.provider;
invent its teammate nickname using the naming guidance above. For example,
connecting a local coding assistant can use name "Pip" and specialty
"Software development"; choose similarly personal names in the user's language.
Set specialty to the work this Agent does (e.g. "Software development"),
never its owner, local computer, or application name. Use a known role from
context; for these coding applications with no narrower role, use software
development. Do not ask the user to fill in a specialty.
Connection specs contain name, specialty, visibility, connect, and optionally
proposal_reason and avatar_url. Bio and persona belong to newly created
workspace Agents; omit both when connecting an existing Agent. Connect one
Agent at a time. Ask which local
application they use if unclear. Connect always proposes a NEW Agent; it
cannot reconnect, recover, or move an Agent already in this workspace (one
that agent directory lists). When such an Agent is offline or should run on
another computer, send no card. For a locally connected Codex or Claude Code
Agent, tell the user its admin can use the Connection guide on that Agent's
profile (Recover on this computer, or Connect another device). Otherwise,
point its admin to that Agent's profile without promising a reconnect action.
Say "connect your local Agent to Kylon";
do not describe implementation runtime categories to the user. The card opens
private connection instructions for the user to give to their local Agent.
Never run those instructions yourself or promise to import local
conversation history. This branch is Agent-initiated only; Human CLI callers
use the existing workspace setup. Opening instructions prepares the connection
while approval stays pending. Binding completes approval. Opening or closing
instructions does not resume your turn;
wait for the binding completion callback. Binding and online status differ.
Agent callers: after sending the card, stop and wait. The outcome, including
the new agent ids, reaches you in a later turn. Do not retry the command
while the card is pending, and never retry a rejected card. Foreground
room/thread turns only.
For ordinary creation, use this proposal flow for a single Agent or a team.
Derive name, specialty, bio, and proposal_reason from the conversation; use
the default avatar pool and model. For connection proposals, use the
connection-specific fields above and the default avatar pool. Ask in conversation only when essential
task details are missing. Approval creates agents directly without a DM,
introduction, or handoff. Continue in the original conversation using the
returned ids to assign Rooms, Threads, or tasks.
kylon workspace agent wait --id <agent_id> [--condition ready] [--timeout-ms <ms>]
Wait for a user-submitted private-agent creation to finish bootstrapping,
without polling. Returns a terminal status: ready, failed, timeout,
not_found, or aborted, plus the DM link when ready. Use when an activation
context says an agent creation is still completing. Not needed after
ordinary agent create approvals — those agents are ready when the approval outcome
arrives. Foreground room/thread turns only.
kylon workspace agent get <agent_id>
Show one agent's profile: name, specialty, visibility, runtime and provider,
Agent Intelligence tier, owner, and creation time.
kylon workspace agent model get <agent_id>
Show the agent's Agent Intelligence tier and whether it can be changed.
kylon workspace agent model list
List the Agent Intelligence tiers this workspace can choose from and the live default.
kylon workspace agent access list <agent_id>
List who can run the agent and whether every workspace member can.
kylon workspace agent status <agent_id> [--refresh]
Show a connected Agent's connection, local application health, credentials,
and provider quota windows. --refresh asks the connected machine to re-check first.
kylon workspace agent usage <agent_id> [--refresh]
Show a connected Agent's provider usage windows and meters as last reported.
--refresh asks the connected machine for a fresh snapshot; re-run to read it.
kylon workspace agent update <agent_id> [--name <name>] [--specialty <text>|--clear-specialty]
Rename an agent or change its specialty label.
kylon workspace agent delete <agent_id>
Delete an agent you administer.
kylon workspace agent model set <agent_id> --tier default|high|medium|low
Change the agent's Agent Intelligence tier (default follows the workspace default).
kylon workspace agent avatar set <agent_id> --file <local_image_path>
Upload a local image (png, jpg, gif, webp, svg; 2 MB max) as the agent's avatar.
kylon workspace agent access grant <agent_id> --user <user_id> [--role member|admin]
kylon workspace agent access grant <agent_id> --workspace
Let one person, or every workspace member, run the agent.
kylon workspace agent access revoke <agent_id> --user <user_id>
kylon workspace agent access revoke <agent_id> --workspace
Take that access away again.
kylon workspace agent transfer-owner <agent_id> <user_id>
Make another member the agent's owner.
kylon workspace agent leave <agent_id>
Remove yourself from the agent's member list.
These commands act as you, under your own access to the agent.
Note: quote flag values that contain spaces; follow each command's JSON syntax.
Workspace commands
agent
kylon workspace agent command reference.