> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolvingmachines.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents: methods

> Register, read, replace, and delete custom agents.

Use `agents()` or `hosted().agents` for registered custom agents. Built-in harness capabilities come from [`meta()`](/sdk-reference/methods/meta). Examples use a configured `client`. Python examples run inside an async function.

## create

Register a custom agent from an install script or local directory.

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const agent = await client.create({
    name: "my-agent",
    directory: "./agent-source",
    run_command: "my-agent --headless",
  });
  ```

  ```python Python theme={"dark"}
  agent = await client.create(
      name="my-agent",
      directory="./agent-source",
      run_command="my-agent --headless",
  )
  ```
</CodeGroup>

**Returns:** `Agent`. See [agent fields](#agent-fields).

<Accordion title="Parameters and behavior">
  | Parameter                       | Type and meaning                                                                                  |
  | ------------------------------- | ------------------------------------------------------------------------------------------------- |
  | `name`                          | Required string. Read naming rules and reserved names from `meta().agent_registration`.           |
  | `install_script` or `directory` | Exactly one. Script is its text, not a path. Directory is packed and uploaded.                    |
  | `run_command`                   | Required command string, run headlessly with `sh -c` in the task working directory.               |
  | `env?`                          | String-to-string map. Injected at run time; platform-owned environment keys are refused.          |
  | `org?`                          | Organization slug or id. Overrides client default, then falls back to your personal organization. |

  The build has internet access but no secrets. Its dependencies must be publicly fetchable, and installation must leave executables under `$PREFIX/bin`. Read [custom agents](/core-concepts/agents) for the run contract.
</Accordion>

## list

Browse registered agents visible in the chosen scope.

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const page = await client.list({
    scope: "org",
    limit: 20,
  });
  ```

  ```python Python theme={"dark"}
  page = await client.list(
      scope="org",
      limit=20,
  )
  ```
</CodeGroup>

**Returns:** `AgentPage` when awaited; an `Agent` per iteration.

<Accordion title="Parameters and behavior">
  | Parameter           | Type and meaning                                                                                                                                      |
  | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `scope?`            | `my` (default): yours. `shared`: other members’ registrations in your organizations. `org`: all registrations in your organizations, including yours. |
  | `limit?`, `cursor?` | Collection pagination; default 50, maximum 200. Await one page or use `for await` / `async for`.                                                      |

  Page fields are `items`, `nextCursor`, `hasMore` in TypeScript; `items`, `next_cursor`, `has_more` in Python.
</Accordion>

## get

Read a registered agent by name.

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const agent = await client.get("my-agent");
  ```

  ```python Python theme={"dark"}
  agent = await client.get("my-agent")
  ```
</CodeGroup>

**Returns:** `Agent`.

<Accordion title="Parameters and behavior">
  `name` is a required string. This reads registered agents; use `meta()` to discover built-in harnesses.
</Accordion>

## upsert

Create or fully replace the registration under a name.

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  const agent = await client.upsert("my-agent", {
    directory: "./agent-source",
    run_command: "my-agent --headless",
    env: { AGENT_MODE: "eval" },
  });
  ```

  ```python Python theme={"dark"}
  agent = await client.upsert(
      "my-agent",
      directory="./agent-source",
      run_command="my-agent --headless",
      env={"AGENT_MODE": "eval"},
  )
  ```
</CodeGroup>

**Returns:** `Agent` after replacement.

<Accordion title="Parameters and behavior">
  The first argument is the required name. Remaining fields match [`create`](#create), except `name` is not repeated in the TypeScript input.

  This replaces the entire registration: omitting `env` clears it. The owning organization cannot change. Existing registrations can be updated without a delete-and-create gap.
</Accordion>

## delete

Remove a registered agent.

<CodeGroup>
  ```ts TypeScript theme={"dark"}
  await client.delete("my-agent");
  ```

  ```python Python theme={"dark"}
  await client.delete("my-agent")
  ```
</CodeGroup>

**Returns:** No value (`void` / `None`).

<Accordion title="Parameters and behavior">
  `name` is required. Past jobs retain their recorded agent identity.
</Accordion>

## Agent fields

<Accordion title="Agent response">
  Both SDKs use the same fields; Python returns an `Agent` dataclass. `source` identifies how it was registered. The response does not contain the install script or source archive.

  ```ts Fields theme={"dark"}
  interface Agent {
    name: string;
    org: string | null;
    source: AgentSource;
    run_command: string;
    env: Record<string, string>;
    created_at: string;
    updated_at: string;
  }

  type AgentSource = "install_script" | "tarball";
  ```
</Accordion>