feat(2/n): agent return turn awaiting input for tool calls

docs/_static/llama-stack-spec.html

@@ -2319,7 +2319,7 @@
             "post": {
                 "responses": {
                     "200": {
-                        "description": "A single turn in an interaction with an Agentic System. **OR** streamed agent turn completion response.",
+                        "description": "A Turn object if stream is False, otherwise an AsyncIterator of AgentTurnResponseStreamChunk objects.",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -2337,11 +2337,12 @@
                 "tags": [
                     "Agents"
                 ],
-                "description": "",
+                "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"
@@ -2350,6 +2351,7 @@
                     {
                         "name": "session_id",
                         "in": "path",
+                        "description": "The ID of the session to resume.",
                         "required": true,
                         "schema": {
                             "type": "string"
@@ -2358,6 +2360,7 @@
                     {
                         "name": "turn_id",
                         "in": "path",
+                        "description": "The ID of the turn to resume.",
                         "required": true,
                         "schema": {
                             "type": "string"
@@ -4287,6 +4290,9 @@
                     },
                     "tool_config": {
                         "$ref": "#/components/schemas/ToolConfig"
+                    },
+                    "allow_turn_resume": {
+                        "type": "boolean"
                     }
                 },
                 "additionalProperties": false,
@@ -8106,10 +8112,12 @@
                         "type": "array",
                         "items": {
                             "$ref": "#/components/schemas/ToolResponseMessage"
-                        }
+                        },
+                        "description": "The tool call responses to resume the turn with."
                     },
                     "stream": {
-                        "type": "boolean"
+                        "type": "boolean",
+                        "description": "Whether to stream the response."
                     }
                 },
                 "additionalProperties": false,

docs/_static/llama-stack-spec.yaml

@@ -1406,8 +1406,8 @@ paths:
       responses:
         '200':
           description: >-
-            A single turn in an interaction with an Agentic System. **OR** streamed
-            agent turn completion response.
+            A Turn object if stream is False, otherwise an AsyncIterator of AgentTurnResponseStreamChunk
+            objects.
           content:
             application/json:
               schema:
@@ -1417,20 +1417,28 @@ paths:
                 $ref: '#/components/schemas/AgentTurnResponseStreamChunk'
       tags:
         - Agents
-      description: ''
+      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
@@ -2779,6 +2787,8 @@ components:
             $ref: '#/components/schemas/AgentTool'
         tool_config:
           $ref: '#/components/schemas/ToolConfig'
+        allow_turn_resume:
+          type: boolean
       additionalProperties: false
       required:
         - messages
@@ -5242,8 +5252,11 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/ToolResponseMessage'
+          description: >-
+            The tool call responses to resume the turn with.
         stream:
           type: boolean
+          description: Whether to stream the response.
       additionalProperties: false
       required:
         - tool_responses

llama_stack/apis/agents/agents.py

@@ -296,6 +296,9 @@ class AgentTurnCreateRequest(AgentConfigOverridablePerTurn):
     stream: Optional[bool] = False
     tool_config: Optional[ToolConfig] = None
 
+    # TODO (xiyan): temporary flag, will remove for 0.1.5
+    allow_turn_resume: Optional[bool] = False
+
 
 @json_schema_type
 class AgentTurnResumeRequest(BaseModel):
@@ -352,6 +355,7 @@ async def create_agent_turn(
         documents: Optional[List[Document]] = None,
         toolgroups: Optional[List[AgentToolGroup]] = None,
         tool_config: Optional[ToolConfig] = None,
+        allow_turn_resume: Optional[bool] = False,
     ) -> Union[Turn, AsyncIterator[AgentTurnResponseStreamChunk]]: ...
 
     @webmethod(
@@ -365,7 +369,19 @@ async def resume_agent_turn(
         turn_id: str,
         tool_responses: List[ToolResponseMessage],
         stream: Optional[bool] = False,
-    ) -> Union[Turn, AsyncIterator[AgentTurnResponseStreamChunk]]: ...
+    ) -> Union[Turn, AsyncIterator[AgentTurnResponseStreamChunk]]:
+        """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.
+
+        :param agent_id: The ID of the agent to resume.
+        :param session_id: The ID of the session to resume.
+        :param turn_id: The ID of the turn to resume.
+        :param tool_responses: The tool call responses to resume the turn with.
+        :param stream: Whether to stream the response.
+        :returns: A Turn object if stream is False, otherwise an AsyncIterator of AgentTurnResponseStreamChunk objects.
+        """
+        ...
 
     @webmethod(
         route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}",