Skip to Content
kosemdocs
ReferenceAPIAgents

Resolve access request

Approves or denies an agent's open request_access call, atomically granting/widening access when approved and immediately waking the agent. Takes agents.agents.send on the agent, plus the caller's own issue/access permission on target when approving.

POST
/v1/projects/{project}/agents/{agent}/accessRequests/{callId}

Approves or denies an agent's open request_access call, atomically granting/widening access when approved and immediately waking the agent.

Takes agents.agents.send on the agent, plus the caller's own issue/access permission on target when approving.

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}$
callId*string

The request_access tool call ID to approve or deny.

Length1 <= length <= 256

Request Body

application/json
  1. body
approve*boolean

Whether to approve the request.

expireTime?string

Optional grant expiry time, bounded by agents.maxGrantTtl.

Formatdate-time
note?string

Optional note returned to the agent.

Lengthlength <= 1000
scope?

Optional human-enforced narrowing scope for an access profile grant.

target?string

Required when approving: resource name of the project access profile or secret to grant or widen.

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/accessRequests/string' \
  -H 'Content-Type: application/json' \
  -d '{
  "approve": true
}'
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"
}