Change an agent

PATCH

/agents/{agentId}

const url = 'https://api.asklucy.eu/v1/agents/example';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","description":"example","instructions":"example","model":"example","tools":{"web_search":false,"sandbox":false,"memory":"off","connectors":["m365.mail"]},"limits":{"max_steps":30,"max_minutes":15},"enabled":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://api.asklucy.eu/v1/agents/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "description": "example", "instructions": "example", "model": "example", "tools": { "web_search": false, "sandbox": false, "memory": "off", "connectors": [ "m365.mail" ] }, "limits": { "max_steps": 30, "max_minutes": 15 }, "enabled": true }'

A change to its configuration (name, description, instructions, model, tools, limits) saves a new version; runs keep the version they started with. enabled alone doesn’t make a version. An agent an admin disabled can’t be enabled here (409 …/errors/agent-disabled-by-admin).

Authorizations

zitadel

Parameters

Path Parameters

agentId

required

string

/^agt_[A-Za-z0-9]+$/

Request Body^required

application/json

The identity can’t change.

object

>= 1 properties

name

string

>= 1 characters <= 100 characters

description

string

<= 500 characters

instructions

string

>= 1 characters <= 20000 characters

model

string | null

tools

What a run may use, besides the tools of the agent’s own connections (listAgentConnectors, listAgentToolPermissions). Never available to agents: tools on people’s computers (local).

object

web_search

Only while the organization lets the agent’s identity use web search (the owner’s can_web_search; for service agents, web_search not off).

boolean

sandbox

Run code and write files in Lucy’s sandbox (when the contract includes it).

boolean

memory

Lucy Memory, when it is on for the identity: the owner’s memory (owner), or the agent’s own and the organization’s shared memory (service). read recalls and searches; read_write also lets the run remember new facts.

string

default: off

Allowed values: off read read_write

connectors

Ignored, and always empty in answers: an agent uses its own connections (listAgentConnectors) with its own tool permissions (listAgentToolPermissions), never its owner’s. Accepted so older clients can still save an agent.

Array<string>

<= 10 items

limits

object

max_steps

Tool calls per run. At the limit Lucy stops using tools and writes the answer with what she has.

integer

default: 30 >= 1 <= 100

max_minutes

Wall-clock time per run, queueing excluded. At the limit the run ends failed (error.code time_limit).

integer

default: 15 >= 1 <= 15

enabled

boolean

Responses

200

application/json

object

required

string

name

required

string

description

required

string

identity

required

Whom the agent acts as.

owner: its creator, with exactly their access (their memory, their Microsoft 365, their quotas). Its runs are their conversations: they can read and continue them as themselves.
service: itself (its ID is its principal). It reaches only what it was given: its knowledge files and the tools below, never anyone’s Microsoft 365. Only org_admins create and see service agents; their runs are read-only.

string

Allowed values: owner service

owner_id

required

The person an owner agent acts as (its creator). Null for service agents.

string | null

created_by

required

object

required

Zitadel user ID.

string

name

required

string

email

string | null format: email

kind

service is a customer system’s Zitadel service user; agent is a service agent (its ID is the agt_ ID), the author of its runs’ messages.

string

Allowed values: person service agent

version

required

The current version (listAgentVersions).

integer

>= 1

instructions

required

What the agent does, in its own words. Lucy follows them in every run, after the organization’s instructions.

string

model

required

A Model.id while the identity may choose models; null is Auto.

string | null

tools

required

What a run may use, besides the tools of the agent’s own connections (listAgentConnectors, listAgentToolPermissions). Never available to agents: tools on people’s computers (local).

object

web_search

Only while the organization lets the agent’s identity use web search (the owner’s can_web_search; for service agents, web_search not off).

boolean

sandbox

Run code and write files in Lucy’s sandbox (when the contract includes it).

boolean

memory

string

default: off

Allowed values: off read read_write

connectors

Array<string>

