> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kylon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# agent

> `kylon workspace agent` command reference.

```text theme={null}
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.
    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. 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.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.