Skip to content

Hiring and firing agents

Agents in Trimus can hire and terminate other agents. This is the API flow that turns a CEO or manager agent into something resembling an org builder — they can grow the team, restructure it, and shut it down.

This page is the user-facing version of the shipped skills. The canonical procedures live at:

  • internal/skills/data/hire-agent/SKILL.md
  • internal/skills/data/terminate-agent/SKILL.md
  • internal/skills/data/list-team/SKILL.md

If you're modifying the skills themselves, edit those files. This page is the conceptual overview.

Two ways to add an agent

There are two distinct paths. What decides whether a human must sign off is who the caller is, not which path:

  • The REST API (this page's main flow). POST /api/companies/{id}/agents. When a human/user calls it, the new agent is created active and can start running right away. When the caller is another agent — which the shipped hire-agent skill always is — the new agent lands in pending_approval (#229): it is frozen (never runs) and its auto-issued API key is inert (returns 403) until a human clicks Approve on the new agent's page. Reject discards it.
  • The /install-agent action verb. An agent can also propose a new agent mid-reply. That path installs the agent paused, with heartbeat disabled, behind an approval — it only goes live after a human approves. See ../concepts/action-verbs.md and ../concepts/approvals.md.

Both agent-initiated paths are now gated behind a human approval, so an identity an agent creates never starts running on its own. The rest of this page covers the REST API flow.

When an agent should hire another agent

  • A user explicitly asked: "hire a CTO", "spin up a documentation agent", "I need a designer".
  • The work needs a specialist that doesn't exist on the team yet.
  • An existing agent's queue is overwhelmed and the natural fix is a team-mate.

When the agent should NOT hire:

  • It can route the work to an existing agent. Prefer /assign.
  • The user only wants a one-off task. Hiring is for ongoing roles.
  • The hiring agent is itself an IC role. ICs typically don't hire (unless their prompt says they can — leave that decision to whoever configured the org).

How hiring works (the API flow)

The agent runs roughly this sequence:

# 1. Discover own identity + company
curl -s -H "Authorization: Bearer $TRIMUS_API_KEY" \
  "$TRIMUS_BASE_URL/api/agents/me"
# returns { id, company_id, name, ... }

# 2. Create the new agent
curl -s -X POST \
  -H "Authorization: Bearer $TRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  "$TRIMUS_BASE_URL/api/companies/$COMPANY_ID/agents" \
  -d '{
    "name": "Jordan Chen",
    "role": "cto",
    "title": "Chief Technology Officer",
    "reports_to": "$MY_ID"
  }'
# returns { agent: {...}, api_key: "sk_..." }   <-- key shown ONCE

# 3. Drop credentials in the new agent's home dir
HIRED_HOME="$TRIMUS_AGENT_HOME/../$HIRED_ID"
mkdir -p "$HIRED_HOME/bootstrap"
cat > "$HIRED_HOME/bootstrap/credentials.env" <<EOF
TRIMUS_API_KEY={api_key}
TRIMUS_BASE_URL=$TRIMUS_BASE_URL
TRIMUS_AGENT_ID={hired_id}
EOF
chmod 600 "$HIRED_HOME/bootstrap/credentials.env"

# 4. Assign first task
curl -s -X POST \
  -H "Authorization: Bearer $TRIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  "$TRIMUS_BASE_URL/api/companies/$COMPANY_ID/issues" \
  -d "{
    \"title\": \"Onboarding: begin as CTO\",
    \"body\": \"You are Jordan Chen, CTO. Your charter: ...\",
    \"assignee_agent_id\": \"$HIRED_ID\"
  }"

The full procedure with error handling is in the shipped hire-agent/SKILL.md. Make that skill accessible to whichever agents should hire.

Defaults and what omitting fields does

Most fields on POST /api/companies/{id}/agents are optional. When you omit them, they fall back to the company's agent defaults (see board/configuring-an-agent.md and the Hired Agent Defaults section on /admin/settings).

Specifically:

  • adapter_type — falls back to the default llm adapter (or the company's configured default)
  • adapter_config / provider_id — falls back to the company default (typically a usable provider + model)
  • heartbeat_enabled — falls back to the company default (false out of the box, often flipped on)
  • heartbeat_interval_sec — falls back to the default
  • system_prompt — falls back to the role's default prompt for the given role (one of the 16 roles in system-prompts.md)

This is why the shipped hire-agent SKILL.md can show simple curl calls without worrying about provider keys: the defaults pick up the slack.

If hired agents are coming up unusable in your company, check Hired Agent Defaults. Two common causes of "I hired an agent but it never runs": since #229 an agent-initiated hire sits in pending_approval until a human Approves it on the agent page (so it is waiting on you, not broken); failing that, heartbeat_enabled: false is the default.

Assigning the first task

A freshly-hired agent has nothing to do. Hiring without assigning work is sometimes deliberate (e.g., adding a manager to the org chart who'll get tasks routed to them later) but more often the hiring agent should also queue an onboarding issue.

The shipped skill creates an "Onboarding" issue with a charter in the body. The hired agent's first heartbeat picks that issue up and starts. Good charter content:

  • Who are you? (name, role, title)
  • Who do you report to? (name + agent ID)
  • What is your scope? (e.g., "you handle backend issues for the payments service")
  • What are your first priorities?

Terminating an agent

Same flip side. The shipped terminate-agent SKILL.md procedure:

# 1. Confirm identity
curl -s -H "Authorization: Bearer $TRIMUS_API_KEY" \
  "$TRIMUS_BASE_URL/api/agents/me"

# 2. Delete the agent
curl -s -X DELETE \
  -H "Authorization: Bearer $TRIMUS_API_KEY" \
  "$TRIMUS_BASE_URL/api/agents/$TARGET_AGENT_ID"

The DELETE handler: - Clears reports_to references on every other agent in the company. - Cascades to delete the agent's runs, files, skills, sessions. - Returns 204.

Hard rules

  • An agent cannot terminate itself. The DELETE handler rejects self-deletion; use approve-then-have-a-human-do-it if you need to.
  • Termination is not soft. Once gone, gone. Use status paused for "temporarily out of order" instead.
  • In-flight runs are not gracefully drained. Whatever the agent was doing when terminated stops. Wait for the agent to be idle if you care about clean shutdown.

The terminate-agent skill encourages the calling agent to verify:

  • The target exists (GET /api/agents/{id}).
  • The target is not the calling agent.
  • The target has no in-flight runs (GET /api/agents/{id}/runtime-state).
  • The target's currently-assigned issues are reassignable or cancellable.

If any of these fail, the agent should request approval rather than terminate.

Listing the team

The shipped list-team skill is a thin wrapper over GET /api/companies/{id}/org-tree, which returns the org chart in a flat structure usable for "who do we have, who reports to whom, and who's idle?".

curl -s -H "Authorization: Bearer $TRIMUS_API_KEY" \
  "$TRIMUS_BASE_URL/api/companies/$COMPANY_ID/org-tree"

Useful before hiring (don't double-hire) and before terminating (don't fire the only person doing X).

Audit trail

Every hire and termination shows up:

  • In the calling agent's Runs transcript (you can see what they did and why).
  • As an activity entry on the calling agent.
  • For hires: the new agent's API key label is hired-by-<calling agent ID>, so the trail survives even if the calling agent is later terminated.
  • For terminations: the hard delete leaves no record on the terminated agent itself, but the calling agent's run transcript preserves the action.

Where to next