Run an Agent with files and structured results

Use Console to run an Agent on a specific task. Supply input values and files, then inspect its answer and generated documents. Your application can run the same Agent through the Connector API.

Prepare the Agent

You need permission to manage Agents. Start with Create a knowledge Agent if you need an Agent.

1. Open the Agent's settings.
2. Set its instructions.
3. Choose its model.
4. Select its permitted resources.
5. Open Inputs & outputs.
6. Enable Sandbox if the task needs calculations or files.
7. Add named Input files and Output files where needed.
8. Mark each required file in its file settings.
9. If your application requires a fixed input format, set Input schema.
10. If it requires a fixed result format, set Output schema.
11. Save the Agent.

A schema defines the structure of the input or result. Leave the optional schemas blank when any JSON structure is suitable. The model picker includes Claude Opus 5.5. Select a model that suits the task and review its usage after a trial.

Prepare reusable sources

Under Inputs & outputs → Resources, select the sources each run needs.

• Include in context supplies selected Knowledge Base documents to the Agent.
• Available in sandbox supplies selected documents and uploaded reference files for file processing.

Use a saved rubric, document template, or reference workbook when each run must use the same material. The Agent and the person running it must have access to the selected Knowledge Base content. A run uses the source versions captured when it starts. Later edits do not change that run's sources. These resources apply to Console, API, and Evals runs.

Run a task in Console

1. Open Agents → Console.
2. Select the Agent.
3. Enter the input through Fields or JSON.
4. Attach the files required by the Agent.
5. Keep Preview selected for the first check.
6. Choose Run.
7. Open Output to inspect the answer and files.
8. Open Activity to inspect the conversation, tools, and usage.

For example, provide a fictional learner's essay and a rubric. Ask the Agent to return a score and a feedback document. Check the score against the rubric and open the document before you use the result. Use Open logs to inspect the recorded run.

Preview limits workspace access to reading and disables course creation and external network access. It can still generate local files. Live permits the actions allowed by the Agent's configuration and current permissions. Choose Live only when those actions are part of the task.

Call the Agent from your application

1. In Developers, create or edit a Connector.
2. Enable Run Agents.
3. Select the Agents that the Connector may run.
4. Copy the API example from Console.
5. Keep the Connector token on your server.

An empty Agent selection grants no Agent access. The selected Agent's capabilities and the calling member's current permissions still apply.

Send POST /api/v1/agents/run with agentId, input, files, and mode. Set mode explicitly to PREVIEW or LIVE. The API defaults to LIVE when you omit the mode. Use an Idempotency-Key for the request. Reuse the same key and body if you retry that request.

The response contains data.runId. Send that ID to agents/run-get until the task finishes. A successful task returns output, files, and a summary. Failed, cancelled, or timed-out tasks need review. Use agents/run-cancel to cancel a task.

For an input file, call agents/file-upload with its Agent, filename, MIME type, and byte size. Upload the bytes to the returned URL. Call agents/file-complete, then put the file ID in the run's named files map. For an output download, call agents/file-download with its fileId.

See Use the API and OpenAPI reference for authentication and current request schemas. Continue with Test an Agent with Evals or Share an Agent report.