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

# Create an agent

> You create an agent from the Agents page or with pinework agent create, then set its model, access mode and instructions before you hand it work.

An **agent** is a named teammate in your workspace that runs on a model and follows your instructions. This guide creates one and sets its model, access mode and instructions.

## Before you start

* You have a Pinework workspace and can sign in to the dashboard.
* For the CLI tab, you have run `pinework login`.
* The agent can run somewhere. That means a Mac with a signed-in harness such as Claude Code, or a provider key for cloud runs. See [Add a provider key or subscription](/guides/add-a-provider-key).

## Create the agent

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open the new agent form">
        Click **Agents** in the sidebar, then click **New agent**. The **New agent** page opens.
      </Step>

      <Step title="Fill in the identity">
        Under **Identity**, type a **Name** and pick a **Role**. Both are required. **Reports to** is optional.
      </Step>

      <Step title="Pick where it runs">
        Under **Execution**, pick a **Harness**: Claude, OpenCode, Cursor or Codex. Then pick **Device** or **Cloud**. **Device** runs on your own computer with your local CLI. **Cloud** runs in Pinework's cloud sandbox.
      </Step>

      <Step title="Describe what it is for">
        Write a **Description**. You and Pinework read it to pick an agent for a piece of work. It gives the agent no extra access.
      </Step>

      <Step title="Hire it">
        Click **Hire agent**. You see an "Agent created" toast. The agent's page opens on the **Configure** view.
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Create the agent">
        `--name` is required. `--role` defaults to `agent`.

        ```bash theme={null}
        pinework agent create \
          --name "Release Notes" \
          --role engineer \
          --description "Writes release notes from merged pull requests." \
          --harness claude \
          --environment cloud
        ```

        The command prints the new agent as JSON. Copy its `id` for the next steps. An audit of the name, role and description follows on stderr.
      </Step>

      <Step title="Confirm it exists">
        ```bash theme={null}
        pinework agent get <agent-id>
        ```

        The output shows the agent's name, role and handle.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Set the model

A model set on the task, the conversation or the routine wins first. Next comes the model you set on the agent. Without one, the agent uses the workspace **Default model**. With no default, Pinework picks the best ready route. A Cursor or Codex agent skips both steps. Without its own model, it runs on that harness's own default model.

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open the model picker">
        On the agent's **Configure** view, find the **Runtime** section. Click the control on the **Model** row, then open **Model**.
      </Step>

      <Step title="Pick a model">
        Search with **Search models...** and click a model. Each model shows how it will run, such as "via Claude Code · Subscription". The **Effort** row sets how hard the model thinks.
      </Step>

      <Step title="Save">
        Click **Save changes** in the bar at the bottom. You see "Saved just now" next to the view switcher.
      </Step>
    </Steps>

    **Fallback model** on the same section names a second model. Leave it on **Workspace default** if you have no preference.
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Find a model id">
        ```bash theme={null}
        pinework models list --provider anthropic
        ```

        The list shows every model id the agent accepts.
      </Step>

      <Step title="Set the model">
        ```bash theme={null}
        pinework agent config set <agent-id> --model claude-sonnet-5-5 --reasoning-effort medium
        ```

        The command prints the saved configuration. Pass `--model null` to clear the agent's own model.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Choose the access mode

The **access mode** says how a run pays the model vendor. It is `subscription` (shown as **Subscription**) or `byok` (shown as **API key**). You do not type it in. Pinework picks it at the start of each run from what you have connected.

* On a device, a harness signed in on that computer goes first. It counts as a subscription.
* Among the credentials saved in Pinework, a subscription goes before an API key.
* A saved subscription serves only agents owned by the person who saved it. You own the agents you create.
* An API key serves every agent in the workspace.

To steer the choice, open the model picker. When a model has more than one route, click the icon stack at the end of its row. The list shows each route, such as "Claude Code · Subscription" or "Claude Code · API key". Click a ready route to pin its harness. The access mode still follows the order above. A route that is not ready shows its state, such as "Add API key".

To connect a key or a subscription, see [Add a provider key or subscription](/guides/add-a-provider-key).

## Write the instructions

An **instruction** is the agent's standing guidance. It reaches the agent at the start of every run. Each agent has one instructions file, `AGENT.md`, plus any number of named rules.

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open AGENT.md">
        In the **Instructions** section, click the **AGENT.md** row. The **Instructions** dialog opens.
      </Step>

      <Step title="Write it">
        Write it the way you would brief a new teammate. Click **Done**, then click **Save changes**. The row shows the first line of what you wrote and its token count.
      </Step>

      <Step title="Add a rule (optional)">
        Click **New rule**. Type a **Name**, such as `never-force-push`, and the **Rule** text. Click **Save**. The rule appears under the agent's own rules.
      </Step>
    </Steps>

    **Workspace rules** in the same section apply to every agent. To turn one off for this agent, open its menu and click **Disable for this agent**.
  </Tab>

  <Tab title="CLI">
    <Steps>
      <Step title="Upload AGENT.md">
        Write the file locally, then upload it.

        ```bash theme={null}
        pinework agent update <agent-id> --agent-md ./AGENT.md
        ```
      </Step>

      <Step title="Add a rule (optional)">
        ```bash theme={null}
        pinework agent rule set <agent-id> never-force-push \
          --content "Never force-push to main. Open a pull request instead."
        ```
      </Step>

      <Step title="Check what the agent receives">
        ```bash theme={null}
        pinework agent identity <agent-id>
        ```

        The command prints `AGENT.md` and each rule as markdown. Token counts go to stderr.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Troubleshooting

**The model control reads "No model on the agent, no workspace default, and no ready route."** A Cursor or Codex agent shows this hint whenever it has no model of its own. It still runs on the harness's default model. On any other agent, nothing can run it yet. Connect a provider key or subscription, or sign in to a harness on your Mac.

**A model shows "Add API key → set up" or "Add subscription → set up".** The vendor has no credential that this agent can use. Add one on the **Providers** settings page, then pick the model again.

<CardGroup cols={2}>
  <Card title="Assign a task" href="/guides/assign-a-task">
    Hand your new agent its first piece of work.
  </Card>

  <Card title="Rules and instructions" href="/concepts/rules-and-instructions">
    How workspace, project and agent rules combine.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.