Agents

Manage AI agents in this org from the command line — their identity (name, description, instructions, model, creativity, reasoning), their attachments (tools, knowledge bases, linked sub-agents), and a YAML round-trip for version-controlling agent definitions. The models group sits alongside to discover the model codes that feed --model on agents create / agents update.

All commands run against the org and credentials resolved from the environment (HUTLY_ORG_ID, HUTLY_API_KEY) or .hutlyrc.yaml — see the CLI configuration reference. Access is enforced server-side by the calling key’s org role: read verbs return only the agents the authenticated user can see, and write verbs (create, update, delete, push, and every attach / detach) are rejected by the API if the key lacks the required role in this org. On any API error the command prints the message and exits non-zero (exit code 1).

Most read commands emit JSON by default. --json is accepted everywhere as a no-op for scripting compatibility; --pretty indents the JSON for human reading.

Agent commands

list

List agents the authenticated user can access, with pagination and an optional search query.

# First page (default 100)
hutly agents list

# Search by name or description
hutly agents list --query "deposit"

# Page through results
hutly agents list --limit 25 --cursor 25 --pretty

Output is a pagination envelope (items, totalRows, cursor) over the matching agents.

get

Fetch one agent and all of its attachments — tools, knowledge bases, and linked sub-agents — in a single payload.

hutly agents get 467c7151-c84b-4d80-8320-0b55f7961337 --pretty

Returns { agent, tools, knowledgeBases, linkedAgents }. This is the full-detail view, including instructions and emailFilters.

describe

Show an agent’s metadata without the large body fields (instructions, emailFilters). Use get when you need the full detail.

hutly agents describe 467c7151-c84b-4d80-8320-0b55f7961337 --pretty

create

Create a new agent. --name, --description, --instructions, and --model are required; the rest are optional.

hutly agents create \
  --name "Deposit Parser" \
  --description "Extracts structured data from deposit evidence documents" \
  --instructions "You are a document parsing agent. Your sole job is to extract..." \
  --model claude-sonnet-4.6 \
  --creativity 0.4 \
  --reasoning medium

--creativity outside 0–1 and --reasoning outside the four allowed values are rejected before any request is sent. On success the command prints the created agent’s name and id.

update

Update one or more fields on an existing agent. Only the flags you pass are changed — the command fetches the current agent and overlays your flags, so a single-field update never resets the rest. Passing no field flags exits non-zero with an error.

# Swap the model and bump reasoning
hutly agents update 467c7151-c84b-4d80-8320-0b55f7961337 \
  --model claude-opus-4.7 \
  --reasoning high

# Rename only
hutly agents update 467c7151-c84b-4d80-8320-0b55f7961337 --name "Deposit Parser v2"

Accepts the same field flags as create: --name, --description, --instructions, --model, --creativity, --reasoning, --email-address, --email-filters. The --creativity and --reasoning validations apply identically.

delete

Permanently delete an agent and all of its attachments. This also removes the agent’s conversations and is not reversible.

hutly agents delete 467c7151-c84b-4d80-8320-0b55f7961337
hutly agents delete 467c7151-c84b-4d80-8320-0b55f7961337 --yes

Without -y, the command prompts for confirmation and prints Cancelled. if declined.

push

Create or update an agent from a YAML file. Idempotent on the file’s agentId: if the YAML already carries an agentId for this org, the agent is updated; otherwise a new agent is created and the id is written back into the file. Variables (!sub) and !include directives in the file are resolved before the request.

# Create-or-update from a tracked definition
hutly agents push ./workflows/realflow/credit-assessment/agents/parse-deposit-agent.yaml

# Force a brand-new agent regardless of any existing agentId
hutly agents push ./agents/deposit-parser.yaml --force-new

# Resolve a templated variable
hutly agents push ./agents/deposit-parser.yaml --var environment=production

When a new agent is created, the command rewrites the source file with the assigned id under an !org_map (keyed by org) — commit that change so subsequent pushes update in place.

pull

Fetch an agent and write its full definition — including all tool, knowledge-base, and linked-agent attachments — to a YAML file. This is the inverse of push; together they form the round-trip for version-controlling agents.

# Writes ./agent-<agentId>.yaml
hutly agents pull 467c7151-c84b-4d80-8320-0b55f7961337

# Custom output path (parent dirs are created)
hutly agents pull 467c7151-c84b-4d80-8320-0b55f7961337 \
  -o ./workflows/realflow/credit-assessment/agents/parse-deposit-agent.yaml

On pull, the agent’s own agentId is written as an !org_map (org → id), and attached knowledge-base and linked-agent ids are emitted as relative !ref paths where resolvable, so the definition rebinds to fresh ids when pushed into a different org rather than pointing back at the source org.

