Execute an agent
POST/agents/:agent_id/execute
Runs an agent: retrieves fragments for the retrieval placeholders from the pipeline named in x-pipeline-id, inserts the input values and the fragment text into the prompt template, and sends the messages to the LLM named in x-llm-id. Each placeholder searches the default index of its kind in the pipeline, or, for a similarity or mmr placeholder with embedding, the vector index of that embedding model, and a request without path covers only the documents without a path. The stream field selects the response format: newline-delimited JSON (NDJSON) by default, server-sent events with "sse" or plain text with false. With tracing or attributions set to true, Foundation4 records a trace for 60 minutes and, when the execution succeeds, returns the trace identifier in the x-foundation4ai-tracing-id response header. An execution that fails returns no header. With attributions set to true, Foundation4 also adds the complete answer to the trace, with each sentence of the answer and the retrieved fragments that support the sentence. The response body carries the answer only; the retrieved fragments and the attributions are in the trace.
Permissions. Execute on the agent, the pipeline and the LLM, and a classification allow-list that covers every classification that the request names.
Agents and prompt templates describes execution, and LLMs describes the requirements on the model server and the response formats.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 500
- 502
The answer in the format that stream selects: NDJSON lines of ApiLlmResponse objects, server-sent events with the same objects as data, or the complete answer as plain text. With tracing or attributions set to true, the x-foundation4ai-tracing-id header holds the trace identifier.
Response Headers
The identifier of the execution trace, present when the request sets tracing or attributions to true. GET /tracing/{execution_id} returns the trace.
A required header is missing (Header of type `x-llm-id` was missing or the same for x-pipeline-id) or is not a valid identifier (Invalid pipeline ID, Invalid LLM ID), a filter does not match the pipeline's metadata schema (Schema error), or the execution cannot run (Invalid parameter). details.error holds the reason, such as Missing prompt variables: <names>, a message that the pipeline has no default text index for a full-text or hybrid placeholder, Missing embedding model ID for placeholder: <name> for a similarity or MMR placeholder without embedding on a pipeline without a default vector index, or, while the API server configuration sets app.allow_private_endpoints to false, an LLM endpoint that names a private, loopback or link-local address. The same status reports a body that is not valid JSON.
The authentication headers are missing or invalid, or the API key is inactive or expired. Errors lists the messages.
The license is not valid (Invalid license: <reason>), or a named classification that the pipeline defines is outside the classification allow-list of the key, or the key has an empty allow-list (Unauthorized: execute access to Pipeline required, with the classification named in details.error).
The agent (Agent not found), the pipeline (Pipeline not found) or the LLM (LLM not found) does not exist, or the key lacks execute permission on that object. A placeholder that names an embedding model without a ready vector index in the pipeline returns Embedding Model not found, and a classification object with search_type 1 or 3 that names a classification the pipeline does not define returns Classification not found.
A search index or a distance index that a placeholder searches is still being built, or the search index failed to build (Conflict, with the reason in details.error).
The body does not match the request schema, for example a path that is not a valid path pattern.
Retrieval failed, for example because the embedding model could not convert the query (Internal server error). The API server log records the cause.
The model server returned an error or could not be reached before the first part of the answer, or at any time with "stream": false (Upstream LLM error). A streamed response that has started ends with an error line or an error event instead. The API server log records the reason.