Agent API
API working on agent instances
undefined
| Path | Method | Protected |
|---|---|---|
/v1/agents/invoke-agent | POST | Yes |
Example Request JSON
{
"appName": "string",
"envName": "string",
"agentTypeName": "string",
"parameters": {
"kind": "bool",
"value": true
},
"phantomId": "924e957e-cd56-4af8-a7d0-d200011bddaa",
"config": [],
"methodName": "string",
"methodParameters": {
"kind": "bool",
"value": true
},
"mode": "await",
"scheduleAt": "2019-08-24T14:15:22Z",
"idempotencyKey": "string",
"deploymentRevision": 0,
"ownerAccountEmail": "string"
}Example Response JSON
{
"agentId": {
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"agentId": "string"
},
"idempotencyKey": "string",
"result": {
"graph": {
"defs": [
{
"id": "string",
"name": "string",
"body": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
}
],
"root": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
},
"value": {
"kind": "bool",
"value": true
}
},
"componentRevision": 0
}Invoke a tool on an existing agent or a fresh ephemeral component owner
| Path | Method | Protected |
|---|---|---|
/v1/agents/invoke-tool | POST | Yes |
Uses normal invocation permissions, queueing and idempotency. Byte stdin, stdout and stderr require an attached invocation session rather than this scalar endpoint.
Example Request JSON
{
"appName": "string",
"envName": "string",
"agentId": {
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"agentId": "string"
},
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"toolName": "string",
"commandPath": [
"string"
],
"input": {
"graph": {
"defs": [
{
"id": "string",
"name": "string",
"body": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
}
],
"root": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
},
"value": {
"kind": "bool",
"value": true
}
},
"mode": "await",
"scheduleAt": "2019-08-24T14:15:22Z",
"idempotencyKey": "string"
}Example Response JSON
{
"agentId": {
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"agentId": "string"
},
"idempotencyKey": "string",
"result": {
"type": "Success",
"result": {
"graph": {
"defs": [
{
"id": "string",
"name": "string",
"body": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
}
],
"root": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
},
"value": {
"kind": "bool",
"value": true
}
}
},
"status": "unknown",
"componentRevision": 0,
"agentFingerprint": "5c9c764e-7053-4376-bc55-59b87edea063",
"oplogIndex": 0
}Return the effective definition of a tool bound to an existing agent or component baseline.
| Path | Method | Protected |
|---|---|---|
/v1/agents/describe-tool | POST | Yes |
Example Request JSON
{
"appName": "string",
"envName": "string",
"agentId": {
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"agentId": "string"
},
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"toolName": "string"
}Example Response JSON
{
"definition": {
"version": "string",
"requires_filesystem": true,
"commands": {
"nodes": [
{
"name": "string",
"aliases": [
"string"
],
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"globals": {
"options": [
{
"long": "string",
"short": null,
"aliases": [
"string"
],
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"value_name": "string",
"shape": {
"kind": "scalar",
"value": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
},
"default": {
"kind": "bool",
"value": true
},
"required": true,
"env_var": "string"
}
],
"flags": [
{
"long": "string",
"short": null,
"aliases": [
"string"
],
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"shape": {
"kind": "bool-flag",
"value": {
"default": true,
"negatable": true
}
},
"env_var": "string"
}
]
},
"subcommands": [
0
],
"body": {
"positionals": {
"fixed": [
{
"name": "string",
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"value_name": "string",
"type_": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
},
"default": {
"kind": "bool",
"value": true
},
"required": true,
"accepts_stdio": true
}
],
"tail": {
"name": "string",
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"value_name": "string",
"item_type": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
},
"min": 0,
"max": 0,
"separator": "string",
"verbatim": true,
"accepts_stdio": true
}
},
"options": [
{
"long": "string",
"short": null,
"aliases": [
"string"
],
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"value_name": "string",
"shape": {
"kind": "scalar",
"value": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
},
"default": {
"kind": "bool",
"value": true
},
"required": true,
"env_var": "string"
}
],
"flags": [
{
"long": "string",
"short": null,
"aliases": [
"string"
],
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"shape": {
"kind": "bool-flag",
"value": {
"default": true,
"negatable": true
}
},
"env_var": "string"
}
],
"constraints": [
{
"kind": "requires-all",
"value": [
{
"kind": "present",
"value": "string"
}
]
}
],
"stdin": {
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"mime": [
"string"
],
"required": true
},
"stdout": {
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"mime": [
"string"
],
"required": true
},
"stderr": {
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"mime": [
"string"
],
"required": true
},
"result": {
"type_": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
},
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"formatters": [
{
"name": "string",
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
}
}
],
"default_formatter": "string"
},
"errors": [
{
"name": "string",
"doc": {
"summary": "string",
"description": "string",
"examples": [
{
"title": "string",
"body": "string"
}
]
},
"kind": "usage-error",
"exit_code": 0,
"payload": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
}
],
"annotations": {
"read_only": true,
"destructive": true,
"idempotent": true,
"open_world": true
}
}
}
]
},
"schema": {
"defs": [
{
"id": "string",
"name": "string",
"body": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
}
],
"root": {
"kind": "ref",
"value": {
"id": "string",
"metadata": {
"doc": "string",
"aliases": [
"string"
],
"examples": [
"string"
],
"deprecated": "string",
"role": {
"tag": "multimodal"
}
}
}
}
}
},
"componentRevision": 0,
"deploymentRevision": 0
}Invoke an agent through an attached live streaming session
| Path | Method | Protected |
|---|---|---|
/v1/agents/invoke-agent-session | GET | Yes |
Upgrades to a WebSocket using the required golem.agent-invocation.v1
subprotocol. Text frames carry public v1 JSON lifecycle messages, while
binary frames carry the public v1 binary envelope. The bearer token is
authenticated before the upgrade and authorizes both start and resume.
undefined
| Path | Method | Protected |
|---|---|---|
/v1/agents/create-agent | POST | Yes |
Example Request JSON
{
"appName": "string",
"envName": "string",
"agentTypeName": "string",
"parameters": {
"kind": "bool",
"value": true
},
"phantomId": "924e957e-cd56-4af8-a7d0-d200011bddaa",
"config": []
}Example Response JSON
{
"agentId": {
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"agentId": "string"
},
"componentRevision": 0
}Agent API Errors
| Status Code | Description | Body |
|---|---|---|
| 400 | {"code":"string","errors":["string"]} | |
| 401 | {"code":"string","error":"string"} | |
| 403 | {"code":"string","error":"string"} | |
| 404 | {"code":"string","error":"string"} | |
| 409 | {"code":"string","error":"string"} | |
| 413 | {"code":"string","error":"string"} | |
| 415 | {"code":"string","error":"string"} | |
| 422 | {"code":"string","error":"string"} | |
| 500 | {"code":"string","error":"string","workerError":{"cause":"string","stderr":"string"}} |