> ## 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

> Register and manage your own agents.

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

## create

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    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](/core-concepts/agents#register-your-own-agent).

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

  <Tab title="Python">
    ```python theme={null}
    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](/core-concepts/agents#register-your-own-agent).

    ```python theme={null}
    agent = await agents().create(
        name="acme-cli",
        install_script="curl -fsSL https://acme.dev/install.sh | sh",
        run_command="acme-cli --headless",
    )
    ```
  </Tab>
</Tabs>

## list, get, upsert, delete

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    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.

    ```ts theme={null}
    await agents().upsert(
      "acme-cli",
      {
        install_script: "curl -fsSL https://acme.dev/install.sh | sh",
        run_command: "acme-cli --headless --v2",
      },
    );
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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.

    ```python theme={null}
    await agents().upsert(
        "acme-cli",
        install_script="curl -fsSL https://acme.dev/install.sh | sh",
        run_command="acme-cli --headless --v2",
    )
    ```
  </Tab>
</Tabs>