--- title: "List agents" method: GET path: "/v2/agents" tags: ["Agents"] --- # List agents `GET /v2/agents` Lists all agents available to the authenticated user. Results are paginated. ## Query parameters - `filter` string - `enabled` boolean - `limit` integer - `page_key` string ## Headers - `Request-Timeout` integer - `Request-Timeout-Millis` integer ## Response `200` List of available agents. - ListAgentsResponse — Response containing a list of agents. - `agents` Agent[], required — List of agents. - `key` string, required — A unique key that identifies an agent. - `name` string, required — The human-readable name of an agent. - `description` string — A detailed description of the agent's purpose and capabilities. - `tool_configurations` object, required — A map of tool configurations available to the agent. The key is the name of the tool configuration and the value is an agent tool configuration. - `skills` object — A map of skills available to the agent, keyed by skill name. Skills provide specialized instructions that can be invoked during agent execution. The skill list (name + description) is shown in the system message; content is loaded on invocation. - `model` AgentModel, required — Configuration for the model used in this step, including the model name and arbitrary parameters. - `name` string, required — The name of the model to use for this step. - `parameters` object — Arbitrary model-specific parameters that can be passed to the model. - `retry_configuration` RetryConfiguration — Configuration for automatic retry of failed LLM requests with exponential backoff. - `enabled` boolean — Whether retry is enabled. Enabled by default to provide resilience against transient failures. - `max_retries` integer — Maximum number of retry attempts after initial failure. - `initial_backoff_ms` integer — Initial backoff time in milliseconds before first retry. - `max_backoff_ms` integer — Maximum backoff time in milliseconds between retries. - `backoff_factor` number, double — Multiplication factor for exponential backoff between retries. - `first_step` FirstAgentStep, required — The entry point step for an agent, with a unique name. See AgentStep for full step documentation. - `name` string, required — Unique identifier for this step within the agent. Must not conflict with any key in the steps map. - `type` string — Deprecated. This field is ignored and exists only for backward compatibility. - `instructions` AgentStepInstruction[], required — List of instructions that guide the agent's behavior in this step. - union — An instruction that can be used in an agent step, either by reference, defined inline, or using a Vectara built-in instruction. - ReferenceInstruction — A reference to an instruction that an agent can use. If version is not specified, the agent uses the latest version. When the instruction is updated, agents that use it must be updated to reference the new version explicitly. - `id` string, required — The unique identifier for an instruction. - `version` integer — The specific version of the instruction to use. If not specified, the agent uses the latest version. - `type` string, required — The type of instruction, used for discrimination. - InlineInstruction — Base properties for creating an instruction, without the type discriminator field. - `name` string, required — The human-readable name of an instruction. - `description` string — A detailed description of what this instruction does. - `template_type` 'velocity' | 'text' — The templating engine used to render the instruction's template. - `velocity`: render the template with the Velocity engine, substituting agent, session, and tool variables. - `text`: use the template verbatim as plain text, with no variable substitution. - `template` string, required — The instruction template content. How it is rendered depends on the sibling `template_type`. When `template_type` is `text`, the content is used verbatim as the instruction and no variables are substituted. When `template_type` is `velocity`, the content is rendered with the Velocity engine and the following variables are available: - `$agent.name` - Agent name - `$agent.key` - Agent key - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map (includes user-provided context from test/runtime) - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") - `$tools` - List of tool maps, each with `name` and `description` fields Example: `You are a helpful customer support agent. Agent: $agent.name. Today is $currentDate. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end` - `metadata` object — Arbitrary metadata associated with the instruction. - `enabled` boolean — Whether the instruction should be enabled upon creation. - `type` string, required — The type of instruction, used for discrimination. - `output_parser` union, required — Configuration for how the agent's output is parsed and formatted before it returns to the user. - DefaultOutputParser — Returns the agent's output directly to the user without additional processing. Uses the model's built-in tool calling. - `type` string, required — The type of output parser, which is always 'default' for this parser type. - StructuredOutputParser — Parses agent output as structured JSON conforming to a specified schema. Uses the model's native structured outputs capability to guarantee valid JSON that adheres to the provided schema. This is useful when you need the agent's final response in a specific format for downstream processing. When this parser is configured, the agent emits a StructuredOutputEvent instead of AgentOutputEvent. The StructuredOutputEvent contains the validated JSON content along with the schema name for identification. Note: When using structured outputs, the agent can still use tools normally. The schema constraint only applies to the agent's final text response. When streaming, the structured output arrives as a single complete event, not in chunks. - `type` string, required — The type of output parser, which is always 'structured' for this parser type. - `json_schema` JsonSchemaSpec, required — A specification wrapper for a named JSON schema. - `description` string — A description of the purpose of the response format. The model uses this description to determine how to respond in the format. - `name` string, required — A unique name for this schema. - `strict` boolean, nullable — When true, enforces strict schema adherence. The model always follows the exact schema structure. In strict mode, the schema must follow these rules: - Set `additionalProperties: false` on all object types - List all properties in the `required` array - Maximum 100 properties total, with max 5 levels of nesting - Unsupported keywords: minLength, maxLength, pattern, minimum, maximum, minItems, maxItems - The root schema cannot use the `anyOf` type - `schema` union, required — A JSON Schema definition that describes a data structure. Covers the smallest subset of JSON Schema that all LLM providers support. Unknown keywords are kept and passed through to the provider. `properties`, `required`, and `additionalProperties` are valid only when `type` is `object`. `enum`, `format`, `items`, and `anyOf` are valid for every other `type`, and for an element with no `type`, such as one that only combines schemas with `anyOf`. - … - `reminders` AgentStepReminder[] — Reminders injected into conversation messages when specific events occur. - union — A reminder that is injected into the agent conversation when specific event types occur. - TemplatedReminder — A reminder whose rendered template is appended to messages that match the specified hooks. The template renders at session start according to its template_type (Velocity by default, or text for verbatim content). - `type` string, required — The type of reminder. - `template_type` 'velocity' | 'text' — The templating engine used to render the instruction's template. - `velocity`: render the template with the Velocity engine, substituting agent, session, and tool variables. - `text`: use the template verbatim as plain text, with no variable substitution. - `template` string, required — The instruction template content. How it is rendered depends on the sibling `template_type`. When `template_type` is `text`, the content is used verbatim as the instruction and no variables are substituted. When `template_type` is `velocity`, the content is rendered with the Velocity engine and the following variables are available: - `$agent.name` - Agent name - `$agent.key` - Agent key - `$agent.metadata` - Agent metadata map - `$session.key` - Session key - `$session.metadata` - Session metadata map (includes user-provided context from test/runtime) - `$currentDate` - Current date/time in ISO 8601 format (e.g., "2025-10-24T15:30:45Z") - `$tools` - List of tool maps, each with `name` and `description` fields Example: `You are a helpful customer support agent. Agent: $agent.name. Today is $currentDate. Available tools: #foreach($tool in $tools)${tool.name}#if($foreach.hasNext), #end#end` - `hooks` string[], required — Event types that trigger this reminder to be appended to the corresponding message. - `fire_every` integer — Fire this reminder on every Nth matching hook event (counted independently per hook). Defaults to 1, which preserves the legacy behavior of firing on every matching event. Must be at least 1. Counters reset after a session compaction: the post-compaction event stream is treated as a fresh sequence (index 0), so `skip_first` warmup applies again from the first new matching event. - `skip_first` integer — Skip the first N matching hook events at session start before firing this reminder for the first time (counted independently per hook). Defaults to 0, meaning no warmup delay. Must be non-negative. Counters reset after a session compaction: the post-compaction event stream is treated as a fresh sequence (index 0), so the warmup applies again from the first new matching event. - GlossaryExpansionReminder — A reminder that maps terms, acronyms, and abbreviations to their expansions using a glossary. When attached to a step, the platform appends the matched terms and their expansions to the event as a hint. The agent decides how to use them. - `type` string, required — The type of reminder. - `glossary_key` string, required — A user-provided key that uniquely identifies a glossary. - `next_steps` NextStep[] — Conditional transitions to other steps. Evaluated in order; first matching condition is selected. A next_step without a condition acts as a catch-all/default. If no condition matches, the agent remains on the current step and the agent ends output. - `condition` string — UserFn expression evaluating to boolean. Uses the `get()` function with JSONPath to access the step transition context. See https://docs.vectara.com/docs/search-and-retrieval/rerankers/user-defined-function-reranker for the UserFn language reference. Omit for catch-all/default routing. The context available to `get()` has the following shape: ``` { "agent": { "name": "...", "key": "...", "description": "...", "metadata": { ... } }, "session": { "key": "...", "name": "...", "description": "...", "metadata": { ... } }, "currentDate": "2024-01-15T10:35:00Z", "tools": { "": { "outputs": { "latest": { ... } } } }, "output": { "text": "..." } } ``` - `$.agent.metadata.` — agent metadata fields - `$.session.metadata.` — session metadata fields - `$.tools..outputs.latest.` — latest tool output fields - `$.output.text` — agent text output (when output_parser is `default`) - `$.output.` — agent structured output fields (when output_parser is `structured`) - `step_name` string, required — Name of the step to transition to. Must reference a step defined in the agent's steps list. - `allowed_tools` string[] — List of tool configuration names that this step is allowed to use. If not specified (null), all tools defined in the agent's tool_configurations are allowed. If set to an empty array, no tools are allowed and the agent can only respond with text. - `allowed_skills` string[] — List of skill names that this step is allowed to use. If not specified (null), all skills defined in the agent's skills map are allowed. If set to an empty array, no skills are available and the invoke_skill tool is not shown. - `reentry_step` string — Step name to resume at when the session receives the next user message. If not specified, the session re-enters at this step (i.e., stays here). Set to the agent's first_step_name to always restart from the beginning. - `first_step_name` string — The name of the agent's entry point step. References a key in the steps map. Matches first_step.name. - `steps` object — A map of named steps keyed by step name. Steps can transition to other steps defined here via next_steps. The entry point is the step named by first_step_name. - `metadata` object — Arbitrary metadata associated with the agent for customization and configuration. - `enabled` boolean, required — Whether the agent is currently enabled and available for use. - `compaction` CompactionConfig — Configuration for automatic context compaction. - `enabled` boolean — Enable automatic context compaction. - `threshold_percent` integer — Context usage % (50-95) at which compaction is applied. - `keep_recent_inputs` integer — Number of recent turns to keep verbatim (not compacted). - `compaction_message` string — Custom additional instructions for the compaction summarization prompt. - `tool_event_policy` 'exclude' | 'include_outputs' | 'include_all' — How tool events are included in the compaction input. - `session_enrichment` SessionEnrichmentConfig — Tool calls run at session creation to populate the new session's metadata before the agent's first turn. Each call invokes one of the agent's enrichment-only tool configurations and writes its output into the session metadata. The agent, run conditions, and routing can then read values fetched or computed at session start. Enrichment tools are ordinary entries in the agent's tool_configurations marked enrichment_only, so they are never exposed to the agent's LLM. Enrichment runs for every session the agent creates regardless of trigger, including the API, chat connectors, and schedules. Independent calls run in parallel and a call may consume an earlier call's output. Enrichment is fail-closed: unless a call sets continue_on_error, a failed call aborts session creation and no session is created. The abort status names the failure: 422 for an invalid configuration or a failed transform, 502 for a tool failure, and 504 for a timeout. A jq error raised by the called tool configuration's input_transform or output_transform is a call failure like any other: continue_on_error skips it, and otherwise its message is returned in the error response's messages array. - `enabled` boolean — When false, enrichment does not run and sessions are created with the metadata provided by the caller. - `tool_calls` SessionEnrichmentToolCall[] — Ordered tool calls run at session creation. Independent calls run in parallel. A call that references another call's output runs after it. - `tool` string, required — Name of the tool configuration to call. Must name one of the agent's tool_configurations whose enrichment_only is true. A later tool call references an earlier call's output as tools..outputs.latest. - `arguments` object — Arguments to invoke the tool with. These may set only the parameters that the tool definition does not already fix through its own configured argument_override. A parameter fixed by the tool cannot be set per call, so naming one here is rejected when the agent is created or updated. Enrichment runs with no LLM to fill arguments in. These arguments, together with the parameters fixed by the tool, must cover every required parameter of the tool. Each value is either a literal or a `$ref` object that resolves against session or agent metadata, the agent's secrets as `agent.secrets.`, the session secrets supplied on the create request as `session.secrets.`, or an earlier call's output as `tools..outputs.latest`. Session creation fails with 422 if a `$ref` names a secret that is not on the agent or in the create request, unless the `$ref` supplies a `$default`, in which case the default value is used instead. - `metadata_target_path` string — Dotted metadata path the tool's output is written to, after the tool's own configured output_transform is applied. Outputs are written to the session metadata in call order. A later write to a path replaces any value written earlier at that path. A call without a target path is compute only, so later calls can reference its output but nothing is written to the metadata. Session metadata is returned unmasked on reads: a tool output or transform that writes a resolved secret value makes that secret readable in the session's metadata. - `timeout_seconds` integer — Seconds the call may run before it is treated as a failed call. - `continue_on_error` boolean — When true a failure of this call is ignored and its target is left unset. Otherwise a call failure aborts session creation. - `tool_output_offloading` ToolOutputOffloadingConfiguration — Controls how large tool outputs are kept from overwhelming the agent context window. Tool outputs are inspected as they are produced. A small output is always passed through unchanged. A larger output is handled in one of two cases: when the output on its own is big enough to dominate the context, or when adding it to the conversation would leave too little room for the agent to continue. In either case the output is handled according to `mode` — stored as an artifact and replaced with a compact reference, or truncated in place with the head and tail preserved and the middle omitted. When stored as an artifact, the agent is expected to have artifact_read, artifact_grep, or artifact_jq configured so it can retrieve the full content on demand. All fields are optional; omitted fields fall back to defaults. - `enabled` boolean — Whether tool output offloading is active. Defaults to true. When disabled, tool outputs are always passed through to the agent verbatim. - `mode` 'artifact' | 'truncate' — How a large tool output is handled after it is selected for offloading. In `artifact` mode, the full output is stored as a session artifact and replaced in the conversation with a compact reference containing the artifact id, size, shape, and hints for the available artifact tools. The agent can then use artifact_read, artifact_grep, or artifact_jq to retrieve just the parts it needs. In `truncate` mode, the output is shortened in place to fit within the target size. The head and tail are preserved and the middle is replaced with a short notice explaining that content was omitted. No artifact is created. When unset, the default is `artifact` if the agent has any of artifact_read, artifact_grep, or artifact_jq configured, and `truncate` otherwise. - `context_percentage` number, double — The fraction of the model's context window that a single tool output is allowed to occupy before it is considered large enough to offload on its own, estimated at four characters per token. The resulting byte threshold is clamped between `min_threshold_bytes` and `max_threshold_bytes`, so for very large context models this percentage is usually dominated by `max_threshold_bytes`, and for very small context models it is dominated by `min_threshold_bytes`. - `max_threshold_bytes` integer — An absolute ceiling on single-output size. Any output above this many bytes is considered large enough to offload on its own, regardless of the model's context window. This prevents unusually large outputs from slipping through on models with very large context windows. - `min_threshold_bytes` integer — A hard floor on offloading. Tool outputs below this size are always passed through to the agent unchanged, even when cumulative context usage is high. This ensures that short, useful outputs are never unnecessarily truncated or replaced with a reference. - `headroom_percentage` number, double — The fraction of the model's context window at which offloading becomes sensitive to cumulative usage. When adding a tool output would push total input tokens above this fraction of the context window (estimated at four characters per token), the output is offloaded even if it would otherwise be considered small enough to pass through. This is independent of the compaction `threshold_percent`: both can be configured on the same agent and both can apply. In practice it is often useful to set this below the compaction threshold so that large tool outputs are offloaded before compaction is triggered, avoiding the case where a large tool result is immediately summarized away. Setting this to 1.0 effectively disables the headroom behavior, leaving only the per-output size thresholds in effect. - `created_at` string, date-time — Timestamp when the agent was created. - `updated_at` string, date-time — Timestamp when the agent was last updated. - `metadata` ListMetadata, required — The standard metadata in the response of a list operation. - `page_key` string — The page key for the next page of results. Pass it as a query parameter to request the next page. ## Other responses - `403` — Permissions do not allow listing agents. --- [API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/e85040b266cc/schema)