Agent YAML shape

A pulled agent looks like the following. push consumes this same shape; agentId is stripped before the create/update request.

organizationId: cc19d774-06b8-4e01-8d04-193e093973ad
agentId: !org_map
  cc19d774-06b8-4e01-8d04-193e093973ad: 467c7151-c84b-4d80-8320-0b55f7961337
name: Deposit Parser
description: Extracts structured data from deposit evidence documents.
instructions: >-
  # Deposit Evidence Parsing Agent — Instructions

  You are a document parsing agent. Your sole job is to extract structured
  data from a Deposit Evidence document.
model: claude-sonnet-4.6
creativityScore: "0.4"
reasoning: medium
emailAddress: null
emailFilters: null
# Attachment arrays are emitted only when present
tools:
  - toolCode: skills
    configuration: {}
knowledgeBases:
  - knowledgeBaseId: !ref ../knowledge-bases/legislation.yaml
linkedAgents:
  - targetAgentId: !ref ./contract-parser-agent.yaml
    instructions: Delegate contract-of-sale extraction to this sub-agent.

creativityScore is a string on the wire (e.g. "0.4"); tools, knowledgeBases, and linkedAgents appear only when the agent has attachments of that kind.

Tool attachments — agents tools

Manage the tools attached to an agent. Skills attach as a tool with toolCode='skills' — see the managing-agents skill for the configuration shape.

tools list

hutly agents tools list 467c7151-c84b-4d80-8320-0b55f7961337 --pretty

tools attach

Attach a tool to an agent, optionally with a JSON configuration object.

# No configuration
hutly agents tools attach 467c7151-c84b-4d80-8320-0b55f7961337 web-search

# Inline JSON config
hutly agents tools attach 467c7151-c84b-4d80-8320-0b55f7961337 skills \
  --config '{"skillCodes":["managing-agents"]}'

# Config from a file
hutly agents tools attach 467c7151-c84b-4d80-8320-0b55f7961337 skills \
  --config-file ./skills-config.json

Pass either --config or --config-file, not both; passing both is an error.

tools update

Replace the configuration of an already-attached tool. Takes the same --config / --config-file options as attach.

hutly agents tools update 467c7151-c84b-4d80-8320-0b55f7961337 skills \
  --config '{"skillCodes":["managing-agents","workflow-builder"]}'

tools detach

hutly agents tools detach 467c7151-c84b-4d80-8320-0b55f7961337 web-search --yes

Knowledge-base attachments — agents kbs

Manage the knowledge bases attached to an agent.

kbs list

hutly agents kbs list 467c7151-c84b-4d80-8320-0b55f7961337 --pretty

kbs attach

Attach a knowledge base by id. When attaching a public KB owned by a different org, supply that owner’s org id with --kb-org.

# A KB in this org
hutly agents kbs attach 467c7151-c84b-4d80-8320-0b55f7961337 a1b2c3d4-...

# A public KB owned by another org
hutly agents kbs attach 467c7151-c84b-4d80-8320-0b55f7961337 a1b2c3d4-... \
  --kb-org 2b8e9f03-e0ca-4efa-8a07-a1a21c762bab

kbs detach

hutly agents kbs detach 467c7151-c84b-4d80-8320-0b55f7961337 a1b2c3d4-... --yes

Linked sub-agents — agents links

Manage delegation links: which other agents this agent can call, and the instructions that tell the parent when to delegate.

links list

hutly agents links list 467c7151-c84b-4d80-8320-0b55f7961337 --pretty

links attach

Link a sub-agent to a parent for delegation.

hutly agents links attach 467c7151-c84b-4d80-8320-0b55f7961337 d8bf0751-... \
  --instructions "Delegate contract-of-sale extraction to this sub-agent."

links update

Update the delegation instructions on an existing link.

hutly agents links update 467c7151-c84b-4d80-8320-0b55f7961337 d8bf0751-... \
  --instructions "Only delegate when the document is a Contract of Sale."

links detach

hutly agents links detach 467c7151-c84b-4d80-8320-0b55f7961337 d8bf0751-... --yes

Models — models

Discover the model codes available to this org. The codes returned here are exactly what --model expects on agents create and agents update.

models list

List available models, sorted by display order. The list is filtered server-side to models marked available for the org.

# All available models
hutly models list

# Only Anthropic models
hutly models list --provider anthropic

# Only models that support a reasoning effort
hutly models list --reasoning-only --pretty

Each entry includes the model code to pass to --model, its provider, and whether reasoningSupported. Use --reasoning-only to find the models for which agents create --reasoning <effort> is meaningful.