--- title: "Interact with an agent" method: POST path: "/v2/agents/{agent_key}/sessions/{session_key}/events" tags: ["Agent Sessions"] --- # Interact with an agent `POST /v2/agents/{agent_key}/sessions/{session_key}/events` Creates a new input event in the session to interact with the agent. ## Path parameters - `agent_key` string, required — A unique key that identifies an agent. - `session_key` string, required — A unique key that identifies an agent session. ## Headers - `Request-Timeout` integer - `Request-Timeout-Millis` integer ## Request body - union — A request to create input for an agent session. - object — Base properties shared by all input request types. - `type` string - `stream_response` boolean — Whether to stream the response. - `surface_description` SurfaceDescription — Identifies the surface submitting this input, such as a connector. The `(type, id)` pair identifies the surface within the session; repeat submissions from the same pair are treated as one surface. All fields are optional; a caller that omits `type` is treated as an `api` surface. - `type` string — The kind of surface the input came from, so the agent knows where its reply will be seen and can shape it for that surface — a free-form label, not a fixed set. Connectors send "slack", "gchat", or "zoom"; API callers may send a label describing their own surface. Treated as "api" when omitted. - `id` string — An identifier for this surface within its `type`, e.g. a connector id. Combined with `type` to identify the surface within the session. - `include` boolean — When true, the agent is told which listeners — surfaces currently streaming this session — will see this turn's response. - `messages` AgentInput[], required — List of inputs that make up this event. - union — An input that can be provided to an agent message. - AgentTextInput — A text input for an agent message. - `type` string, required — The type of input. - `content` string, required — The text content of the input. - AgentSkillInput — An input that invokes a skill by name. - `type` string, required — The type of input. - `skill_name` string, required — The name (key) of the skill to invoke. - `since` string — An event ID cursor. When provided and the session is currently running, the response includes all events created after this event ID. The new input is queued and processed according to the behavior field. Use the special value "start" to receive all events from the beginning of the session, including the input message itself. - `behavior` 'steer' | 'follow_up' — Controls how the input is processed when the session is already running. - `steer`: Insert the message as soon as possible on the next iteration of the agent loop. - `follow_up`: Insert the message after the current agent loop finishes, as a follow-up turn. Follow-up inputs are consumed one at a time: after each follow-up turn completes, the next queued follow-up is processed. This ensures each follow-up gets a full agent loop iteration. - `entry_step` string — Name of the step the agent enters before processing this input. Must be a key in the agent's `steps` map or the agent's `first_step_name`. When omitted, the session resumes at its `current_step_name`. - object — Base properties shared by all input request types. - `type` string, required - `stream_response` boolean — Whether to stream the response. - `surface_description` SurfaceDescription — Identifies the surface submitting this input, such as a connector. The `(type, id)` pair identifies the surface within the session; repeat submissions from the same pair are treated as one surface. All fields are optional; a caller that omits `type` is treated as an `api` surface. - `type` string — The kind of surface the input came from, so the agent knows where its reply will be seen and can shape it for that surface — a free-form label, not a fixed set. Connectors send "slack", "gchat", or "zoom"; API callers may send a label describing their own surface. Treated as "api" when omitted. - `id` string — An identifier for this surface within its `type`, e.g. a connector id. Combined with `type` to identify the surface within the session. - `include` boolean — When true, the agent is told which listeners — surfaces currently streaming this session — will see this turn's response. - object — Base properties shared by all input request types. - `type` string, required - `stream_response` boolean — Whether to stream the response. - `surface_description` SurfaceDescription — Identifies the surface submitting this input, such as a connector. The `(type, id)` pair identifies the surface within the session; repeat submissions from the same pair are treated as one surface. All fields are optional; a caller that omits `type` is treated as an `api` surface. - `type` string — The kind of surface the input came from, so the agent knows where its reply will be seen and can shape it for that surface — a free-form label, not a fixed set. Connectors send "slack", "gchat", or "zoom"; API callers may send a label describing their own surface. Treated as "api" when omitted. - `id` string — An identifier for this surface within its `type`, e.g. a connector id. Combined with `type` to identify the surface within the session. - `include` boolean — When true, the agent is told which listeners — surfaces currently streaming this session — will see this turn's response. - `compact_up_to_event_id` string — Compact all inputs up to this event ID (inclusive), e.g. "aev_abc123". When specified, `keep_recent_inputs` is bypassed — all inputs up to the anchor are compacted. If omitted, compacts all inputs except the most recent `keep_recent_inputs` inputs. - `compaction_message` string — Override the compaction prompt for this compaction. - object — Base properties shared by all input request types. - `type` string, required — Always `tool_output`. Identifies this input as a client tool output submission. - `stream_response` boolean — Whether to stream the response. - `surface_description` SurfaceDescription — Identifies the surface submitting this input, such as a connector. The `(type, id)` pair identifies the surface within the session; repeat submissions from the same pair are treated as one surface. All fields are optional; a caller that omits `type` is treated as an `api` surface. - `type` string — The kind of surface the input came from, so the agent knows where its reply will be seen and can shape it for that surface — a free-form label, not a fixed set. Connectors send "slack", "gchat", or "zoom"; API callers may send a label describing their own surface. Treated as "api" when omitted. - `id` string — An identifier for this surface within its `type`, e.g. a connector id. Combined with `type` to identify the surface within the session. - `include` boolean — When true, the agent is told which listeners — surfaces currently streaming this session — will see this turn's response. - `tool_outputs` CreateToolOutputRequest[], required — The tool outputs to deliver, one per pending client tool call. - union — Delivers the result of a client tool call identified by its `tool_input` event ID. - object — Base properties shared by client tool output submissions. - `event_id` string, required — The `tool_input` event this output responds to. - `type` string, required — Always `success`. Indicates the client tool call succeeded. - `output` object, required — The tool's result. Validated against the tool's `output_schema` if one is defined. - object — Base properties shared by client tool output submissions. - `event_id` string, required — The `tool_input` event this output responds to. - `type` string, required — Always `error`. Indicates the client tool call failed. - `error` unknown, required ## Response `201` The input event is created. - AgentResponse — Response containing the complete list of events generated by an agent. - `events` AgentEvent[], required — List of all events generated during agent processing. - union — An event in an agent session conversation. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `messages` AgentInput[], required — List of inputs that make up this message. - union — An input that can be provided to an agent message. - AgentTextInput — A text input for an agent message. - … - AgentSkillInput — An input that invokes a skill by name. - … - `message_diffs` string[] — Opaque diffs against the raw event payload, one per produced agent message. Each diff captures the exact text sent to the model at emission time. When present, the array length MUST equal `messages.length`; a mismatched length is rejected. When absent, the platform reconstructs the rendering on read. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `skill_name` string, required — The name of the skill that was loaded. - `content` string, required — The skill content that was loaded. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `artifacts` ArtifactReference[], required — References to uploaded artifacts - `artifact_id` string, required — Unique identifier for the artifact - `filename` string, required — Original filename of the artifact - `mime_type` string, required — MIME type of the file - `size_bytes` integer, required — File size in bytes - `agent_upload_message` string — Frozen text of the single user-role agent message rendered for this artifact upload at emission time, capturing the artifact metadata and instruction block as one prompt. When absent the platform reconstructs the rendering on read using current templates. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `tool_call_id` string, required — The identifier for the tool call. - `tool_configuration_name` string, required — The name of the tool configuration being invoked, as defined in the agent's tool_configurations map. - `tool_name` string, required — Name of the tool being called. - `tool_input` object, required — Input data for the tool. - `argument_override_paths` string[] — Dot-notation leaf paths supplied by the tool configuration's argument overrides rather than by the agent — for example `api_key`, `config.auth.token`, or `items[0]`. These paths are frozen on the input event so that the agent's view of its own past tool calls stays stable when the tool configuration changes: overrides are excluded from replayed calls regardless of how the override has evolved since. Only the paths are frozen here; the resolved values at those paths are not — they are recomputed against the live session at each launch and recorded on the corresponding `ToolOutputEvent.resolved_argument_overrides`. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `tool_call_id` string, required — The unique identifier for the tool call, matching the input event. - `tool_configuration_name` string, required — The name of the tool configuration that was invoked, as defined in the agent's tool_configurations map. - `tool_name` string, required — Name of the tool that was called. - `resolved_argument_overrides` object — The values the tool configuration's argument overrides contributed to this call, keyed by the paths in `ToolInputEvent.argument_override_paths`. `$ref` overrides are resolved against the session — agent secrets, session metadata, and prior tool outputs — with secret values masked as `****`. Literal overrides appear as-is. Overlay these onto `ToolInputEvent.tool_input` at the matching paths to see exactly what the tool received. Absent when the tool short-circuits before running (for example, malformed arguments from the agent or an unresolved dependency). - `tool_output` object, required — Output data from the tool. - `output_wrapped` boolean — Whether `tool_output` is an envelope holding a non-object result: tools may return raw text, a number, or an array, which is stored as `{"content": }` so the event stays a JSON object. When true, the actual tool result is the value under `content`; when false or absent, `tool_output` is the tool's own object result. - `error` boolean, required — Whether the tool call resulted in an error. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `content` string — Human-readable content of the reasoning process. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `content` string, required — The complete agent response content. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `schema_name` string, required — The name of the JSON schema that the content conforms to. - `content` unknown, required - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `context_limit` integer — The maximum number of tokens allowed by the model - `actual_tokens` integer — The actual number of tokens in the request - `message` string, required — Human-readable error message - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `transition_limit` integer — The maximum number of step transitions allowed - `message` string, required — Human-readable error message - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - object — Event signaling there was an error with the request. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string — If the stream fails, the platform sends an event with type `error`. - `messages` string[] — The error messages. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `pending_calls` ClientToolPendingCall[], required — The client tool calls awaiting output, one entry per outstanding call. - `event_id` string, required — The `tool_input` event this call corresponds to. Submit the matching `tool_output` with this `event_id`. - `tool_configuration_name` string, required — The name of the tool configuration being invoked, as defined in the agent's tool_configurations map. - `tool_name` string, required — Name of the tool being called. - `arguments` object, required — The fully materialized arguments for this call: the agent-supplied arguments merged with the tool configuration's argument overrides and literals, with `$ref`s resolved against the session. Secret-derived values are delivered unmasked because the client needs them to execute the tool. This is exactly what the client should execute the tool with. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `artifact_id` string, required — The ID of the image artifact being loaded into the agent's conversation context. - `detail` 'auto' | 'low' | 'high' — Detail level for image processing. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `from_step` string, required — The name of the step being transitioned from. - `to_step` string, required — The name of the step being transitioned to. - `content` string, required — The handoff message content for the agent. - object — Base properties shared by all agent event types. - `id` string, required — The unique identifier for the event. - `session_key` string, required — A unique key that identifies an agent session. - `created_at` string, date-time, required — Timestamp when the event was created. - `type` string, required — The type of event. - `turns_compacted` integer, required — Number of conversation turns that were compacted. - `events_compacted` integer, required — Number of events that were hidden by compaction. - `summary_text` string — The plain text summary produced by compaction. - `summary_key` string, required — The key of the summary created by compaction. - `session_key` string, required — A unique key that identifies an agent session. ## Other responses - `400` — The request to create an input event is malformed. - `403` — Permissions do not allow creating input events in this session. - `404` — Agent or session not found. - `409` — The session is already running. Use the `since` field in the request body to queue input. - `422` — The agent configuration is invalid (for example, invalid instruction or tool description templates). - `502` — Communication with the session failed. --- [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)