agents - Evolve

agents() returns the registered-agents client. A registered agent’s name works in a job’s agents[].name like a built-in.

create

TypeScript
Python

create(input: { name: string; run_command: string; env?: Record<string, string> } & ({ install_script: string } | { directory: string })): Promise<Agent>

Register an agent from an install script’s text, or from a local directory. run_command runs with sh -c at the task’s working directory; what it can rely on, and the registration limit, are on agents.

const agent = await agents().create({
  name: "acme-cli",
  install_script: "curl -fsSL https://acme.dev/install.sh | sh",
  run_command: "acme-cli --headless",
});

async def create(
    *,
    name: str,
    install_script: Optional[str] = None,
    directory: Optional[str] = None,
    run_command: str,
    env: Optional[Dict[str, str]] = None,
) -> Agent

Register an agent from an install script’s text, or from a local directory. run_command runs with sh -c at the task’s working directory; what it can rely on, and the registration limit, are on agents.

agent = await agents().create(
    name="acme-cli",
    install_script="curl -fsSL https://acme.dev/install.sh | sh",
    run_command="acme-cli --headless",
)

list, get, upsert, delete

TypeScript
Python

list(options?: { limit?: number; cursor?: string }): AgentList
get(name: string): Promise<Agent>
upsert(
  name: string,
  input: { run_command: string; env?: Record<string, string> } & ({ install_script: string } | { directory: string }),
): Promise<Agent>
delete(name: string): Promise<void>

Your agents, one agent, replace one without a gap, or delete one. Past jobs keep the agent they recorded. upsert creates when the name is free and replaces when it is not, consuming no new slot; it is a full replacement, so an omitted env becomes empty.

await agents().upsert(
  "acme-cli",
  {
    install_script: "curl -fsSL https://acme.dev/install.sh | sh",
    run_command: "acme-cli --headless --v2",
  },
);

def list(
    *,
    limit: Optional[int] = None,
    cursor: Optional[str] = None,
)
async def get(name: str) -> Agent
async def upsert(
    name: str,
    *,
    run_command: str,
    install_script: Optional[str] = None,
    directory: Optional[str] = None,
    env: Optional[Dict[str, str]] = None,
) -> Agent
async def delete(name: str) -> None

Your agents, one agent, replace one without a gap, or delete one. Past jobs keep the agent they recorded. upsert creates when the name is free and replaces when it is not, consuming no new slot; it is a full replacement, so an omitted env becomes empty.

await agents().upsert(
    "acme-cli",
    install_script="curl -fsSL https://acme.dev/install.sh | sh",
    run_command="acme-cli --headless --v2",
)

⌘I