Agent Guide

What you place on steps in Project in the Marketplace edition are agents an administrator registered in the admin console (registered agents). A registered agent is a container image built with the SDK. What it does is settled by the image and by the contract the administrator registered.

Unlike the SaaS edition, you cannot create agents on the project screen, nor change their contents. Nor do you attach a goal (instructions), guardrails, a playbook or skills. All the project decides is which step to place it on, and the settings for each step.

	SaaS edition	Marketplace edition
Who provides the agent	Users create it in the project's editor	An administrator registers it under “Agent Settings” in the admin console
What settles how it behaves	Goal (instructions), guardrails, playbook, skills	The container image and the contract
What can be changed per step	(Fixing the agent affects every step it is placed on)	Step settings (workflows), environment variables (cycles)

Agents you can place

Press “Add Agent” on the left of the editor and the list switches to the list of registered agents. The SaaS edition's “New Agent” and “Create from a Schedule / Claw” are not there. The list shows the following registered agents for each type.

Type	Agents listed
Workflow	Enabled registered agents for which an administrator turned on “Use in workflows” and registered a contract. Only certified agents can be placed on steps
Cycle	Registered agents an administrator enabled (agents used in chat). Neither a contract nor certification is needed

In the workflow list, each agent is marked “Certified” or “Unavailable (not certified)”. An agent that is not certified cannot be placed. The reason it remains uncertified is an error in the contract, certification details (SDK version, adapter version, image digest, reference to test results, supported execution rules) that are missing or in the wrong format, or a mismatch between the effect mode in the certification details and the effect mode in the contract. Ask an administrator to register the contract and certification (Settings Guide).

When “No Agent is available for workflows. Register a contract in Admin” appears, there is not a single registered agent with a contract registered.

Only registered agents can be placed in a project. Registered agents and other agents cannot be placed in the same project.

Placing it on a step

Select an agent in the list, and press the destination step under “Place on a step” in “Agent details” on the right. You can also place it from “Add Agent” under the step's “Basic settings”.

When you place a registered agent on a step for the first time, it is saved to the project on the spot (“Agent placed” appears). It does not go into the draft as it would in the SaaS edition. Placing the agent on other steps as well, or removing it, does go into the draft. Applying works as in the SaaS edition (Design Guide).

The settings of a placed agent show “A registered customer Agent. Its behavior is defined by the contract in Admin; only per-step settings are edited here”.

In a workflow, place several on the same step and they run one at a time, in placement order. There is no “Run at the same time”. In a cycle, placements on the same step run without waiting for one another, on their own schedules or by webhook.

Step settings (workflows)

Select a registered agent placed on a workflow step, and “Step settings” appears under “Basic settings” in “Agent on this step”. Enter the values you want to change on this step, within the range the contract settles. Press “Save” and it goes into the project at once (it does not go into the draft, and “Apply changes” is not needed).

Field	What to enter
Parameters	Values for the contract's settings items. Items of type string, integer, number, yes/no and choice can be changed. Only the items you enter a value for are saved; items left blank keep the agent's default values. Items of types the screen cannot change show “○ item(s) cannot be edited here (defined by the administrator's contract)”
Connections	For each connection slot in the contract, choose from this project's connectors. Only the connections the administrator allowed for the slot can be chosen. If no allowed connection is among the connectors, add it first under the connectors in Settings
Input bindings	Bind the output of an agent on a preceding step as this agent's input file. Files set to “Provided in the case settings” are entered when the case starts

The output of the previous step does not pass to the next step automatically. In the SaaS edition the agent on the next step receives the output of the previous step, but in the Marketplace edition only the files you bind here are passed. Always bind any output you want handed over between steps under “Input bindings”.

If you start from the external API or a time trigger, put the required parameters and connections in the step settings. Those ways of starting cannot pass values at the start (Trigger Guide).

Reading the contract summary

“References & tools” on a placed agent shows a summary of the contract. The same summary also appears in “Agent details” when you select the agent in the list.

Item	Meaning
Effect on external systems	One of “Read only”, “Writes (safe to retry)” or “Writes (retry may duplicate)”. This settles whether it is retried automatically after a failure (Trigger Guide)
Execution limit	The time limit for one execution. “No execution limit” means up to the deployment's limit (24 hours by default)
Files	The input files the agent receives, marked “Required”, “Editable” or “Generated from parameters”
Outputs	The artifacts the agent produces. They can be bound to the input files of the next step
Connections	The contract's connection slots, and whether each is required

Environment variables (cycles)

A registered agent placed on a cycle step has “Environment variables”. These are the environment variables passed to the agent when it runs on this step.

• You can add new names. A name starts with an uppercase letter and uses uppercase letters, digits and _, up to 64 characters
• You can override values registered for the agent. Values registered as secrets cannot be overridden (“Secret, cannot be changed”)
• Names the administrator has blocked from change cannot be used (“Change blocked by admin”). Nor can reserved names (such as names starting with ASTER_ or MP_)
• Up to 32, with names and values totalling up to 16 KiB

When “Some saved environment variables are no longer allowed” appears, a name the administrator blocked later remains. Runs cannot start as is, so remove that name and save again. When “The admin's blocking settings are malformed, so environment variables cannot be used in this step” appears, ask an administrator to check the settings.

What the agent receives

No instruction text passes from the project to the agent. What it does is settled by the agent's image. What passes from the project is the following.

What the agent receives in a workflow

What it receives	Contents
Parameters	The contract's defaults, overlaid with the step settings and the case settings
Input files	The instruction files entered in the case settings, and the bound outputs of preceding steps
Connection tokens	The OAuth tokens of the connections chosen in the step settings
Review decision	At the review step just before: whether a person or the platform decided, whether it was approved or sent back, and the reason for a send-back or the comment on an approval written by a person

How to build an agent is in the Workflow Guide.

What the agent receives in a cycle

What it receives	Contents
Body	A fixed sentence: “This task is a periodic sweep of the project “(project name)”. Assigned step: (step name) (state id: …).” When started by a webhook, what was accepted follows (with a note to treat it as data, as input from outside; up to 8,000 characters)
Environment variables	The values registered for the agent, and the step's environment variables. In addition, values the platform settles, such as the IDs of the execution, the conversation and the project
Connector tokens	The tokens of this project's connectors that are enabled. Ones that are disconnected, or expired and cannot be refreshed, are not passed (an expired token is passed if it can be refreshed; reconnect the connector and they are passed from the next execution). It does not start when more than 8 connectors are enabled, when two connectors of the same kind are enabled, or when a token's variable name collides with another environment variable

A cycle agent must be built to exit once one round of processing is done. If it does not exit, the next start of that placement keeps being skipped. How to build it is in Your First Agent.

When you want to change how the agent behaves

Where to change the behaviour depends on what you want to change.

What you want to change	Who to ask
The values on this step (parameters, connections, input files, environment variables)	An owner changes them in the step settings or environment variables
The changeable items themselves, the effect on external systems, the execution limit, connection slots	An administrator changes the contract
The work the agent does, the contents of its output	The agent's developer rebuilds the image. Once the image changes, an administrator certifies it again (because it runs on the image with the certified image digest)