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. 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 set to true, Foundation4 records a trace for 60 minutes and returns the trace identifier in the x-foundation4ai-tracing-id response header.
Permissions. Execute on the agent, the pipeline and the LLM.
Agents and prompt templates describes execution, and LLMs describes the requirements on the model server and the response formats.
Request
Responses
- 200
- 400
- 401
- 404
- 500
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 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 to true. GET /tracing/{execution_id} returns the trace.
A required header is missing (plain text 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), or the execution cannot run (Invalid parameter). details.error holds the reason, such as Missing prompt variables: <names> or API key is required for OpenAI provider.
The authentication headers are missing or invalid, or the API key is inactive or expired. Errors lists the messages.
The agent (Agent not found), the pipeline (Pipeline not found) or the LLM (LLM with id <id> not found) does not exist, or the key lacks execute permission on that object. A placeholder that names an embedding model outside the pipeline returns Embedding Model with id <id> not found.
Retrieval failed (Internal error, with the cause in details.error), or, with "stream": false, the model server returned an error or could not be reached (Stream error: <reason>).