---
name: seren-agent
description: "Deploy and manage hosted prompt-based agents through the seren-agent publisher."
---

# Seren Agent

Use this skill when a user wants to deploy or manage hosted prompt-based agents in Seren-managed runtime.

## API

Use this skill alongside the core Seren API skill (`https://api.serendb.com/skill.md`).

## Base Route

All routes go through `https://api.serendb.com/publishers/seren-agent`.

## Authentication

All endpoints require `Authorization: Bearer $SEREN_API_KEY`.

## Credential Secrets

Managed-agent deployments declare reusable credentials in the `credentials` array. Prefer `seren-secrets://{vault-uuid}/{item-uuid}/{field}` for credentials already held in Seren Passwords: `binding: reference_env` places only the opaque reference in the tool process environment, while `binding: proxy_inject` lets the secrets gateway resolve and inject the value at egress. Plaintext is materialized only at the gateway injection boundary.

The supported reference schemes are:

- `seren-secrets://{vault-uuid}/{item-uuid}/{field}` for vault-held, end-to-end encrypted credentials.
- `control-plane://providers/{id-or-slug}` for provider credentials managed by the control plane.
- `org-secret://{key}` for reusable organization credential-secret records.
- `user-secret://{key}` for reusable user-owned credential-secret records.

Before using `seren-secrets://`, create the managed Employee, then attach vault-backed credentials from the Employees UI after the required principals approve a Passwords policy result bound to the active deployment revision, Employee identity, and exact environment mapping. The update request carries `agent_identity_id`, `secret_resolution_result_id`, and `expected_active_revision_id` as top-level fields alongside `credentials`; do not nest them under `managed_agent`. The deployment also needs an active `secrets_gateway` resolver. Every new revision with Seren Secrets references requires a fresh approved result.

For `header` and `body` bindings, set `publisher_slug` to the exact publisher that may receive the credential. An unscoped header or body credential is accepted only when the deployment declares exactly one publisher tool reference. Multiple credentials may use the same header name for different publishers, but duplicate bindings for the same publisher and target are rejected.

Create and manage `org-secret://` and `user-secret://` records through the core organization API at `/organizations/{organization_id}/agent-credential-secrets`; keep deployment and update calls on `/publishers/seren-agent/*`.

## Examples

Start with `research_monitor` for read-oriented agents and `workflow_agent` for action-oriented flows. Use `tool_presets`, `approval_policy`, and `allowed_remote_agent_origins` to shape what the agent can actually do.

Deploy a BTC watcher:

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/deploy" \
    -H "Authorization: Bearer $SEREN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "BTC Watcher",
    "mode": "always_on",
    "template": "research_monitor",
    "tool_presets": ["live_data", "database"],
    "approval_policy": "read_only",
    "model_policy": "balanced",
    "workload": {
        "execution": {
            "type": "llm",
            "adapter": "seren_agent",
            "model_id": "gpt-5",
            "bundle": {
                "instructions": [{
                    "kind": "user",
                    "content": "Track BTC/USD, use Seren publishers first, and return a concise market summary."
                }]
            }
        }
    }
    }'
```

Deploy a scheduled market brief:

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/deploy" \
    -H "Authorization: Bearer $SEREN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "Daily Market Brief",
    "mode": "cron",
    "cron_schedule": "0 13 * * 1-5",
    "cron_timezone": "UTC",
    "template": "research_monitor",
    "tool_presets": ["live_data"],
    "approval_policy": "read_only",
    "model_policy": "deep",
    "workload": {
        "execution": {
            "type": "llm",
            "adapter": "seren_agent",
            "model_id": "gpt-5",
            "bundle": {
                "instructions": [{
                    "kind": "user",
                    "content": "Summarize the latest market moves and noteworthy publisher signals for today."
                }]
            }
        }
    }
    }'
```

Deploy an ops router with remote delegation:

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/deploy" \
    -H "Authorization: Bearer $SEREN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "Ops Router",
    "mode": "always_on",
    "template": "workflow_agent",
    "tool_presets": ["live_data", "publisher_actions"],
    "approval_policy": "allow_mutations",
    "model_policy": "balanced",
    "allowed_remote_agent_origins": [
        "https://agents.seren.ai",
        "agents.internal"
    ],
    "workload": {
        "execution": {
            "type": "llm",
            "adapter": "seren_agent",
            "model_id": "gpt-5",
            "bundle": {
                "instructions": [{
                    "kind": "user",
                    "content": "Triage requests, use Seren publishers first, and delegate to approved remote agents when needed."
                }]
            }
        }
    }
    }'
```

## Capabilities

Inspect available orchestration/runtime capabilities before deployment.

Inspect available orchestration features and runtime limits.

### GET `/publishers/seren-agent/capabilities`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-agent/capabilities" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

## Deployments

Create managed seren-agent deployments and list their runtime records.

Create or update an orchestrated deployment (forwarded to seren-cloud).

### POST `/publishers/seren-agent/deploy`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/deploy" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"","workload":{"compute_backend":null,"config":{},"execution":null}}'
```

List orchestrated deployments and their runtime metadata.

### GET `/publishers/seren-agent/deployments`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-agent/deployments" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

## Draft Test Runs

Preview an unsaved managed agent once before deploying it. This is best for prompt and capability checks before you commit a real deployment.

Run an unsaved managed seren-agent draft once before deploying.

### POST `/publishers/seren-agent/test-run`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/test-run" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment":{"agent_identity_id":"<agent_identity_uuid>","agent_slug":"my-publisher","alert_policy":null,"mode":"","workload":{"compute_backend":null,"config":{},"execution":null}}}'
```

## Managed Deployments

Inspect and preview the resolved managed spec, including prompt, presets, policies, and runtime-facing configuration.

Get the resolved managed spec for a seren-agent deployment.

Returns the resolved managed-agent configuration for a seren-agent deployment. Use seren-cloud deployment APIs for raw runtime operations.

### GET `/publishers/seren-agent/deployments/{id}/managed`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-agent/deployments/<id>/managed" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Update the editable managed spec for a seren-agent deployment.

### PATCH `/publishers/seren-agent/deployments/{id}/managed`

```bash
curl -sS -X PATCH "https://api.serendb.com/publishers/seren-agent/deployments/<id>/managed" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_identity_id":"<agent_identity_uuid>","agent_slug":"my-publisher","alert_policy":null}'
```

Preview a managed update before applying it.

### POST `/publishers/seren-agent/deployments/{id}/managed/preview`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/deployments/<id>/managed/preview" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_identity_id":"<agent_identity_uuid>","agent_slug":"my-publisher","alert_policy":null}'
```

## Revisions and Rollbacks

Inspect immutable revision history and preview or apply rollbacks to prior managed deployment states.

List immutable revision snapshots for a managed deployment.

### GET `/publishers/seren-agent/deployments/{id}/managed/revisions`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-agent/deployments/<id>/managed/revisions" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Roll a managed deployment back to a prior revision.

### POST `/publishers/seren-agent/deployments/{id}/managed/rollback`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/deployments/<id>/managed/rollback" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision_id":"<revision_uuid>"}'
```

Preview rolling a managed deployment back to a prior revision.

### POST `/publishers/seren-agent/deployments/{id}/managed/rollback/preview`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-agent/deployments/<id>/managed/rollback/preview" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision_id":"<revision_uuid>"}'
```