<= 10 items

knowledge_files

required

Array<object>

object

required

string

agent_id

required

string

name

required

string

content_type

required

string

size_bytes

required

integer

sha256

string | null

status

required

string

Allowed values: pending processing ready rejected

rejection_reason

string | null

created_by

One of:

object
null

object

required

Zitadel user ID.

string

name

required

string

email

string | null format: email

kind

service is a customer system’s Zitadel service user; agent is a service agent (its ID is the agt_ ID), the author of its runs’ messages.

string

Allowed values: person service agent

created_at

required

string format: date-time

download_url

Only on getAgentFile for ready files; valid a few minutes.

string | null format: uri

download_url_expires_at

string | null format: date-time

limits

required

object

max_steps

Tool calls per run. At the limit Lucy stops using tools and writes the answer with what she has.

integer

default: 30 >= 1 <= 100

max_minutes

Wall-clock time per run, queueing excluded. At the limit the run ends failed (error.code time_limit).

integer

default: 15 >= 1 <= 15

enabled

required

Whether it can run now (manual runs and its triggers). See disabled_reason.

boolean

disabled_reason

required

Why it can’t run: its owner (or a service agent’s admins) turned it off, an org_admin disabled it (updateOrgAgent), its owner was removed from the organization, or it was deleted.

string | null

Allowed values: owner admin owner_removed deleted

triggers

How many triggers it has.

integer

last_run

One of:

object
null

object

required

string

status

required

queued waits for the agent’s run in progress; skipped: a schedule fired while a run was still going, so this time didn’t run.

string

Allowed values: queued running succeeded failed cancelled skipped

created_at

required

string format: date-time

finished_at

string | null format: date-time

created_at

required

string format: date-time

updated_at

required

string format: date-time

deleted_at

string | null format: date-time

Example

{
  "id": "agt_3Hq9ZtWk2pLm7Rx0aBcD",
  "identity": "owner",
  "created_by": {
    "kind": "person"
  },
  "tools": {
    "web_search": false,
    "sandbox": false,
    "memory": "off",
    "connectors": [
      "m365.mail"
    ]
  },
  "knowledge_files": [
    {
      "id": "file_8bQ2nVx",
      "status": "pending",
      "created_by": {
        "kind": "person"
      }
    }
  ],
  "limits": {
    "max_steps": 30,
    "max_minutes": 15
  },
  "disabled_reason": "owner",
  "last_run": {
    "status": "queued"
  }
}

400

The request is invalid; errors lists what’s wrong.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

401

Missing, expired or invalid token.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

403

The token is valid but lacks the role this needs.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

404

No such object in your organization.

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

409

The object isn’t in a state that allows this (e.g. Lucy is already answering).

application/problem+json

RFC 9457 problem details.

object

type

required

string format: uri-reference

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

quota

For quota-exceeded, the window that is used up.

object

window

required

string

Allowed values: five_hours week month

percent_used

required

number

<= 100

resets_at

required

Null for a rolling window that hasn’t started.

string | null format: date-time

limited_by

required

organization when the organization’s budget is closer to running out than the member’s own limit.

string

Allowed values: personal organization

request

One of:

object
null

A request as its member sees it, where they asked.

object

required

string

status

required

string

Allowed values: pending approved declined withdrawn

created_at

required

string format: date-time

decided_at

required

string | null format: date-time

note

required

What the admin who decided wrote back.

string | null

errors

Field-level problems (400 only).

Array<object>

object

field

required

JSON pointer into the request body.

string

message

required

string

Example

{
  "type": "https://docs.asklucy.eu/errors/answer-in-progress",
  "quota": {
    "window": "five_hours",
    "limited_by": "personal",
    "request": {
      "status": "pending"
    }
  }
}

Headers

X-Request-Id

string

Unique per request; quote it to support.

Change an agent

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Responses

200

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

404

Example

Headers

409

Example

Headers

Request Body^required