Get an agent

GET

/agents/{agentId}

const url = 'https://api.asklucy.eu/v1/agents/example';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --url https://api.asklucy.eu/v1/agents/example \
  --header 'Authorization: Bearer <token>'

Its owner, or any org_admin for a service agent. Anyone else gets 404.

Authorizations

zitadel

Parameters

Path Parameters

agentId

required

string

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

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

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

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"
  }
}

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.

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.