Agents HTTP API

Register an Evolve agent when your evaluation needs your own executable or installation script. Built-in harnesses are listed by GET /api/meta; they do not need registration. Examples reuse API and EVOLVE_API_KEY from connection setup. Save your installer as install.sh before sending this request:

curl -sS "$API/api/agents" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -F 'name=my-agent' \
  -F 'run_command=my-agent' \
  -F 'install_script=<install.sh'

Success returns 201 with an Agent. Use its name as a job arm’s name, alongside a required model_name.

Routes

Method and path	Input	Success
`POST /api/agents`	Multipart registration below	`201 Agent`
`GET /api/agents`	Optional `scope`, `limit`, `cursor`	`200 AgentPage`
`GET /api/agents/{name}`	Registered name	`200 Agent`
`PUT /api/agents/{name}`	Multipart replacement below; name comes from the URL	`201 Agent` when created; `200 Agent` when replaced
`DELETE /api/agents/{name}`	Registered name	`204`, no body

scope is my (default), shared, or org. See pagination and agent methods for field-level results and SDK equivalents.

Registration fields

Multipart field	Required	Meaning
`name`	POST only	Registration name; PUT takes its name from the URL and ignores a multipart `name`
`run_command`	Yes	Command used to run the agent
`install_script`	One source	Script text, not a path on your computer
`archive`	One source	Gzipped tarball of the agent directory
`org`	No	Owning organization slug or id; defaults to personal on creation; replacement preserves the existing organization and refuses a different one
`env`	No	JSON object of string values encoded as a multipart text field

Provide exactly one of install_script or archive. Registration validates the input without running the installer. The first trial that names the agent builds it with internet access and no secrets; install executables under $PREFIX/bin. Read custom agent packaging before creating the installer. To read the registration:

curl -sS "$API/api/agents/my-agent" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

To create or replace it by name, reuse the registration request with -X PUT and /api/agents/my-agent, omitting the multipart name. PUT fully replaces the command, source, and environment; an omitted env becomes empty. It returns 201 with a Location header for a new registration, or 200 for a replacement. Only the owner can edit or delete a registration. Members of its organization can read it and select it in a job. To remove it:

curl -sS -X DELETE "$API/api/agents/my-agent" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

Errors

Malformed registration fields or an invalid archive refuse registration. An installer failure instead settles the first trial as an infrastructure error, with builder output in its stdout/stderr artifacts. Creating an existing name returns 409 agent_name_taken; use PUT for an intended replacement. A missing registration returns 404 agent_not_found. See registered-agent error codes.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Agents HTTP API

Routes

Registration fields

Errors