Skip to Content
kosemdocs
ReferenceAPIAgents

Send agent events

Sends events to an agent, in order: messages, config changes, answers to its questions and interrupts. They are added to the transcript, which the response returns them as, and the agent acts on them. A message or an answer makes the agent act on the caller's turn, so the caller needs only to write to the agent. What changes nothing adds no event: an interrupt of an idle agent, a config change to the config the agent has, and an answer to a call of the last agentMessage that has its result. An answer to a call that is not in the last agentMessage fails with failed_precondition and the reason CALL_NOT_OPEN.

POST
/v1/projects/{project}/agents/{agent}/events

Sends events to an agent, in order: messages, config changes, answers to its questions and interrupts. They are added to the transcript, which the response returns them as, and the agent acts on them.

A message or an answer makes the agent act on the caller's turn, so the caller needs only to write to the agent. What changes nothing adds no event: an interrupt of an idle agent, a config change to the config the agent has, and an answer to a call of the last agentMessage that has its result. An answer to a call that is not in the last agentMessage fails with failed_precondition and the reason CALL_NOT_OPEN.

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

Query Parameters

requestId?string

Makes retries safe: sending again with the same ID to the agent returns the events the first request added, rather than adding them again. While the agent's model writes, what the first sent waits for its answer, and a retry adds nothing more.

Formatuuid

Request Body

application/json
  1. body
events*array<>

The events.

Items1 <= items <= 10

Response Body

OK

application/json
  1. response
agent*

The agent after them.

events*array<>

The events the inputs added, in order. An input may add none, or several: an interrupt adds the results of the calls it closes, and a status.

Example Request
curl -X POST 'https://api.kosem.ai/v1/projects/string/agents/string/events' \
  -H 'Content-Type: application/json' \
  -d '{
  "events": [
    {}
  ]
}'
Example Response
{
  "agent": {
    "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"
  },
  "events": [
    {
      "agentMessage": {
        "id": "string",
        "model": "string",
        "parts": [
          {
            "file": {
              "data": "string",
              "file": "string",
              "filename": "string",
              "mediaType": "string",
              "url": "http://example.com"
            },
            "reasoning": {
              "text": "string"
            },
            "text": {
              "text": "string"
            },
            "toolCall": {
              "id": "string",
              "input": "string",
              "tool": "string"
            }
          }
        ],
        "readSequence": 0,
        "stop": "END",
        "usage": {
          "cacheReadTokens": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      },
      "configChange": {
        "author": "string",
        "changedFields": [
          "model"
        ],
        "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"
          ]
        },
        "grantedSecrets": [
          "string"
        ],
        "removedSecrets": [
          "string"
        ]
      },
      "contextCleared": {
        "resultSequences": [
          0
        ],
        "throughSequence": 0
      },
      "contextSummary": {
        "summary": "string",
        "throughSequence": 0
      },
      "createTime": "2019-08-24T14:15:22Z",
      "interrupt": {
        "author": "string"
      },
      "jobEnded": {
        "command": {
          "command": "string",
          "durationMs": 0,
          "endReason": "string",
          "environmentStart": "STARTED",
          "exitCode": 0,
          "job": "string",
          "running": true,
          "secrets": [
            "string"
          ],
          "startDurationMs": 0,
          "stderr": "string",
          "stderrTruncated": true,
          "stdout": "string",
          "stdoutTruncated": true,
          "workingDirectory": "string"
        },
        "job": "string",
        "text": "string"
      },
      "sequence": 0,
      "status": {
        "awaitingCalls": [
          "string"
        ],
        "state": "IDLE",
        "stop": {
          "message": "string",
          "reason": "END_TURN"
        }
      },
      "toolResult": {
        "author": "string",
        "callId": "string",
        "content": [
          {
            "file": {
              "data": "string",
              "file": "string",
              "filename": "string",
              "mediaType": "string",
              "url": "http://example.com"
            },
            "reasoning": {
              "text": "string"
            },
            "text": {
              "text": "string"
            },
            "toolCall": {
              "id": "string",
              "input": "string",
              "tool": "string"
            }
          }
        ],
        "display": {
          "accessDecision": {
            "alias": "string",
            "approved": true,
            "expireTime": "2019-08-24T14:15:22Z",
            "note": "string",
            "scope": {
              "property1": null,
              "property2": null
            },
            "target": "string"
          },
          "answer": {
            "selected": [
              "string"
            ],
            "text": "string"
          },
          "command": {
            "command": "string",
            "durationMs": 0,
            "endReason": "string",
            "environmentStart": "STARTED",
            "exitCode": 0,
            "job": "string",
            "running": true,
            "secrets": [
              "string"
            ],
            "startDurationMs": 0,
            "stderr": "string",
            "stderrTruncated": true,
            "stdout": "string",
            "stdoutTruncated": true,
            "workingDirectory": "string"
          },
          "publishedSite": {
            "displayName": "string",
            "fileCount": 0,
            "home": true,
            "live": true,
            "newSite": true,
            "site": "string",
            "sizeBytes": 0,
            "uri": "string",
            "version": "string"
          },
          "todoList": {
            "items": [
              {
                "content": "string",
                "state": "PENDING"
              }
            ]
          },
          "webPage": {
            "characters": 0,
            "title": "string",
            "truncated": true,
            "url": "string"
          },
          "webSearch": {
            "query": "string",
            "results": [
              {
                "publishTime": "2019-08-24T14:15:22Z",
                "snippet": "string",
                "title": "string",
                "url": "string"
              }
            ]
          }
        },
        "isError": true,
        "tool": "string"
      },
      "toolStarted": {
        "callId": "string",
        "tool": "string"
      },
      "turn": 0,
      "userMessage": {
        "author": "string",
        "parts": [
          {
            "file": {
              "data": "string",
              "file": "string",
              "filename": "string",
              "mediaType": "string",
              "url": "http://example.com"
            },
            "reasoning": {
              "text": "string"
            },
            "text": {
              "text": "string"
            },
            "toolCall": {
              "id": "string",
              "input": "string",
              "tool": "string"
            }
          }
        ]
      },
      "warning": {
        "message": "string"
      }
    }
  ]
}