---
title: "How ProxyAI Agent Tasks work"
description: Understand task instructions, compiled versions, tool permissions, triggers and run records.
canonical: https://www.proxyai.app/docs/agent-tasks
last-updated: 2026-10-19
---

> For the complete documentation index, see [llms.txt](https://www.proxyai.app/llms.txt). Request public content pages with `Accept: text/markdown`.

# How ProxyAI Agent Tasks work

An Agent Task is a saved job for one bot. It combines an instruction, tools it may use, a trigger and guardrails. A run is one execution of that job. The Run Log records what happened; a connector supplies access to a service the task is allowed to use.

Start with the [Agent Tasks dashboard guide](https://www.proxyai.app/help/add-ons/agent-tasks-guide) for the console and library. These documents explain the execution model behind that interface.

## From brief to active version

A library recipe supplies a prepared script and tool configuration. Adding it fills the chosen settings, creates its first version and activates the task. Check the displayed schedule before adding it.

A task built from your own brief is compiled into an executable version. That version pairs the generated script with a manifest: the tools, their permissions and bindings, prompts and guardrails used by the run. Review the compiled plan before deploying it.

A live run uses the task's active version. A test run uses the latest compiled version so you can try a draft without making it the live version. Compiling a change and deploying it are distinct actions in the custom builder.

## Trigger, queue, execute, record

A schedule, event, webhook, customer chat request or manual action can queue a run. The runtime claims queued work and dispatches the pinned version to an isolated runner. Tool calls return through ProxyAI, where the run's grants, account boundaries and guardrails are checked.

Completion records the result, tool steps, cost and status. A run can also stop for approval, fail or be killed. A queued request is not proof that the job completed; inspect its Run Log result.

## Choose the next topic

- [Execution, test mode and approvals](https://www.proxyai.app/docs/agent-tasks-execution): what runs, what can be held, and what approval means.
- [Schedules and triggers](https://www.proxyai.app/docs/agent-tasks-schedules): activation, timing, events, manual runs and overlapping work.
- [Permissions and credentials](https://www.proxyai.app/docs/agent-tasks-permissions): tool grants, connected services and customer-called tasks.
- [MCP connector](https://www.proxyai.app/docs/mcp): the restricted report recipes available to external assistants.

## Costs and limits

Adding a library recipe does not call a model. Compiling a custom brief and executing a task can use paid AI or tool services. Test runs can also incur normal charges. Agent capacity, entitlement, available credits and per-run guardrails apply independently of the trigger.

Use the pricing page and the cost shown in your account for current charges. A spend cap limits a run; it does not make retries or test runs free.