AI Agent

Runs an autonomous AI agent that investigates a goal using allowed tools and reports whether it completed or stopped.

@lainstack/ai/agent · AI

How to use it

Runs an AI agent that works toward a goal over several steps, optionally using tools, and reports whether it finished. Choose it for work that needs investigation or tool use. For one model call use @lainstack/ai/prompt. For one label from a fixed list use @lainstack/ai/classify.

• Two ports: “completed” and “stopped”. “stopped” covers every terminalReason other than completed, such as an incomplete answer, tool error, denied authority or step limit. Wire both.
• Messages: goal is the system message (up to 2,000 characters). userPromptTemplate is the run request (up to 16,000 characters). Up to 10 files can be attached. Files and filenames go to the AI provider.
• profile adds platform instructions before goal. It never grants tools or authority. Values: operations (default), workspace_assistant (helps people in chat), automation_reviewer, escalation_triager, plain (no platform text).
• allowedTools lists named tools (at most 64). Leave it empty for a reasoning-only agent.
• includeWorkspaceTools (default true) adds read-only workspace tools. In the code they are attached only when the run starts from trigger.agent.
• writeMode is off, ask or smart. Writes need an interactive chat run. In ask, a person approves each change. In smart, only low-risk draft writes skip approval. An approval granted for an older graph revision is refused.
• maxSteps defaults to 25 and cannot exceed 50. A run lasts at most 30 minutes.
• Answer: outputMode text gives replyText. json gives answer, typed by answerSchema. fields gives answer with your output fields; only scalar and enum fields can be referenced. A missing required field ends on “stopped” with incomplete_answer.
• With trigger.agent and no reply set, the reply is the replyText of the only agent block. With two or more agent blocks, set the trigger’s reply source.

Settings

Setting	Key	Type	Details
Profile	profile	One of Operations, Workspace assistant, Automation reviewer, Escalation triager, Plain	What the platform tells the agent before your system message. Operations: a general operations agent. Workspace assistant: helps people in chat find and act on workspace work. Automation reviewer: diagnoses runs and proposes fixes. Escalation triager: works out what blocks an escalation and who should act. Plain: no platform instructions or workspace details. Default operations.
System message (required)	goal	Text	Persistent instructions that define the agent’s role, rules, and definition of done.
User message (required)	userPromptTemplate	Text	The run-specific request. Type plain text and insert trigger or upstream values as references.
Files	files	Value
Connection (required)	credentialId	Connection	The workspace model credential to use for this agent.
Model (required)	model	Text	The model to use from the selected connection. At most 200 characters.
Thinking effort	reasoningEffort	Text	Optional reasoning effort supported by the selected model. At most 32 characters.
Allowed tools	allowedTools	Connections	Named tools this agent can use. Leave empty for a reasoning-only agent. At most 64 items.
Workspace tools (read-only)	includeWorkspaceTools	Yes or no	Also give this agent the platform’s read-only workspace tools. Access remains limited to this workspace and the agent’s mandate. Default true.
Write access	writeMode	One of Off, Ask, Smart	Controls whether this Agent can propose or execute workspace changes. The user can approve changes only when write access is enabled. Default off.
Maximum steps	maxSteps	Number	Maximum number of steps (1–50). The agent stops when this is reached.
Expense guardrail (USD)	maxBudgetUsd	Number	Stops before the next call when the public-list estimate reaches the limit. One admitted call can overshoot. Models without a provable public-list price count as $0 toward this guardrail.
Answer format (required)	outputMode	One of Text, JSON, Fields	How this agent returns its answer. Default text.
Output fields	outputSchema	List	Fields the agent must populate in its final answer. Leave empty to take its reply text as the answer. At most 64 items.
Answer shape	answerSchema	Value	Optional. The fields, records, and lists the answer must contain. Later steps can reference each declared field.

Outputs

Output	Path	Type
Answer	answer	Value
Reply text	replyText	Text
Agent outcome	agentOutcome	Choice
Terminal reason	terminalReason	Choice
Steps executed	stepsExecuted	Number
Tool call count	toolCallCount	Number
Transcript	transcriptRef	Value
Answer issues	answerIssues	List
Stored answer	answerRef	Value

Exits

Exit	Port	Notes
Completed	completed
Stopped	stopped