Skip to main content

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​

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
    x-foundation4ai-tracing-id

    The identifier of the execution trace, present when the request sets tracing or attributions to true. GET /tracing/{execution_id} returns the trace.