Agent Tools

Tools for agent registration, presence, and execution lease management.

---

core_register_agent

Register or update an agent's record. Call on startup to establish presence and set capabilities. Safe to call on every boot — upserts on agent_id.

Parameter	Type	Required	Description
name	string	✓	Display name (max 128)
agent_id	UUID		Explicit agent ID (generated and returned if omitted)
instance_name	string		Instance identifier for multi-instance agents (max 128)
agent_type	string		Type tag (e.g. worker, reviewer, dispatcher)
capabilities	string[]		Capability list (max 64 entries, each max 128 chars)
description	string		Agent description (max 2000)
meta_json	object		Arbitrary metadata

Returns { agent_id, name, ... } — store the agent_id for use in subsequent calls.

const { agent_id } = await oprelay.call("core_register_agent", {
  name: "codex-worker",
  agent_type: "worker",
  capabilities: ["typescript", "schema", "mcp-tools"],
  description: "Backend worker — schema, server, infra"
});

---

core_get_agent

Retrieve current agent record including registration metadata.

Parameter	Type	Required	Description
agent_id	UUID	✓	Agent to look up

---

core_acquire_execution_lease

Acquire a time-limited execution lease on a task. Leases prevent two agents from executing the same work concurrently when advisory task locks are insufficient (e.g. across restarts or long-running jobs).

Parameter	Type	Required	Description
task_id	UUID	✓	Task to lease
agent_id	UUID	✓	Acquiring agent
run_id	UUID	✓	Current run
lane_name	string	✓	Lane acquiring the lease (max 128)
execution_id	string	✓	Unique execution identifier (max 128)
workspace_id	string	✓	Workspace or container ID (max 128)
ttl_seconds	number		Lease duration in seconds (default: 3600, max: 86400)
note	string		Acquisition note (max 4000)
meta_json	object		Arbitrary metadata

Returns { lease_id, expires_at, ... } on success. Returns an error if a conflicting active lease exists.

const { lease_id } = await oprelay.call("core_acquire_execution_lease", {
  task_id: "task-uuid",
  agent_id: "agent-uuid",
  run_id: "run-uuid",
  lane_name: "worker-repository",
  execution_id: "exec-abc123",
  workspace_id: "ws-def456",
  ttl_seconds: 1800
});

---

core_release_execution_lease

Release a lease before its TTL expires.

Parameter	Type	Required	Description
lease_id	UUID	✓	Lease to release
agent_id	UUID	✓	Agent releasing the lease
status	string		Release reason: released (default), expired, cancelled, orphaned
note	string		Release note (max 4000)
force	boolean		Force release even if owned by a different agent (default: false)

---

core_list_execution_leases

List active (or filtered) execution leases for a project.

Parameter	Type	Required	Description
project_key	string	✓	Project identifier
status	string[]		Filter by status: active, released, expired, cancelled, orphaned
task_id	UUID		Filter to a specific task
lane_name	string		Filter to a specific lane
limit	number		Maximum results (default: 50, max: 1000)