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

# Manage Agents

> /v1/agents — create, update, and publish Experts via API

Besides invoking Experts, you can author and maintain your own through the API.

<Note>
  Create and update both leave the agent in **draft**. A draft is invocable by its author only, with no review required — build it, call it, iterate, and publish to the marketplace when you're satisfied.
</Note>

## Create or update a draft

```
POST https://api.profy.cn/v1/agents
```

<ParamField body="name" type="string" required>
  Agent name. Must be unique among your agents.
</ParamField>

<ParamField body="identifier" type="string">
  Agent identifier. Derived from the name when omitted. Passing an existing identifier updates that agent (it must be yours).
</ParamField>

<ParamField body="version" type="string" default="0.1.0">
  Version string.
</ParamField>

<ParamField body="persona" type="string">
  Persona definition (Markdown).
</ParamField>

<ParamField body="soul" type="string">
  Soul content.
</ParamField>

<ParamField body="agent" type="string">
  Agent instruction content.
</ParamField>

<ParamField body="skill" type="string">
  Skill content.
</ParamField>

<ParamField body="opening_message" type="string">
  Opening message.
</ParamField>

<ParamField body="sandbox" type="object">
  Sandbox template; same fields as an [Environment](/en/developers/api/environments) `template`.
</ParamField>

<ParamField body="tools" type="object[]">
  Tool configuration.
</ParamField>

Other optional fields: `description`, `category`, `tags`, `changelog`, `overview`.

```bash curl theme={null}
curl -X POST https://api.profy.cn/v1/agents \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customs Helper",
    "identifier": "customs-helper",
    "persona": "You are a senior customs broker…",
    "sandbox": { "runtime": "python", "dependencies": ["pandas"] }
  }'
```

```json theme={null}
{
  "code": 0,
  "data": {
    "identifier": "customs-helper",
    "version": "0.1.0",
    "status": "pending_review",
    "is_update": false,
    "invocable": true
  }
}
```

The draft is immediately invocable:

```bash curl theme={null}
curl -N -X POST https://api.profy.cn/v1/agents/run \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{"expert_identifier": "customs-helper", "message": "Test run"}'
```

## Update a draft

```
PATCH https://api.profy.cn/v1/agents/{identifier}
```

Send only the fields you want to change; `name` and `version` are carried forward from the current row.

## Publish to the marketplace

```
POST https://api.profy.cn/v1/agents/{identifier}/publish
```

<ParamField body="version" type="string">
  Release version. Defaults to the current version.
</ParamField>

<ParamField body="changelog" type="string">
  Release notes.
</ParamField>

Publication goes through the platform review gate. The API cannot bypass it.

## Other operations

| Method | Path                          | Notes                   |
| ------ | ----------------------------- | ----------------------- |
| `GET`  | `/v1/agents?page=&page_size=` | List agents you created |
| `GET`  | `/v1/agents/{identifier}`     | Detail (creator view)   |

## Errors

| Status | Meaning                                |
| ------ | -------------------------------------- |
| `400`  | Missing `name`                         |
| `401`  | Authentication failed                  |
| `403`  | Not the owner, or creator not approved |
| `404`  | Agent not found                        |
| `409`  | Duplicate agent name                   |

## Next steps

<CardGroup cols={2}>
  <Card title="Sessions" icon="comments" href="/en/developers/api/sessions">
    Create long-lived sessions and append events
  </Card>

  <Card title="Environments" icon="box" href="/en/developers/api/environments">
    Define sandbox runtime and dependencies
  </Card>
</CardGroup>