跳转到内容

DevHub API 数据结构

DevHub API 参考。路径相对于 DevHub 基础地址,在 DevHub Console 中 Agent 的 API 页可以看到;每个接口都需要 DevHub Key。规范中的描述保留原文。

下载 OpenAPI

{
"name": "sessionId",
"in": "path",
"required": true,
"description": "A Session id from this API. Any id that is not one of the calling Developer's Sessions answers 404 `not_found`.",
"schema": {
"type": "string"
}
}
{
"name": "turnId",
"in": "path",
"required": true,
"description": "A Turn id from `POST /api/v1/sessions/{sessionId}/turns` for this Session; submitting a Client Tool result also accepts the Turn of a call DevHub lists for the Session. Any other id answers 404 `not_found`.",
"schema": {
"type": "string"
}
}
{
"name": "limit",
"in": "query",
"required": false,
"description": "The most items to return.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"default": 50
}
}
{
"name": "cursor",
"in": "query",
"required": false,
"description": "A cursor this operation returned to you for the same Session; any other value answers 400 `invalid_request`.",
"schema": {
"type": "string"
}
}
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"description": "Identifies one creation or input, so a repeated request cannot create a second Agent, Session or Turn input.",
"schema": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$"
}
}
{
"name": "agentId",
"in": "path",
"required": true,
"description": "An Agent id from this API. Any id that is not one of the calling Developer's Agents answers 404 `not_found`.",
"schema": {
"type": "string"
}
}
{
"description": "Identifies the Client Tool set's revision; send it in `If-Match` to replace only that revision.",
"schema": {
"type": "string"
}
}
{
"type": "http",
"scheme": "bearer",
"bearerFormat": "DevHub Key",
"description": "A DevHub Key, `ti_dev_` followed by 43 base64url characters, sent as `Authorization: Bearer <key>`. It authenticates exactly one provisioned Developer and grants nothing in the core. A missing, malformed, unknown or revoked key, or a key whose Developer is not yet provisioned, is refused with 401 `authentication_required`. A revocation applies to the next request and ends the event streams the key opened within a few seconds."
}
{
"description": "The request carries no usable DevHub Key.",
"headers": {
"WWW-Authenticate": {
"description": "Always `Bearer`.",
"schema": {
"type": "string",
"const": "Bearer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
},
"example": {
"error": {
"code": "authentication_required",
"message": "A valid DevHub Key is required."
}
}
}
}
}
{
"description": "DevHub or the service behind it is temporarily unavailable; retry later. The DevHub Key was not refused.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
{
"description": "The request is malformed; `invalid_request`. Nothing was changed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
{
"description": "The id is not one of the calling Developer's Agents; `not_found`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
{
"description": "The id is not one of the calling Developer's Sessions; `not_found`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
{
"description": "The Session is not one of the calling Developer's, or the Turn is not one of its Turns; `not_found`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
{
"description": "`conflict`: another request is changing this Agent; retry when it has finished. `configuration_unavailable` (update only): the Agent's configuration references something no longer available, such as a Skill version, so the core refuses to save it until that is changed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"agentId",
"name",
"autoTitle",
"model",
"realtimeModel",
"activeTurnId",
"readOnly",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^ses_[0-9a-f]{32}$"
},
"agentId": {
"type": "string",
"pattern": "^agt_[0-9a-f]{32}$",
"description": "The Agent the Session belongs to; it stays set after that Agent is deleted."
},
"name": {
"type": [
"string",
"null"
],
"description": "The name you gave the Session, if any."
},
"autoTitle": {
"type": [
"string",
"null"
],
"description": "A title the platform generated from the conversation, if any."
},
"model": {
"type": "string",
"description": "The text model the Session's next Turn uses."
},
"realtimeModel": {
"type": [
"string",
"null"
],
"description": "The Realtime model of the Session's voice conversations; null without voice."
},
"activeTurnId": {
"type": [
"string",
"null"
],
"description": "The running Turn, if any."
},
"readOnly": {
"type": "boolean",
"description": "The Session can be read but no longer changed or continued."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"sessions",
"nextCursor"
],
"properties": {
"sessions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
},
"nextCursor": {
"type": [
"string",
"null"
]
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"agentId"
],
"properties": {
"agentId": {
"type": "string",
"pattern": "^agt_[0-9a-f]{32}$",
"description": "One of your Agents."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Surrounding whitespace is trimmed; control characters are refused."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"role",
"content",
"createdAt"
],
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"user",
"assistant"
]
},
"content": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}
{
"description": "Work the Agent did during a Turn, such as a tool call.",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"kind",
"status",
"category",
"label",
"createdAt",
"completedAt"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"status": {
"type": "string",
"description": "running, succeeded, failed, interrupted or unknown_result; more may be added."
},
"category": {
"type": [
"string",
"null"
],
"description": "`tool_call` or `skill_read` for a tool call; null for other work such as model calls."
},
"label": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
{
"type": "object",
"additionalProperties": false,
"if": {
"required": [
"kind"
]
},
"then": {
"properties": {
"userMessages": {
"maxItems": 0
}
}
},
"required": [
"id",
"sessionId",
"status",
"userMessages",
"assistantMessage",
"operations",
"failure",
"createdAt",
"completedAt"
],
"properties": {
"id": {
"type": "string"
},
"sessionId": {
"type": "string",
"pattern": "^ses_[0-9a-f]{32}$"
},
"status": {
"type": "string",
"enum": [
"running",
"succeeded",
"failed",
"interrupted"
]
},
"kind": {
"type": "string",
"enum": [
"template_handoff"
],
"description": "The visible summary created while switching the Session to another AgentTemplate."
},
"userMessages": {
"type": "array",
"description": "The input the Turn received, in order. Empty for a Template Handoff.",
"items": {
"$ref": "#/components/schemas/Message"
}
},
"assistantMessage": {
"oneOf": [
{
"$ref": "#/components/schemas/Message"
},
{
"type": "null"
}
]
},
"operations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Operation"
}
},
"failure": {
"description": "Why a failed Turn failed, when known.",
"oneOf": [
{
"$ref": "#/components/schemas/TurnFailure"
},
{
"type": "null"
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "A stable code, such as `model_provider_failed`."
},
"message": {
"type": "string"
}
}
}
{
"description": "A final transcript of a voice conversation in the Session: what the user said (`input_transcript`) or what the voice model answered (`response`). `turnId` names the Turn it started or speaks about, if any.",
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type",
"text",
"turnId",
"createdAt"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "input_transcript"
},
"text": {
"type": "string"
},
"turnId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"type",
"kind",
"text",
"turnId",
"interrupted",
"createdAt"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string",
"const": "response"
},
"kind": {
"type": "string",
"description": "chat, task_ack, task_progress, task_result or clarify; more may be added."
},
"text": {
"type": "string"
},
"turnId": {
"type": [
"string",
"null"
]
},
"interrupted": {
"type": "boolean",
"description": "The answer was cut off; its text may include speech the user did not hear."
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}
]
}
{
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"turn"
],
"properties": {
"type": {
"type": "string",
"const": "turn"
},
"turn": {
"$ref": "#/components/schemas/Turn"
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"realtime"
],
"properties": {
"type": {
"type": "string",
"const": "realtime"
},
"realtime": {
"$ref": "#/components/schemas/RealtimeFact"
}
}
}
]
}
{
"type": "object",
"additionalProperties": false,
"required": [
"entries",
"nextCursor"
],
"properties": {
"entries": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TimelineEntry"
}
},
"nextCursor": {
"type": [
"string",
"null"
]
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"input"
],
"properties": {
"input": {
"type": "string",
"minLength": 1,
"description": "Text that is not only whitespace, at most 32 KiB in UTF-8."
},
"fileIds": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"uniqueItems": true,
"description": "Files uploaded to this Session for the Agent to use in the Turn. A file uploaded with an `image/` content type is also shown to the model as an image, so the Session's model must accept images and the platform's image limits apply (at most 4 JPEG, PNG or static WebP images of up to 8 MiB each); otherwise the Turn fails with a `turn_error` that says why.",
"items": {
"type": "string",
"pattern": "^file_[0-9a-f]{32}$"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"turnId",
"sessionId",
"mode"
],
"properties": {
"turnId": {
"type": "string",
"description": "The Turn the input started or joined."
},
"sessionId": {
"type": "string",
"pattern": "^ses_[0-9a-f]{32}$"
},
"mode": {
"type": "string",
"enum": [
"started",
"steered"
]
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"turnId",
"accepted"
],
"properties": {
"turnId": {
"type": "string"
},
"accepted": {
"type": "boolean",
"description": "True when the running Turn was asked to stop; false when it was not running."
}
}
}
{
"description": "One Server-Sent Events `data` frame. Turn events carry the Turn's `event`, its per-Turn `seq` and a `payload`: `turn_started` {model} (type `agent.session.turn.started`); `progress` {text} (`agent.session.turn.progress`, a progress note, not answer text); `assistant_draft` {text} (`agent.session.turn.output_text.snapshot`, the complete draft so far: replace, do not append); `operation_step` {operationId, status, label, category} and `assistant_message` {messageId, text} (`agent.session.turn.item.added`; the latter is the saved answer); `turn_error` {code, message} (`agent.session.turn.failed`); `turn_finished` {status} (`agent.session.turn.completed`, `.failed` or `.cancelled`), the Turn's last event. Client Tool calls carry a `ClientToolCallsEvent` (`agent.session.turn.requires_action`). Voice transcripts carry a `RealtimeFact`. Ignore types you do not know.",
"type": "object",
"additionalProperties": false,
"required": [
"type",
"sessionId",
"turnId",
"createdAt",
"data"
],
"properties": {
"type": {
"type": "string",
"enum": [
"agent.session.turn.started",
"agent.session.turn.progress",
"agent.session.turn.requires_action",
"agent.session.turn.output_text.snapshot",
"agent.session.turn.item.added",
"agent.session.turn.failed",
"agent.session.turn.completed",
"agent.session.turn.cancelled",
"agent.session.realtime.input_transcript.completed",
"agent.session.realtime.response.completed"
]
},
"sessionId": {
"type": "string",
"pattern": "^ses_[0-9a-f]{32}$"
},
"turnId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"data": {
"oneOf": [
{
"$ref": "#/components/schemas/TurnEvent"
},
{
"$ref": "#/components/schemas/ClientToolCallsEvent"
},
{
"$ref": "#/components/schemas/RealtimeFact"
}
]
}
}
}
{
"description": "The Client Tool calls the Agent made in one step of the Turn that DevHub took for your application. Answer each with `POST /api/v1/sessions/{sessionId}/turns/{turnId}/client-tool-results` before its `deadlineAt`. A call made while DevHub was not executing the Session, such as during a DevHub restart, is not shown, and the Agent is told that it was not performed.",
"type": "object",
"additionalProperties": false,
"required": [
"event",
"seq",
"payload"
],
"properties": {
"event": {
"type": "string",
"const": "client_tool_calls"
},
"seq": {
"type": "integer",
"minimum": 0
},
"payload": {
"type": "object",
"additionalProperties": false,
"required": [
"calls"
],
"properties": {
"calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientToolCall"
}
}
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"callId",
"name",
"arguments",
"deadlineAt"
],
"properties": {
"callId": {
"type": "string",
"description": "Identifies the call within its Turn; send it back with the result."
},
"name": {
"type": "string",
"description": "The Client Tool the Agent called."
},
"arguments": {
"type": "object",
"description": "Arguments for the tool's declared parameters."
},
"deadlineAt": {
"type": "string",
"format": "date-time",
"description": "The result must arrive before this time."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"event",
"seq",
"payload"
],
"properties": {
"event": {
"type": "string",
"enum": [
"turn_started",
"progress",
"assistant_draft",
"operation_step",
"assistant_message",
"turn_error",
"turn_finished"
]
},
"seq": {
"type": "integer",
"minimum": 0
},
"payload": {
"type": "object",
"additionalProperties": false,
"properties": {
"model": {
"type": [
"string",
"null"
]
},
"text": {
"type": "string"
},
"operationId": {
"type": "string"
},
"status": {
"type": [
"string",
"null"
]
},
"label": {
"type": [
"string",
"null"
]
},
"category": {
"type": [
"string",
"null"
]
},
"messageId": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
{
"description": "A file uploaded to a Session for its Turns.",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"sessionId",
"name",
"contentType",
"size",
"sha256",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^file_[0-9a-f]{32}$"
},
"sessionId": {
"type": "string",
"pattern": "^ses_[0-9a-f]{32}$",
"description": "The only Session whose Turns can use the file."
},
"name": {
"type": "string"
},
"contentType": {
"type": [
"string",
"null"
]
},
"size": {
"type": "integer",
"minimum": 1,
"description": "Bytes."
},
"sha256": {
"type": "string",
"pattern": "^[0-9a-f]{64}$",
"description": "Lowercase hexadecimal SHA-256 of the content."
},
"createdAt": {
"type": "string",
"format": "date-time"
}
}
}
{
"description": "A function your application executes for the Agent. The Agent sees the name, description and parameters as written.",
"type": "object",
"additionalProperties": false,
"required": [
"type",
"name",
"description",
"parameters"
],
"properties": {
"type": {
"type": "string",
"const": "function"
},
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,64}$",
"description": "Unique in the set and without `__`. Names of the platform's own tools and the `mcp_` and `device_` prefixes are reserved."
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"parameters": {
"type": "object",
"description": "A JSON Schema with `type: object`, at most 16 KiB and 16 levels deep. It may not define an `async` property: the platform adds that argument for the Agent to choose not to wait for the result, and never sends it to you."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"revision",
"tools"
],
"properties": {
"revision": {
"type": "integer",
"minimum": 0,
"description": "Increases with each replacement that changes the set; 0 before any."
},
"tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClientTool"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"tools"
],
"properties": {
"tools": {
"type": "array",
"maxItems": 64,
"description": "The whole new set, at most 64 KiB of JSON.",
"items": {
"$ref": "#/components/schemas/ClientTool"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"turnId",
"callId",
"name",
"arguments",
"publishedAt",
"deadlineAt"
],
"properties": {
"turnId": {
"type": "string"
},
"callId": {
"type": "string"
},
"name": {
"type": "string"
},
"arguments": {
"type": "object"
},
"publishedAt": {
"type": "string",
"format": "date-time"
},
"deadlineAt": {
"type": "string",
"format": "date-time"
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"calls"
],
"properties": {
"calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingClientToolCall"
}
}
}
}
{
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"callId",
"output"
],
"properties": {
"callId": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"output": {
"type": "string",
"maxLength": 65536,
"description": "What the tool returned, as text the Agent reads."
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"callId",
"error"
],
"properties": {
"callId": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Why the tool failed, for the Agent."
}
}
}
}
}
]
}
{
"type": "object",
"additionalProperties": false,
"required": [
"turnId",
"callId"
],
"properties": {
"turnId": {
"type": "string"
},
"callId": {
"type": "string"
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"description"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as `exampleId` to create an Agent from this example."
},
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"examples"
],
"properties": {
"examples": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OfficialExample"
}
}
}
}
{
"description": "An Agent as lists show it; read the Agent for its instructions.",
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"description",
"defaultModel",
"defaultRealtimeModel",
"exampleId",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^agt_[0-9a-f]{32}$"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"defaultModel": {
"type": [
"string",
"null"
],
"description": "The text model new Sessions of this Agent use; null uses the platform default."
},
"defaultRealtimeModel": {
"type": [
"string",
"null"
],
"description": "The Realtime model new Sessions use when the Agent has voice enabled; null uses the platform default. It has no effect while voice is off."
},
"exampleId": {
"type": [
"string",
"null"
],
"description": "The Official Example this Agent was copied from, if any."
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"description",
"defaultModel",
"defaultRealtimeModel",
"exampleId",
"instructions",
"voice",
"sessionRecall",
"skills",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"pattern": "^agt_[0-9a-f]{32}$"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"defaultModel": {
"type": [
"string",
"null"
],
"description": "The text model new Sessions of this Agent use; null uses the platform default."
},
"defaultRealtimeModel": {
"type": [
"string",
"null"
],
"description": "The Realtime model new Sessions use when the Agent has voice enabled; null uses the platform default. It has no effect while voice is off."
},
"exampleId": {
"type": [
"string",
"null"
],
"description": "The Official Example this Agent was copied from, if any."
},
"instructions": {
"type": "string"
},
"voice": {
"$ref": "#/components/schemas/Voice"
},
"sessionRecall": {
"type": "boolean",
"description": "Whether new Sessions can recall the Developer's earlier Sessions with this Agent."
},
"skills": {
"type": "array",
"description": "The Official Skills this Agent uses, each at the version it selected.",
"items": {
"$ref": "#/components/schemas/SelectedSkill"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
}
}
{
"description": "Voice (Realtime) for new Sessions; null is voice off. Sessions with voice use the Agent's `defaultRealtimeModel`.",
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"language",
"standingTask"
],
"properties": {
"language": {
"type": "string",
"enum": [
"zh-CN",
"en-US"
]
},
"standingTask": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 4000,
"description": "A goal the Agent keeps working on while a voice client is connected and the conversation gives it nothing else to do; null for none. Line endings become LF and surrounding whitespace is trimmed."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"version",
"name"
],
"properties": {
"id": {
"type": "string",
"pattern": "^osk_[0-9a-f]{32}$"
},
"version": {
"type": "integer",
"minimum": 1
},
"name": {
"type": "string"
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"version"
],
"properties": {
"id": {
"type": "string",
"pattern": "^osk_[0-9a-f]{32}$"
},
"version": {
"type": "integer",
"minimum": 1
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"description",
"version"
],
"properties": {
"id": {
"type": "string",
"pattern": "^osk_[0-9a-f]{32}$"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"version": {
"type": "integer",
"minimum": 1,
"description": "The version an Agent can select."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"skills"
],
"properties": {
"skills": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OfficialSkill"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"agents"
],
"properties": {
"agents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentSummary"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"description": "`name` is required for a blank Agent. For a copy, absent `name` and `description` take the Official Example's, as `GET /api/v1/examples` lists them.",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Surrounding whitespace is trimmed; control characters are refused."
},
"description": {
"type": "string",
"maxLength": 2000
},
"exampleId": {
"type": [
"string",
"null"
],
"description": "An Official Example id to copy; absent or null creates a blank Agent."
}
}
}
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Surrounding whitespace is trimmed; control characters are refused."
},
"description": {
"type": "string",
"maxLength": 2000
},
"instructions": {
"type": "string",
"description": "Line endings become LF and surrounding whitespace is trimmed; at most 16 KiB in UTF-8."
},
"defaultModel": {
"type": [
"string",
"null"
],
"pattern": "^[!-~]{1,128}$",
"description": "A model id for new Sessions; null returns to the platform default. Availability is checked when a Session is created."
},
"defaultRealtimeModel": {
"type": [
"string",
"null"
],
"pattern": "^[!-~]{1,128}$",
"description": "A Realtime model id for new voice Sessions; null returns to the platform default. Availability is checked when a Session is created."
},
"voice": {
"$ref": "#/components/schemas/Voice"
},
"sessionRecall": {
"type": "boolean"
},
"skills": {
"type": "array",
"maxItems": 100,
"description": "The complete selection, each Official Skill at most once. Together with any Skills a copied Official Example brought that are not Official Skills, which the Agent keeps, an Agent has at most 100 Skills.",
"items": {
"$ref": "#/components/schemas/SkillSelection"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"label",
"available"
],
"properties": {
"id": {
"type": "string",
"description": "The id to set as an Agent's default model."
},
"label": {
"type": "string",
"description": "A display name."
},
"available": {
"type": "boolean",
"description": "Whether the platform can serve it now."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"label",
"available",
"languages"
],
"properties": {
"id": {
"type": "string",
"description": "The id to set as an Agent's default Realtime model."
},
"label": {
"type": "string",
"description": "A display name."
},
"available": {
"type": "boolean",
"description": "Whether the platform can serve it now."
},
"languages": {
"type": "array",
"description": "The voice languages it serves.",
"items": {
"type": "string",
"enum": [
"zh-CN",
"en-US"
]
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"defaultModel",
"models",
"defaultRealtimeModel",
"realtimeModels"
],
"properties": {
"defaultModel": {
"type": "string",
"description": "The platform's suggested text model, which new Sessions normally use when the Agent's `defaultModel` is null."
},
"models": {
"type": "array",
"description": "Text models.",
"items": {
"$ref": "#/components/schemas/Model"
}
},
"defaultRealtimeModel": {
"type": [
"string",
"null"
],
"description": "The Realtime model voice Sessions use when the Agent's `defaultRealtimeModel` is null; null when the platform has none."
},
"realtimeModels": {
"type": "array",
"description": "Realtime models.",
"items": {
"$ref": "#/components/schemas/RealtimeModel"
}
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"developerId"
],
"properties": {
"developerId": {
"type": "string",
"pattern": "^dev_[0-9a-f]{32}$",
"description": "The Developer's DevHub id."
}
}
}
{
"type": "object",
"additionalProperties": false,
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable code; clients branch on this, not on the message.",
"enum": [
"authentication_required",
"not_found",
"invalid_request",
"idempotency_key_reused",
"conflict",
"session_has_active_turn",
"session_read_only",
"configuration_unavailable",
"client_tool_call_settled",
"precondition_failed",
"file_too_large",
"credits_exhausted",
"credits_unavailable",
"service_unavailable",
"internal_error"
]
},
"message": {
"type": "string",
"description": "Human-readable explanation; may change."
},
"resetsAt": {
"type": "string",
"format": "date-time",
"description": "Only with `credits_exhausted`; when your Credits reset."
}
}
}
}
}