Agents

Choose your language:

Agents are Mankinds automation units attached to systems.

client.agents.list(filters)

List agents in the authenticated organization.

SDK	client.agents.list(filters=None)
Returns	Agent[]

Parameters:

Location	Parameter	Type	Required	Description
Query	system_id	string	Optional	Restrict agents to one system UUID.
Query	agent_type	string	Optional	Restrict by agent type.
Query	status	string	Optional	Restrict by agent status.

client.agents.get(agentId)

Read one agent by id.

SDK	client.agents.get(agent_id)
Returns	Agent

Parameters:

Location	Parameter	Type	Required	Description
Path	agent_id	string	Required	Agent UUID.

client.agents.run(agentId, params)

Trigger a run for an existing agent.

SDK	client.agents.run(agent_id, params=None, idempotency_key=None)
Returns	AgentRun

Parameters:

Location	Parameter	Type	Required	Default	Description
Path	agent_id	string	Required	—	Agent UUID.
Body	trigger_source	string	Optional	ci	Source label for the run.
Body	trigger_detail	string	Optional	—	Additional trigger detail.
Body	run_mode	string	Optional	—	Requested run mode. The backend resolves it against the agent config.
Body	metadata	dict	Optional	—	Arbitrary metadata stored on the run. The backend adds actor_label.
SDK option	idempotency_key	string	Optional	—	Sent as the Idempotency-Key header.

Notable behavior:

• The agent must belong to the authenticated organization.
• The agent must be in a runnable state.
• If triggerSource resolves to CI, the agent must already have a configured gate.
• The backend returns 409 when the agent already has an active or queued run.
• The backend returns 429 when the agent daily run limit is reached.

Example:

run = client.agents.run(agent["id"], {
  "triggerSource": "release-script",
  "runMode": "offline",
  "metadata": {"environment": "preprod"},
})

client.agents.getRun(agentId, runId)

Read one agent run.

SDK	client.agents.get_run(agent_id, run_id)
Returns	AgentRun

Parameters:

Location	Parameter	Type	Required	Description
Path	agent_id	string	Required	Agent UUID.
Path	run_id	string	Required	Agent run UUID.

client.agents.waitForGate(agentId, runId, options)

SDK helper that polls client.agents.getRun(...) until the run reaches a terminal state, then raises on failed gate decisions.

SDK	client.agents.wait_for_gate(agent_id, run_id, timeout_ms=..., interval_ms=..., on_poll=None)
Returns	AgentRun

Parameters:

Location	Parameter	Type	Required	Default	Description
SDK	agent_id	string	Required	—	Agent UUID.
SDK	run_id	string	Required	—	Agent run UUID.
SDK	timeout_ms	integer	Optional	1800000	Maximum wait time in milliseconds.
SDK	interval_ms	integer	Optional	5000	Poll interval in milliseconds.
SDK	on_poll	callable	Optional	—	Callback called with each run payload.

Raises:

Error	When
GateFailedError	The run completed and results.gate.passed or summary.gate.passed is false.
JobFailedError	The run terminal status is failed, canceled or timed out.
PollTimeoutError	The timeout is reached before a terminal state.