Skip to Content
kosemdocs
ReferenceAPIAgents

Mark agent unread

Marks an agent unread by the caller, who follows it from then on, and returns it. It's unread while it's IDLE after finishing its turn, failing or reaching a limit, until the caller marks it read. Service accounts follow no agents, and are refused.

POST
/v1/projects/{project}/agents/{agent}/mark-unread

Marks an agent unread by the caller, who follows it from then on, and returns it.

It's unread while it's IDLE after finishing its turn, failing or reaching a limit, until the caller marks it read. Service accounts follow no agents, and are refused.

Authorization

bearer
headerAuthorizationBearer <token>

An access token, or an API key.

Path Parameters

project*string

The project's ID.

Match^prj_[0-7][0-9a-hjkmnp-tv-z]{25}$
agent*string

The agent's ID.

Match^ags_[0-7][0-9a-hjkmnp-tv-z]{25}$

Response Body

OK

application/json
  1. response
activityTime*string

When the agent was last active, as people see it, which lists order agents by: when it was created, someone wrote to it or answered it, or it stopped, as it finished its turn, asked a question, was interrupted or failed. Unlike updateTime, the steps of a turn leave it.

Formatdate-time
awaitingCalls*array<string>

The tool calls that the agent waits for answers to, in AWAITING_INPUT.

config*

How the agent works. Set when the agent is created, then changed only by configChange events.

createTime*string

When the agent was created.

Formatdate-time
creator*string

Who created the agent, such as user:usr_….

environment?

The agent's environment, which its first command makes; absent while it has none.

jobs*array<>

The background jobs that the agent left running and is told the end of, while its environment runs. As each ends, it starts a turn of an IDLE agent, unless someone interrupted its last turn, so an agent that finished its turn with jobs goes on when they end.

lastSequence*integer

The sequence of the transcript's last event.

Formatint64
lastStop?

Why the agent last stopped; absent until it first does.

name*string

Resource name, projects/{project_id}/agents/{agent_id}.

state*string

What the agent is doing: IDLE with nothing to do, as lastStop says, until a message starts it again; QUEUED with work it starts on shortly; RUNNING; or AWAITING_INPUT, waiting for answers to the tool calls in awaitingCalls, such as a question it asked.

Value in"IDLE""QUEUED""RUNNING""AWAITING_INPUT"
title*string

A title for people, at most 200 characters. Empty until the agent writes one after its first answer, unless someone set it.

unread*boolean

Whether the agent stopped since the caller last read it: it finished its turn, failed or reached a limit, and is IDLE. Only for agents the caller follows, as people follow those they created, sent to or marked unread; always false for service accounts. MarkAgentRead marks it read.

updateTime*string

When the agent last changed, or had an event.

Formatdate-time
usage*

What the agent used, all told.

visibility*string

Who sees the agent: PROJECT, everyone who may see the project's agents, by their roles on it; PRIVATE, its owner, those it is shared with through its IAM policy, and those who hold agents.agents.accessPrivate on the project.

Value in"PROJECT""PRIVATE"
Example Request
curl -X POST 'https://api.kosem.ai/v1/projects/string/agents/string/mark-unread'
Example Response
{
  "activityTime": "2019-08-24T14:15:22Z",
  "awaitingCalls": [
    "string"
  ],
  "config": {
    "environment": {
      "diskGib": 0,
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "idleTimeoutSeconds": 0,
      "image": "string",
      "memoryMib": 0,
      "runnerPool": "string",
      "secrets": [
        {
          "credential": "string",
          "env": "string",
          "file": "string",
          "scope": {
            "property1": null,
            "property2": null
          },
          "secret": "string",
          "state": "ACTIVE",
          "stateReason": "string"
        }
      ],
      "stoppedTtlSeconds": 0,
      "vcpus": 0
    },
    "instructions": "string",
    "maxModelCalls": 0,
    "model": "string",
    "reasoningEffort": "",
    "tools": [
      "string"
    ]
  },
  "createTime": "2019-08-24T14:15:22Z",
  "creator": "string",
  "environment": {
    "diskGib": 0,
    "environment": "string",
    "memoryMib": 0,
    "state": "PROVISIONING",
    "stateReason": "string",
    "updateTime": "2019-08-24T14:15:22Z",
    "vcpus": 0
  },
  "jobs": [
    {
      "command": "string",
      "job": "string",
      "startTime": "2019-08-24T14:15:22Z"
    }
  ],
  "lastSequence": 0,
  "lastStop": {
    "message": "string",
    "reason": "END_TURN"
  },
  "name": "string",
  "state": "IDLE",
  "title": "string",
  "unread": true,
  "updateTime": "2019-08-24T14:15:22Z",
  "usage": {
    "webSearches": 0
  },
  "visibility": "PROJECT"
}