From 1e25a72ece277a6460cdf330a0ceda1f3fcf1a68 Mon Sep 17 00:00:00 2001 From: Charlie Doern Date: Tue, 30 Sep 2025 14:15:04 -0400 Subject: [PATCH] feat(api): level /agents as `v1alpha` (#3610) # What does this PR do? agents is likely to be deprecated in favor of responses. Lets level it as alpha to indicate the lack of longterm support keep v1 route for backwards compat. Closes #3611 Signed-off-by: Charlie Doern --- docs/static/llama-stack-spec.html | 677 ++++++++++++++++++++++++++++++ docs/static/llama-stack-spec.yaml | 485 +++++++++++++++++++++ llama_stack/apis/agents/agents.py | 60 ++- 3 files changed, 1214 insertions(+), 8 deletions(-) diff --git a/docs/static/llama-stack-spec.html b/docs/static/llama-stack-spec.html index d46e54011..c755af948 100644 --- a/docs/static/llama-stack-spec.html +++ b/docs/static/llama-stack-spec.html @@ -161,6 +161,101 @@ } } }, + "/v1alpha/agents": { + "get": { + "responses": { + "200": { + "description": "A PaginatedResponse.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaginatedResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "List all agents.", + "description": "List all agents.", + "parameters": [ + { + "name": "start_index", + "in": "query", + "description": "The index to start the pagination from.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "limit", + "in": "query", + "description": "The number of agents to return.", + "required": false, + "schema": { + "type": "integer" + } + } + ] + }, + "post": { + "responses": { + "200": { + "description": "An AgentCreateResponse with the agent ID.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentCreateResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Create an agent with the given configuration.", + "description": "Create an agent with the given configuration.", + "parameters": [], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAgentRequest" + } + } + }, + "required": true + } + } + }, "/v1/agents": { "get": { "responses": { @@ -256,6 +351,60 @@ } } }, + "/v1alpha/agents/{agent_id}/session": { + "post": { + "responses": { + "200": { + "description": "An AgentSessionCreateResponse.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentSessionCreateResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Create a new session for an agent.", + "description": "Create a new session for an agent.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to create the session for.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAgentSessionRequest" + } + } + }, + "required": true + } + } + }, "/v1/agents/{agent_id}/session": { "post": { "responses": { @@ -310,6 +459,74 @@ } } }, + "/v1alpha/agents/{agent_id}/session/{session_id}/turn": { + "post": { + "responses": { + "200": { + "description": "If stream=False, returns a Turn object. If stream=True, returns an SSE event stream of AgentTurnResponseStreamChunk.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Turn" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/AgentTurnResponseStreamChunk" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Create a new turn for an agent.", + "description": "Create a new turn for an agent.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to create the turn for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "session_id", + "in": "path", + "description": "The ID of the session to create the turn for.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateAgentTurnRequest" + } + } + }, + "required": true + } + } + }, "/v1/agents/{agent_id}/session/{session_id}/turn": { "post": { "responses": { @@ -572,6 +789,85 @@ } } }, + "/v1alpha/agents/{agent_id}": { + "get": { + "responses": { + "200": { + "description": "An Agent of the agent.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Agent" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Describe an agent by its ID.", + "description": "Describe an agent by its ID.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "ID of the agent.", + "required": true, + "schema": { + "type": "string" + } + } + ] + }, + "delete": { + "responses": { + "200": { + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Delete an agent by its ID and its associated sessions and turns.", + "description": "Delete an agent by its ID and its associated sessions and turns.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to delete.", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, "/v1/agents/{agent_id}": { "get": { "responses": { @@ -651,6 +947,115 @@ ] } }, + "/v1alpha/agents/{agent_id}/session/{session_id}": { + "get": { + "responses": { + "200": { + "description": "A Session.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Session" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Retrieve an agent session by its ID.", + "description": "Retrieve an agent session by its ID.", + "parameters": [ + { + "name": "session_id", + "in": "path", + "description": "The ID of the session to get.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to get the session for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "turn_ids", + "in": "query", + "description": "(Optional) List of turn IDs to filter the session by.", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ] + }, + "delete": { + "responses": { + "200": { + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Delete an agent session by its ID and its associated turns.", + "description": "Delete an agent session by its ID and its associated turns.", + "parameters": [ + { + "name": "session_id", + "in": "path", + "description": "The ID of the session to delete.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to delete the session for.", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, "/v1/agents/{agent_id}/session/{session_id}": { "get": { "responses": { @@ -1094,6 +1499,77 @@ } } }, + "/v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}": { + "get": { + "responses": { + "200": { + "description": "An AgentStepResponse.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentStepResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Retrieve an agent step by its ID.", + "description": "Retrieve an agent step by its ID.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to get the step for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "session_id", + "in": "path", + "description": "The ID of the session to get the step for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "turn_id", + "in": "path", + "description": "The ID of the turn to get the step for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "step_id", + "in": "path", + "description": "The ID of the step to get.", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, "/v1/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}": { "get": { "responses": { @@ -1165,6 +1641,68 @@ ] } }, + "/v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}": { + "get": { + "responses": { + "200": { + "description": "A Turn.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Turn" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Retrieve an agent turn by its ID.", + "description": "Retrieve an agent turn by its ID.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to get the turn for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "session_id", + "in": "path", + "description": "The ID of the session to get the turn for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "turn_id", + "in": "path", + "description": "The ID of the turn to get.", + "required": true, + "schema": { + "type": "string" + } + } + ] + } + }, "/v1/agents/{agent_id}/session/{session_id}/turn/{turn_id}": { "get": { "responses": { @@ -2900,6 +3438,68 @@ ] } }, + "/v1alpha/agents/{agent_id}/sessions": { + "get": { + "responses": { + "200": { + "description": "A PaginatedResponse.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PaginatedResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "List all session(s) of a given agent.", + "description": "List all session(s) of a given agent.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to list sessions for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "start_index", + "in": "query", + "description": "The index to start the pagination from.", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "limit", + "in": "query", + "description": "The number of sessions to return.", + "required": false, + "schema": { + "type": "integer" + } + } + ] + } + }, "/v1/agents/{agent_id}/sessions": { "get": { "responses": { @@ -5373,6 +5973,83 @@ } } }, + "/v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume": { + "post": { + "responses": { + "200": { + "description": "A Turn object if stream is False, otherwise an AsyncIterator of AgentTurnResponseStreamChunk objects.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Turn" + } + }, + "text/event-stream": { + "schema": { + "$ref": "#/components/schemas/AgentTurnResponseStreamChunk" + } + } + } + }, + "400": { + "$ref": "#/components/responses/BadRequest400" + }, + "429": { + "$ref": "#/components/responses/TooManyRequests429" + }, + "500": { + "$ref": "#/components/responses/InternalServerError500" + }, + "default": { + "$ref": "#/components/responses/DefaultError" + } + }, + "tags": [ + "Agents" + ], + "summary": "Resume an agent turn with executed tool call responses.", + "description": "Resume an agent turn with executed tool call responses.\nWhen a Turn has the status `awaiting_input` due to pending input from client side tool calls, this endpoint can be used to submit the outputs from the tool calls once they are ready.", + "parameters": [ + { + "name": "agent_id", + "in": "path", + "description": "The ID of the agent to resume.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "session_id", + "in": "path", + "description": "The ID of the session to resume.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "turn_id", + "in": "path", + "description": "The ID of the turn to resume.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResumeAgentTurnRequest" + } + } + }, + "required": true + } + } + }, "/v1/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume": { "post": { "responses": { diff --git a/docs/static/llama-stack-spec.yaml b/docs/static/llama-stack-spec.yaml index 98b790a49..901bade95 100644 --- a/docs/static/llama-stack-spec.yaml +++ b/docs/static/llama-stack-spec.yaml @@ -95,6 +95,74 @@ paths: schema: $ref: '#/components/schemas/CancelTrainingJobRequest' required: true + /v1alpha/agents: + get: + responses: + '200': + description: A PaginatedResponse. + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedResponse' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: List all agents. + description: List all agents. + parameters: + - name: start_index + in: query + description: The index to start the pagination from. + required: false + schema: + type: integer + - name: limit + in: query + description: The number of agents to return. + required: false + schema: + type: integer + post: + responses: + '200': + description: >- + An AgentCreateResponse with the agent ID. + content: + application/json: + schema: + $ref: '#/components/schemas/AgentCreateResponse' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: >- + Create an agent with the given configuration. + description: >- + Create an agent with the given configuration. + parameters: [] + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAgentRequest' + required: true /v1/agents: get: responses: @@ -163,6 +231,43 @@ paths: schema: $ref: '#/components/schemas/CreateAgentRequest' required: true + /v1alpha/agents/{agent_id}/session: + post: + responses: + '200': + description: An AgentSessionCreateResponse. + content: + application/json: + schema: + $ref: '#/components/schemas/AgentSessionCreateResponse' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: Create a new session for an agent. + description: Create a new session for an agent. + parameters: + - name: agent_id + in: path + description: >- + The ID of the agent to create the session for. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAgentSessionRequest' + required: true /v1/agents/{agent_id}/session: post: responses: @@ -200,6 +305,55 @@ paths: schema: $ref: '#/components/schemas/CreateAgentSessionRequest' required: true + /v1alpha/agents/{agent_id}/session/{session_id}/turn: + post: + responses: + '200': + description: >- + If stream=False, returns a Turn object. If stream=True, returns an SSE + event stream of AgentTurnResponseStreamChunk. + content: + application/json: + schema: + $ref: '#/components/schemas/Turn' + text/event-stream: + schema: + $ref: '#/components/schemas/AgentTurnResponseStreamChunk' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: Create a new turn for an agent. + description: Create a new turn for an agent. + parameters: + - name: agent_id + in: path + description: >- + The ID of the agent to create the turn for. + required: true + schema: + type: string + - name: session_id + in: path + description: >- + The ID of the session to create the turn for. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAgentTurnRequest' + required: true /v1/agents/{agent_id}/session/{session_id}/turn: post: responses: @@ -384,6 +538,63 @@ paths: schema: $ref: '#/components/schemas/CreatePromptRequest' required: true + /v1alpha/agents/{agent_id}: + get: + responses: + '200': + description: An Agent of the agent. + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: Describe an agent by its ID. + description: Describe an agent by its ID. + parameters: + - name: agent_id + in: path + description: ID of the agent. + required: true + schema: + type: string + delete: + responses: + '200': + description: OK + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: >- + Delete an agent by its ID and its associated sessions and turns. + description: >- + Delete an agent by its ID and its associated sessions and turns. + parameters: + - name: agent_id + in: path + description: The ID of the agent to delete. + required: true + schema: + type: string /v1/agents/{agent_id}: get: responses: @@ -441,6 +652,86 @@ paths: required: true schema: type: string + /v1alpha/agents/{agent_id}/session/{session_id}: + get: + responses: + '200': + description: A Session. + content: + application/json: + schema: + $ref: '#/components/schemas/Session' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: Retrieve an agent session by its ID. + description: Retrieve an agent session by its ID. + parameters: + - name: session_id + in: path + description: The ID of the session to get. + required: true + schema: + type: string + - name: agent_id + in: path + description: >- + The ID of the agent to get the session for. + required: true + schema: + type: string + - name: turn_ids + in: query + description: >- + (Optional) List of turn IDs to filter the session by. + required: false + schema: + type: array + items: + type: string + delete: + responses: + '200': + description: OK + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: >- + Delete an agent session by its ID and its associated turns. + description: >- + Delete an agent session by its ID and its associated turns. + parameters: + - name: session_id + in: path + description: The ID of the session to delete. + required: true + schema: + type: string + - name: agent_id + in: path + description: >- + The ID of the agent to delete the session for. + required: true + schema: + type: string /v1/agents/{agent_id}/session/{session_id}: get: responses: @@ -759,6 +1050,55 @@ paths: schema: $ref: '#/components/schemas/EvaluateRowsRequest' required: true + /v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}: + get: + responses: + '200': + description: An AgentStepResponse. + content: + application/json: + schema: + $ref: '#/components/schemas/AgentStepResponse' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: Retrieve an agent step by its ID. + description: Retrieve an agent step by its ID. + parameters: + - name: agent_id + in: path + description: The ID of the agent to get the step for. + required: true + schema: + type: string + - name: session_id + in: path + description: >- + The ID of the session to get the step for. + required: true + schema: + type: string + - name: turn_id + in: path + description: The ID of the turn to get the step for. + required: true + schema: + type: string + - name: step_id + in: path + description: The ID of the step to get. + required: true + schema: + type: string /v1/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}: get: responses: @@ -808,6 +1148,49 @@ paths: required: true schema: type: string + /v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}: + get: + responses: + '200': + description: A Turn. + content: + application/json: + schema: + $ref: '#/components/schemas/Turn' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: Retrieve an agent turn by its ID. + description: Retrieve an agent turn by its ID. + parameters: + - name: agent_id + in: path + description: The ID of the agent to get the turn for. + required: true + schema: + type: string + - name: session_id + in: path + description: >- + The ID of the session to get the turn for. + required: true + schema: + type: string + - name: turn_id + in: path + description: The ID of the turn to get. + required: true + schema: + type: string /v1/agents/{agent_id}/session/{session_id}/turn/{turn_id}: get: responses: @@ -2046,6 +2429,49 @@ paths: required: true schema: type: string + /v1alpha/agents/{agent_id}/sessions: + get: + responses: + '200': + description: A PaginatedResponse. + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedResponse' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: List all session(s) of a given agent. + description: List all session(s) of a given agent. + parameters: + - name: agent_id + in: path + description: >- + The ID of the agent to list sessions for. + required: true + schema: + type: string + - name: start_index + in: query + description: The index to start the pagination from. + required: false + schema: + type: integer + - name: limit + in: query + description: The number of sessions to return. + required: false + schema: + type: integer /v1/agents/{agent_id}/sessions: get: responses: @@ -3857,6 +4283,65 @@ paths: schema: $ref: '#/components/schemas/RerankRequest' required: true + /v1alpha/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume: + post: + responses: + '200': + description: >- + A Turn object if stream is False, otherwise an AsyncIterator of AgentTurnResponseStreamChunk + objects. + content: + application/json: + schema: + $ref: '#/components/schemas/Turn' + text/event-stream: + schema: + $ref: '#/components/schemas/AgentTurnResponseStreamChunk' + '400': + $ref: '#/components/responses/BadRequest400' + '429': + $ref: >- + #/components/responses/TooManyRequests429 + '500': + $ref: >- + #/components/responses/InternalServerError500 + default: + $ref: '#/components/responses/DefaultError' + tags: + - Agents + summary: >- + Resume an agent turn with executed tool call responses. + description: >- + Resume an agent turn with executed tool call responses. + + When a Turn has the status `awaiting_input` due to pending input from client + side tool calls, this endpoint can be used to submit the outputs from the + tool calls once they are ready. + parameters: + - name: agent_id + in: path + description: The ID of the agent to resume. + required: true + schema: + type: string + - name: session_id + in: path + description: The ID of the session to resume. + required: true + schema: + type: string + - name: turn_id + in: path + description: The ID of the turn to resume. + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ResumeAgentTurnRequest' + required: true /v1/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume: post: responses: diff --git a/llama_stack/apis/agents/agents.py b/llama_stack/apis/agents/agents.py index e8d0c467a..f732dd1ed 100644 --- a/llama_stack/apis/agents/agents.py +++ b/llama_stack/apis/agents/agents.py @@ -27,7 +27,7 @@ from llama_stack.apis.inference import ( ) from llama_stack.apis.safety import SafetyViolation from llama_stack.apis.tools import ToolDef -from llama_stack.apis.version import LLAMA_STACK_API_V1 +from llama_stack.apis.version import LLAMA_STACK_API_V1, LLAMA_STACK_API_V1ALPHA from llama_stack.schema_utils import json_schema_type, register_schema, webmethod from .openai_responses import ( @@ -482,7 +482,10 @@ class Agents(Protocol): - Agents can also use Memory to retrieve information from knowledge bases. See the RAG Tool and Vector IO APIs for more details. """ - @webmethod(route="/agents", method="POST", descriptive_name="create_agent", level=LLAMA_STACK_API_V1) + @webmethod( + route="/agents", method="POST", descriptive_name="create_agent", deprecated=True, level=LLAMA_STACK_API_V1 + ) + @webmethod(route="/agents", method="POST", descriptive_name="create_agent", level=LLAMA_STACK_API_V1ALPHA) async def create_agent( self, agent_config: AgentConfig, @@ -498,8 +501,15 @@ class Agents(Protocol): route="/agents/{agent_id}/session/{session_id}/turn", method="POST", descriptive_name="create_agent_turn", + deprecated=True, level=LLAMA_STACK_API_V1, ) + @webmethod( + route="/agents/{agent_id}/session/{session_id}/turn", + method="POST", + descriptive_name="create_agent_turn", + level=LLAMA_STACK_API_V1ALPHA, + ) async def create_agent_turn( self, agent_id: str, @@ -528,8 +538,15 @@ class Agents(Protocol): route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume", method="POST", descriptive_name="resume_agent_turn", + deprecated=True, level=LLAMA_STACK_API_V1, ) + @webmethod( + route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume", + method="POST", + descriptive_name="resume_agent_turn", + level=LLAMA_STACK_API_V1ALPHA, + ) async def resume_agent_turn( self, agent_id: str, @@ -554,8 +571,14 @@ class Agents(Protocol): @webmethod( route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}", method="GET", + deprecated=True, level=LLAMA_STACK_API_V1, ) + @webmethod( + route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}", + method="GET", + level=LLAMA_STACK_API_V1ALPHA, + ) async def get_agents_turn( self, agent_id: str, @@ -574,8 +597,14 @@ class Agents(Protocol): @webmethod( route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}", method="GET", + deprecated=True, level=LLAMA_STACK_API_V1, ) + @webmethod( + route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}", + method="GET", + level=LLAMA_STACK_API_V1ALPHA, + ) async def get_agents_step( self, agent_id: str, @@ -597,8 +626,15 @@ class Agents(Protocol): route="/agents/{agent_id}/session", method="POST", descriptive_name="create_agent_session", + deprecated=True, level=LLAMA_STACK_API_V1, ) + @webmethod( + route="/agents/{agent_id}/session", + method="POST", + descriptive_name="create_agent_session", + level=LLAMA_STACK_API_V1ALPHA, + ) async def create_agent_session( self, agent_id: str, @@ -612,7 +648,8 @@ class Agents(Protocol): """ ... - @webmethod(route="/agents/{agent_id}/session/{session_id}", method="GET", level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}/session/{session_id}", method="GET", deprecated=True, level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}/session/{session_id}", method="GET", level=LLAMA_STACK_API_V1ALPHA) async def get_agents_session( self, session_id: str, @@ -628,7 +665,10 @@ class Agents(Protocol): """ ... - @webmethod(route="/agents/{agent_id}/session/{session_id}", method="DELETE", level=LLAMA_STACK_API_V1) + @webmethod( + route="/agents/{agent_id}/session/{session_id}", method="DELETE", deprecated=True, level=LLAMA_STACK_API_V1 + ) + @webmethod(route="/agents/{agent_id}/session/{session_id}", method="DELETE", level=LLAMA_STACK_API_V1ALPHA) async def delete_agents_session( self, session_id: str, @@ -641,7 +681,8 @@ class Agents(Protocol): """ ... - @webmethod(route="/agents/{agent_id}", method="DELETE", level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}", method="DELETE", deprecated=True, level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}", method="DELETE", level=LLAMA_STACK_API_V1ALPHA) async def delete_agent( self, agent_id: str, @@ -652,7 +693,8 @@ class Agents(Protocol): """ ... - @webmethod(route="/agents", method="GET", level=LLAMA_STACK_API_V1) + @webmethod(route="/agents", method="GET", deprecated=True, level=LLAMA_STACK_API_V1) + @webmethod(route="/agents", method="GET", level=LLAMA_STACK_API_V1ALPHA) async def list_agents(self, start_index: int | None = None, limit: int | None = None) -> PaginatedResponse: """List all agents. @@ -662,7 +704,8 @@ class Agents(Protocol): """ ... - @webmethod(route="/agents/{agent_id}", method="GET", level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}", method="GET", deprecated=True, level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}", method="GET", level=LLAMA_STACK_API_V1ALPHA) async def get_agent(self, agent_id: str) -> Agent: """Describe an agent by its ID. @@ -671,7 +714,8 @@ class Agents(Protocol): """ ... - @webmethod(route="/agents/{agent_id}/sessions", method="GET", level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}/sessions", method="GET", deprecated=True, level=LLAMA_STACK_API_V1) + @webmethod(route="/agents/{agent_id}/sessions", method="GET", level=LLAMA_STACK_API_V1ALPHA) async def list_agent_sessions( self, agent_id: str,