diff --git a/docs/_static/llama-stack-spec.html b/docs/_static/llama-stack-spec.html
index 643e1faee..16847f542 100644
--- a/docs/_static/llama-stack-spec.html
+++ b/docs/_static/llama-stack-spec.html
@@ -362,7 +362,7 @@
"post": {
"responses": {
"200": {
- "description": "OK",
+ "description": "An AgentCreateResponse with the agent ID.",
"content": {
"application/json": {
"schema": {
@@ -387,7 +387,7 @@
"tags": [
"Agents"
],
- "description": "",
+ "description": "Create an agent with the given configuration.",
"parameters": [],
"requestBody": {
"content": {
@@ -405,7 +405,7 @@
"post": {
"responses": {
"200": {
- "description": "OK",
+ "description": "An AgentSessionCreateResponse.",
"content": {
"application/json": {
"schema": {
@@ -430,11 +430,12 @@
"tags": [
"Agents"
],
- "description": "",
+ "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"
@@ -457,7 +458,7 @@
"post": {
"responses": {
"200": {
- "description": "A single turn in an interaction with an Agentic System. **OR** streamed agent turn completion response.",
+ "description": "If stream=False, returns a Turn object. If stream=True, returns an SSE event stream of AgentTurnResponseStreamChunk",
"content": {
"application/json": {
"schema": {
@@ -487,11 +488,12 @@
"tags": [
"Agents"
],
- "description": "",
+ "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"
@@ -500,6 +502,7 @@
{
"name": "session_id",
"in": "path",
+ "description": "The ID of the session to create the turn for.",
"required": true,
"schema": {
"type": "string"
@@ -623,11 +626,12 @@
"tags": [
"Agents"
],
- "description": "",
+ "description": "Delete an agent by its ID.",
"parameters": [
{
"name": "agent_id",
"in": "path",
+ "description": "The ID of the agent to delete.",
"required": true,
"schema": {
"type": "string"
@@ -665,11 +669,12 @@
"tags": [
"Agents"
],
- "description": "",
+ "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"
@@ -678,6 +683,7 @@
{
"name": "agent_id",
"in": "path",
+ "description": "The ID of the agent to get the session for.",
"required": true,
"schema": {
"type": "string"
@@ -686,6 +692,7 @@
{
"name": "turn_ids",
"in": "query",
+ "description": "(Optional) List of turn IDs to filter the session by.",
"required": false,
"schema": {
"type": "array",
@@ -717,11 +724,12 @@
"tags": [
"Agents"
],
- "description": "",
+ "description": "Delete an agent session by its ID.",
"parameters": [
{
"name": "session_id",
"in": "path",
+ "description": "The ID of the session to delete.",
"required": true,
"schema": {
"type": "string"
@@ -730,6 +738,7 @@
{
"name": "agent_id",
"in": "path",
+ "description": "The ID of the agent to delete the session for.",
"required": true,
"schema": {
"type": "string"
@@ -939,7 +948,7 @@
"get": {
"responses": {
"200": {
- "description": "OK",
+ "description": "An AgentStepResponse.",
"content": {
"application/json": {
"schema": {
@@ -964,11 +973,12 @@
"tags": [
"Agents"
],
- "description": "",
+ "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"
@@ -977,6 +987,7 @@
{
"name": "session_id",
"in": "path",
+ "description": "The ID of the session to get the step for.",
"required": true,
"schema": {
"type": "string"
@@ -985,6 +996,7 @@
{
"name": "turn_id",
"in": "path",
+ "description": "The ID of the turn to get the step for.",
"required": true,
"schema": {
"type": "string"
@@ -993,6 +1005,7 @@
{
"name": "step_id",
"in": "path",
+ "description": "The ID of the step to get.",
"required": true,
"schema": {
"type": "string"
@@ -1005,7 +1018,7 @@
"get": {
"responses": {
"200": {
- "description": "OK",
+ "description": "A Turn.",
"content": {
"application/json": {
"schema": {
@@ -1030,11 +1043,12 @@
"tags": [
"Agents"
],
- "description": "",
+ "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"
@@ -1043,6 +1057,7 @@
{
"name": "session_id",
"in": "path",
+ "description": "The ID of the session to get the turn for.",
"required": true,
"schema": {
"type": "string"
@@ -1051,6 +1066,7 @@
{
"name": "turn_id",
"in": "path",
+ "description": "The ID of the turn to get.",
"required": true,
"schema": {
"type": "string"
@@ -5192,7 +5208,8 @@
"type": "object",
"properties": {
"agent_config": {
- "$ref": "#/components/schemas/AgentConfig"
+ "$ref": "#/components/schemas/AgentConfig",
+ "description": "The configuration for the agent."
}
},
"additionalProperties": false,
@@ -5218,7 +5235,8 @@
"type": "object",
"properties": {
"session_name": {
- "type": "string"
+ "type": "string",
+ "description": "The name of the session to create."
}
},
"additionalProperties": false,
@@ -5254,10 +5272,12 @@
"$ref": "#/components/schemas/ToolResponseMessage"
}
]
- }
+ },
+ "description": "List of messages to start the turn with."
},
"stream": {
- "type": "boolean"
+ "type": "boolean",
+ "description": "(Optional) If True, generate an SSE event stream of the response. Defaults to False."
},
"documents": {
"type": "array",
@@ -5281,10 +5301,12 @@
{
"$ref": "#/components/schemas/URL"
}
- ]
+ ],
+ "description": "The content of the document."
},
"mime_type": {
- "type": "string"
+ "type": "string",
+ "description": "The MIME type of the document."
}
},
"additionalProperties": false,
@@ -5292,17 +5314,21 @@
"content",
"mime_type"
],
- "title": "Document"
- }
+ "title": "Document",
+ "description": "A document to be used by an agent."
+ },
+ "description": "(Optional) List of documents to create the turn with."
},
"toolgroups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AgentTool"
- }
+ },
+ "description": "(Optional) List of toolgroups to create the turn with, will be used in addition to the agent's config toolgroups for the request."
},
"tool_config": {
- "$ref": "#/components/schemas/ToolConfig"
+ "$ref": "#/components/schemas/ToolConfig",
+ "description": "(Optional) The tool configuration to create the turn with, will be used to override the agent's tool_config."
}
},
"additionalProperties": false,
@@ -5315,18 +5341,22 @@
"type": "object",
"properties": {
"turn_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the turn."
},
"step_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the step."
},
"started_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step started."
},
"completed_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step completed."
},
"step_type": {
"type": "string",
@@ -5334,7 +5364,8 @@
"default": "inference"
},
"model_response": {
- "$ref": "#/components/schemas/CompletionMessage"
+ "$ref": "#/components/schemas/CompletionMessage",
+ "description": "The response from the LLM."
}
},
"additionalProperties": false,
@@ -5344,24 +5375,29 @@
"step_type",
"model_response"
],
- "title": "InferenceStep"
+ "title": "InferenceStep",
+ "description": "An inference step in an agent turn."
},
"MemoryRetrievalStep": {
"type": "object",
"properties": {
"turn_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the turn."
},
"step_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the step."
},
"started_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step started."
},
"completed_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step completed."
},
"step_type": {
"type": "string",
@@ -5369,10 +5405,12 @@
"default": "memory_retrieval"
},
"vector_db_ids": {
- "type": "string"
+ "type": "string",
+ "description": "The IDs of the vector databases to retrieve context from."
},
"inserted_context": {
- "$ref": "#/components/schemas/InterleavedContent"
+ "$ref": "#/components/schemas/InterleavedContent",
+ "description": "The context retrieved from the vector databases."
}
},
"additionalProperties": false,
@@ -5383,7 +5421,8 @@
"vector_db_ids",
"inserted_context"
],
- "title": "MemoryRetrievalStep"
+ "title": "MemoryRetrievalStep",
+ "description": "A memory retrieval step in an agent turn."
},
"SafetyViolation": {
"type": "object",
@@ -5431,18 +5470,22 @@
"type": "object",
"properties": {
"turn_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the turn."
},
"step_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the step."
},
"started_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step started."
},
"completed_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step completed."
},
"step_type": {
"type": "string",
@@ -5450,7 +5493,8 @@
"default": "shield_call"
},
"violation": {
- "$ref": "#/components/schemas/SafetyViolation"
+ "$ref": "#/components/schemas/SafetyViolation",
+ "description": "The violation from the shield call."
}
},
"additionalProperties": false,
@@ -5459,24 +5503,29 @@
"step_id",
"step_type"
],
- "title": "ShieldCallStep"
+ "title": "ShieldCallStep",
+ "description": "A shield call step in an agent turn."
},
"ToolExecutionStep": {
"type": "object",
"properties": {
"turn_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the turn."
},
"step_id": {
- "type": "string"
+ "type": "string",
+ "description": "The ID of the step."
},
"started_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step started."
},
"completed_at": {
"type": "string",
- "format": "date-time"
+ "format": "date-time",
+ "description": "The time the step completed."
},
"step_type": {
"type": "string",
@@ -5487,13 +5536,15 @@
"type": "array",
"items": {
"$ref": "#/components/schemas/ToolCall"
- }
+ },
+ "description": "The tool calls to execute."
},
"tool_responses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToolResponse"
- }
+ },
+ "description": "The tool responses from the tool calls."
}
},
"additionalProperties": false,
@@ -5504,7 +5555,8 @@
"tool_calls",
"tool_responses"
],
- "title": "ToolExecutionStep"
+ "title": "ToolExecutionStep",
+ "description": "A tool execution step in an agent turn."
},
"ToolResponse": {
"type": "object",
@@ -5641,10 +5693,12 @@
{
"$ref": "#/components/schemas/URL"
}
- ]
+ ],
+ "description": "The content of the attachment."
},
"mime_type": {
- "type": "string"
+ "type": "string",
+ "description": "The MIME type of the attachment."
}
},
"additionalProperties": false,
@@ -5652,7 +5706,8 @@
"content",
"mime_type"
],
- "title": "Attachment"
+ "title": "Attachment",
+ "description": "An attachment to an agent turn."
}
},
"started_at": {
@@ -5747,7 +5802,8 @@
"shield_call",
"memory_retrieval"
],
- "title": "StepType"
+ "title": "StepType",
+ "description": "Type of the step in an agent turn."
},
"step_id": {
"type": "string"
@@ -5803,7 +5859,8 @@
"shield_call",
"memory_retrieval"
],
- "title": "StepType"
+ "title": "StepType",
+ "description": "Type of the step in an agent turn."
},
"step_id": {
"type": "string"
@@ -5837,7 +5894,8 @@
"shield_call",
"memory_retrieval"
],
- "title": "StepType"
+ "title": "StepType",
+ "description": "Type of the step in an agent turn."
},
"step_id": {
"type": "string"
diff --git a/docs/_static/llama-stack-spec.yaml b/docs/_static/llama-stack-spec.yaml
index eb31b61fb..cfca894fb 100644
--- a/docs/_static/llama-stack-spec.yaml
+++ b/docs/_static/llama-stack-spec.yaml
@@ -234,7 +234,8 @@ paths:
post:
responses:
'200':
- description: OK
+ description: >-
+ An AgentCreateResponse with the agent ID.
content:
application/json:
schema:
@@ -251,7 +252,8 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ description: >-
+ Create an agent with the given configuration.
parameters: []
requestBody:
content:
@@ -263,7 +265,7 @@ paths:
post:
responses:
'200':
- description: OK
+ description: An AgentSessionCreateResponse.
content:
application/json:
schema:
@@ -280,10 +282,12 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ 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
@@ -298,8 +302,8 @@ paths:
responses:
'200':
description: >-
- A single turn in an interaction with an Agentic System. **OR** streamed
- agent turn completion response.
+ If stream=False, returns a Turn object. If stream=True, returns an SSE
+ event stream of AgentTurnResponseStreamChunk
content:
application/json:
schema:
@@ -319,15 +323,19 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ 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
@@ -411,10 +419,11 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ description: Delete an agent by its ID.
parameters:
- name: agent_id
in: path
+ description: The ID of the agent to delete.
required: true
schema:
type: string
@@ -439,20 +448,25 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ 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
@@ -474,15 +488,18 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ description: Delete an agent session by its ID.
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
@@ -630,7 +647,7 @@ paths:
get:
responses:
'200':
- description: OK
+ description: An AgentStepResponse.
content:
application/json:
schema:
@@ -647,25 +664,30 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ 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
@@ -673,7 +695,7 @@ paths:
get:
responses:
'200':
- description: OK
+ description: A Turn.
content:
application/json:
schema:
@@ -690,20 +712,24 @@ paths:
$ref: '#/components/responses/DefaultError'
tags:
- Agents
- description: ''
+ 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
@@ -3567,6 +3593,7 @@ components:
properties:
agent_config:
$ref: '#/components/schemas/AgentConfig'
+ description: The configuration for the agent.
additionalProperties: false
required:
- agent_config
@@ -3585,6 +3612,7 @@ components:
properties:
session_name:
type: string
+ description: The name of the session to create.
additionalProperties: false
required:
- session_name
@@ -3607,8 +3635,12 @@ components:
oneOf:
- $ref: '#/components/schemas/UserMessage'
- $ref: '#/components/schemas/ToolResponseMessage'
+ description: List of messages to start the turn with.
stream:
type: boolean
+ description: >-
+ (Optional) If True, generate an SSE event stream of the response. Defaults
+ to False.
documents:
type: array
items:
@@ -3622,19 +3654,30 @@ components:
items:
$ref: '#/components/schemas/InterleavedContentItem'
- $ref: '#/components/schemas/URL'
+ description: The content of the document.
mime_type:
type: string
+ description: The MIME type of the document.
additionalProperties: false
required:
- content
- mime_type
title: Document
+ description: A document to be used by an agent.
+ description: >-
+ (Optional) List of documents to create the turn with.
toolgroups:
type: array
items:
$ref: '#/components/schemas/AgentTool'
+ description: >-
+ (Optional) List of toolgroups to create the turn with, will be used in
+ addition to the agent's config toolgroups for the request.
tool_config:
$ref: '#/components/schemas/ToolConfig'
+ description: >-
+ (Optional) The tool configuration to create the turn with, will be used
+ to override the agent's tool_config.
additionalProperties: false
required:
- messages
@@ -3644,20 +3687,25 @@ components:
properties:
turn_id:
type: string
+ description: The ID of the turn.
step_id:
type: string
+ description: The ID of the step.
started_at:
type: string
format: date-time
+ description: The time the step started.
completed_at:
type: string
format: date-time
+ description: The time the step completed.
step_type:
type: string
const: inference
default: inference
model_response:
$ref: '#/components/schemas/CompletionMessage'
+ description: The response from the LLM.
additionalProperties: false
required:
- turn_id
@@ -3665,27 +3713,36 @@ components:
- step_type
- model_response
title: InferenceStep
+ description: An inference step in an agent turn.
MemoryRetrievalStep:
type: object
properties:
turn_id:
type: string
+ description: The ID of the turn.
step_id:
type: string
+ description: The ID of the step.
started_at:
type: string
format: date-time
+ description: The time the step started.
completed_at:
type: string
format: date-time
+ description: The time the step completed.
step_type:
type: string
const: memory_retrieval
default: memory_retrieval
vector_db_ids:
type: string
+ description: >-
+ The IDs of the vector databases to retrieve context from.
inserted_context:
$ref: '#/components/schemas/InterleavedContent'
+ description: >-
+ The context retrieved from the vector databases.
additionalProperties: false
required:
- turn_id
@@ -3694,6 +3751,8 @@ components:
- vector_db_ids
- inserted_context
title: MemoryRetrievalStep
+ description: >-
+ A memory retrieval step in an agent turn.
SafetyViolation:
type: object
properties:
@@ -3721,39 +3780,49 @@ components:
properties:
turn_id:
type: string
+ description: The ID of the turn.
step_id:
type: string
+ description: The ID of the step.
started_at:
type: string
format: date-time
+ description: The time the step started.
completed_at:
type: string
format: date-time
+ description: The time the step completed.
step_type:
type: string
const: shield_call
default: shield_call
violation:
$ref: '#/components/schemas/SafetyViolation'
+ description: The violation from the shield call.
additionalProperties: false
required:
- turn_id
- step_id
- step_type
title: ShieldCallStep
+ description: A shield call step in an agent turn.
ToolExecutionStep:
type: object
properties:
turn_id:
type: string
+ description: The ID of the turn.
step_id:
type: string
+ description: The ID of the step.
started_at:
type: string
format: date-time
+ description: The time the step started.
completed_at:
type: string
format: date-time
+ description: The time the step completed.
step_type:
type: string
const: tool_execution
@@ -3762,10 +3831,12 @@ components:
type: array
items:
$ref: '#/components/schemas/ToolCall'
+ description: The tool calls to execute.
tool_responses:
type: array
items:
$ref: '#/components/schemas/ToolResponse'
+ description: The tool responses from the tool calls.
additionalProperties: false
required:
- turn_id
@@ -3774,6 +3845,7 @@ components:
- tool_calls
- tool_responses
title: ToolExecutionStep
+ description: A tool execution step in an agent turn.
ToolResponse:
type: object
properties:
@@ -3850,13 +3922,16 @@ components:
items:
$ref: '#/components/schemas/InterleavedContentItem'
- $ref: '#/components/schemas/URL'
+ description: The content of the attachment.
mime_type:
type: string
+ description: The MIME type of the attachment.
additionalProperties: false
required:
- content
- mime_type
title: Attachment
+ description: An attachment to an agent turn.
started_at:
type: string
format: date-time
@@ -3922,6 +3997,7 @@ components:
- shield_call
- memory_retrieval
title: StepType
+ description: Type of the step in an agent turn.
step_id:
type: string
step_details:
@@ -3959,6 +4035,7 @@ components:
- shield_call
- memory_retrieval
title: StepType
+ description: Type of the step in an agent turn.
step_id:
type: string
delta:
@@ -3985,6 +4062,7 @@ components:
- shield_call
- memory_retrieval
title: StepType
+ description: Type of the step in an agent turn.
step_id:
type: string
metadata:
diff --git a/llama_stack/apis/agents/agents.py b/llama_stack/apis/agents/agents.py
index eb3399788..def61b617 100644
--- a/llama_stack/apis/agents/agents.py
+++ b/llama_stack/apis/agents/agents.py
@@ -41,16 +41,36 @@ from llama_stack.schema_utils import json_schema_type, register_schema, webmetho
class Attachment(BaseModel):
+ """An attachment to an agent turn.
+
+ :param content: The content of the attachment.
+ :param mime_type: The MIME type of the attachment.
+ """
+
content: InterleavedContent | URL
mime_type: str
class Document(BaseModel):
+ """A document to be used by an agent.
+
+ :param content: The content of the document.
+ :param mime_type: The MIME type of the document.
+ """
+
content: InterleavedContent | URL
mime_type: str
class StepCommon(BaseModel):
+ """A common step in an agent turn.
+
+ :param turn_id: The ID of the turn.
+ :param step_id: The ID of the step.
+ :param started_at: The time the step started.
+ :param completed_at: The time the step completed.
+ """
+
turn_id: str
step_id: str
started_at: Optional[datetime] = None
@@ -58,6 +78,14 @@ class StepCommon(BaseModel):
class StepType(Enum):
+ """Type of the step in an agent turn.
+
+ :cvar inference: The step is an inference step that calls an LLM.
+ :cvar tool_execution: The step is a tool execution step that executes a tool call.
+ :cvar shield_call: The step is a shield call step that checks for safety violations.
+ :cvar memory_retrieval: The step is a memory retrieval step that retrieves context for vector dbs.
+ """
+
inference = "inference"
tool_execution = "tool_execution"
shield_call = "shield_call"
@@ -66,6 +94,11 @@ class StepType(Enum):
@json_schema_type
class InferenceStep(StepCommon):
+ """An inference step in an agent turn.
+
+ :param model_response: The response from the LLM.
+ """
+
model_config = ConfigDict(protected_namespaces=())
step_type: Literal[StepType.inference.value] = StepType.inference.value
@@ -74,6 +107,12 @@ class InferenceStep(StepCommon):
@json_schema_type
class ToolExecutionStep(StepCommon):
+ """A tool execution step in an agent turn.
+
+ :param tool_calls: The tool calls to execute.
+ :param tool_responses: The tool responses from the tool calls.
+ """
+
step_type: Literal[StepType.tool_execution.value] = StepType.tool_execution.value
tool_calls: List[ToolCall]
tool_responses: List[ToolResponse]
@@ -81,13 +120,25 @@ class ToolExecutionStep(StepCommon):
@json_schema_type
class ShieldCallStep(StepCommon):
+ """A shield call step in an agent turn.
+
+ :param violation: The violation from the shield call.
+ """
+
step_type: Literal[StepType.shield_call.value] = StepType.shield_call.value
violation: Optional[SafetyViolation]
@json_schema_type
class MemoryRetrievalStep(StepCommon):
+ """A memory retrieval step in an agent turn.
+
+ :param vector_db_ids: The IDs of the vector databases to retrieve context from.
+ :param inserted_context: The context retrieved from the vector databases.
+ """
+
step_type: Literal[StepType.memory_retrieval.value] = StepType.memory_retrieval.value
+ # TODO: should this be List[str]?
vector_db_ids: str
inserted_context: InterleavedContent
@@ -335,7 +386,13 @@ class Agents(Protocol):
async def create_agent(
self,
agent_config: AgentConfig,
- ) -> AgentCreateResponse: ...
+ ) -> AgentCreateResponse:
+ """Create an agent with the given configuration.
+
+ :param agent_config: The configuration for the agent.
+ :returns: An AgentCreateResponse with the agent ID.
+ """
+ ...
@webmethod(route="/agents/{agent_id}/session/{session_id}/turn", method="POST")
async def create_agent_turn(
@@ -352,7 +409,19 @@ class Agents(Protocol):
documents: Optional[List[Document]] = None,
toolgroups: Optional[List[AgentToolGroup]] = None,
tool_config: Optional[ToolConfig] = None,
- ) -> Union[Turn, AsyncIterator[AgentTurnResponseStreamChunk]]: ...
+ ) -> Union[Turn, AsyncIterator[AgentTurnResponseStreamChunk]]:
+ """Create a new turn for an agent.
+
+ :param agent_id: The ID of the agent to create the turn for.
+ :param session_id: The ID of the session to create the turn for.
+ :param messages: List of messages to start the turn with.
+ :param stream: (Optional) If True, generate an SSE event stream of the response. Defaults to False.
+ :param documents: (Optional) List of documents to create the turn with.
+ :param toolgroups: (Optional) List of toolgroups to create the turn with, will be used in addition to the agent's config toolgroups for the request.
+ :param tool_config: (Optional) The tool configuration to create the turn with, will be used to override the agent's tool_config.
+ :returns: If stream=False, returns a Turn object.
+ If stream=True, returns an SSE event stream of AgentTurnResponseStreamChunk
+ """
@webmethod(
route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}/resume",
@@ -388,7 +457,15 @@ class Agents(Protocol):
agent_id: str,
session_id: str,
turn_id: str,
- ) -> Turn: ...
+ ) -> Turn:
+ """Retrieve an agent turn by its ID.
+
+ :param agent_id: The ID of the agent to get the turn for.
+ :param session_id: The ID of the session to get the turn for.
+ :param turn_id: The ID of the turn to get.
+ :returns: A Turn.
+ """
+ ...
@webmethod(
route="/agents/{agent_id}/session/{session_id}/turn/{turn_id}/step/{step_id}",
@@ -400,14 +477,30 @@ class Agents(Protocol):
session_id: str,
turn_id: str,
step_id: str,
- ) -> AgentStepResponse: ...
+ ) -> AgentStepResponse:
+ """Retrieve an agent step by its ID.
+
+ :param agent_id: The ID of the agent to get the step for.
+ :param session_id: The ID of the session to get the step for.
+ :param turn_id: The ID of the turn to get the step for.
+ :param step_id: The ID of the step to get.
+ :returns: An AgentStepResponse.
+ """
+ ...
@webmethod(route="/agents/{agent_id}/session", method="POST")
async def create_agent_session(
self,
agent_id: str,
session_name: str,
- ) -> AgentSessionCreateResponse: ...
+ ) -> AgentSessionCreateResponse:
+ """Create a new session for an agent.
+
+ :param agent_id: The ID of the agent to create the session for.
+ :param session_name: The name of the session to create.
+ :returns: An AgentSessionCreateResponse.
+ """
+ ...
@webmethod(route="/agents/{agent_id}/session/{session_id}", method="GET")
async def get_agents_session(
@@ -415,17 +508,35 @@ class Agents(Protocol):
session_id: str,
agent_id: str,
turn_ids: Optional[List[str]] = None,
- ) -> Session: ...
+ ) -> Session:
+ """Retrieve an agent session by its ID.
+
+ :param session_id: The ID of the session to get.
+ :param agent_id: The ID of the agent to get the session for.
+ :param turn_ids: (Optional) List of turn IDs to filter the session by.
+ """
+ ...
@webmethod(route="/agents/{agent_id}/session/{session_id}", method="DELETE")
async def delete_agents_session(
self,
session_id: str,
agent_id: str,
- ) -> None: ...
+ ) -> None:
+ """Delete an agent session by its ID.
+
+ :param session_id: The ID of the session to delete.
+ :param agent_id: The ID of the agent to delete the session for.
+ """
+ ...
@webmethod(route="/agents/{agent_id}", method="DELETE")
async def delete_agent(
self,
agent_id: str,
- ) -> None: ...
+ ) -> None:
+ """Delete an agent by its ID.
+
+ :param agent_id: The ID of the agent to delete.
+ """
+ ...