Agents
Agents, the prompts that agents build, retrieval without generation, execution and execution traces. Agents and prompt templates describes agents.
List agents
Returns one page of the agents that the key can read, in the list envelope. Query parameters filter the list by field values and set the order and the page.
Create an agent
Creates an agent from a prompt template and the placeholders that the template uses. Foundation4 validates the definition before storing the agent: the prompt contains at least one `system` message and one `user` message, the last message is a `user` message, every name in braces is a placeholder of the agent, no two placeholders share a name, every retrieval placeholder has a `target` that names a `query` placeholder, the search parameters are valid, and no placeholder names a search index in `index` or `indexes`. Agent executions run `query`, `similarity`, `mmr`, `search`, `hybrid` and `history` placeholders on the default search indexes of the pipeline of each request.
Get an agent
Returns the stored definition of an agent: the prompt template, the placeholders and the metadata. An agent stores no pipeline and no LLM, because each execution names both.
Update an agent
Changes the fields of an agent that the request names, and keeps the stored value of every omitted field. `prompt`, `placeholders` and `metadata` replace the stored values whole, and `description` accepts `null` to clear the description. Foundation4 validates the resulting prompt template and placeholders with the rules of agent creation, including stored values that the request leaves unchanged.
Delete an agent
Deletes an agent. Executions that name the deleted agent then return HTTP 404.
Execute an agent
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.
Get the prompt of an agent
Returns the prompt template and the placeholders of an agent as stored, without substitution, and `input_variables`: the names of the `query` placeholders whose values each execution supplies in `prompt`.
Run an agent retrieval dry run
Runs the retrieval placeholders of an agent against the pipeline named in the `x-pipeline-id` header, without calling an LLM, and returns the fragments that each retrieval placeholder retrieves. The body takes the `prompt`, `classification`, `path` and `filters` fields of an agent execution. 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. A request without `path` covers only the documents without a path. A client application uses the dry run to test the placeholders, filters and classifications of an agent.
Get an execution trace
Returns the trace of an agent execution that ran with `tracing` or `attributions` set to `true`: the input values, the fragments that each retrieval placeholder retrieved and the messages as sent to the LLM. For an execution with `attributions`, the trace also holds the answer and, for each sentence of the answer, the retrieved fragments that support the sentence, from the moment the answer is complete. Foundation4 keeps a trace for 60 minutes after the execution.