> ## Documentation Index
> Fetch the complete documentation index at: https://docs.welesai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an agent workflow

> Build an agent-only (API) workflow in Weles: choose a model, add tools and variables, run it from Chat, and invoke it through the API.

An **Agent-Only (API)** workflow accepts a question and an optional file, then runs its agent stages in order. It can also be selected in Chat. Use an OCR pipeline instead when processing documents through extraction and verification stages.

## Prerequisites

* An administrator account and a valid license for the intended feature. Chat requires the chat entitlement; the workflow invoke endpoint checks the document processing (`idp`) entitlement.
* An active, tested [LLM provider](https://docs.welesai.com/administration/llm-providers.md) and a model compatible with the intended inputs and tool calls.
* Network access, credentials, and permissions for any tool you enable. For regular users, assign workflow access in **User Config**.

## Create the flow

1. Open **Workflows**, select the plus button, enter a name, choose **Agent-Only (API)**, and select **Create**. Weles creates the **API Input** start stage automatically.
2. Select **Add Stage**. The new stage is an **AI Agent** in an agent-only workflow. Expand its settings and give it a meaningful name.
3. Under **Model & Prompt**, choose an available model, enter a system prompt, and adjust **Temperature**, **Max tokens**, and the optional context size for your use case. For example: “Answer the user's question using the available tools when needed. State uncertainty and return the answer in a JSON field named `answer`.”
4. Open **Variables**, select `input_question` and any other required input, and add `answer` as an output variable. Input options also include `input_file_content`, `input_filename`, and output variables from previous agent stages.
5. Open **Tools** and add only the tools the agent needs. Follow [Add and configure tools](https://docs.welesai.com/workflows/agent-tools.md). For a minimal test, leave tools empty and ask a question that does not require external data.
6. Select **Save** on the changed stage. Each edited stage has its own Save control; save every changed stage. Add further agent stages if needed, select earlier output variables as their inputs, and save them too.
7. Under **User Config**, assign the workflow to the intended users. Open **Chat**, select the workflow, start a session, and submit a non-sensitive test question. Verify the answer and, when tools are enabled, check the tool activity and results.

The agent's model name is sent to the active LLM provider. The builder's model dropdown is labeled **Model Ollama** but uses the active LLM provider's model-list endpoint; check the chosen model is compatible with that provider. A connection test does not guarantee tool-calling support.

## How variables work

When input variables are selected, the agent receives those existing context values. File/image and internal context keys are also passed through; an empty input selection passes the entire workflow context, so it is not a privacy boundary. Set explicit inputs and avoid placing unnecessary sensitive data in the context.

The agent is instructed to return JSON with the configured output keys. Weles keeps the raw response and attempts to parse JSON; only declared keys are copied to the downstream context when output variables are set. If output is invalid JSON or a key is missing, a later stage may not receive the value. Test the actual model's output. Avoid treating the text output as guaranteed structured data.

## Invoke through the API

The endpoint accepts multipart fields `question`, optional `file`, and `wait`. Create an API key in Weles and give its owner access to the workflow, or use a valid user bearer token. This example uses a key supplied through a protected environment variable, not a literal secret:

```bash theme={null}
curl --fail-with-body \
  -H "X-API-Key: $WELES_API_KEY" \
  -F "question=Summarize the supplied text." \
  -F "file=@sample.txt" \
  -F "wait=true" \
  "https://your-weles.example/api/workflows/WORKFLOW_ID/invoke"
```

Replace the URL and workflow ID. Omit the file field for a question-only request. `wait=true` executes before returning; with `wait=false` the response contains the run ID and the task is queued. Query `GET /api/workflow-runs/RUN_ID` with the same authentication to inspect status and context. Verify reverse-proxy paths for your deployment, keep tokens out of shared command histories and logs, and use only authorized test data.

## Troubleshooting

If the workflow is missing, check its mode and user assignment. For a `403`, check access and the relevant license entitlement. If answers ignore a tool, check that the stage was saved, the tool is enabled and reachable, the model supports tool calls, and its tool-call logs show a successful result. If structured output is missing, inspect the raw response and JSON keys. Consult [troubleshooting](https://docs.welesai.com/administration/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.