When To Use A Code Agent
Use a code agent for data transformations, or typed shaping between steps.
Use a simpler Orchestrate, Branch, API, or command flow when the behavior does not need custom TypeScript.
Set Up The Node
Open the automation builder.
Add
Codefrom the add-agent panel.Select the new code node.
Review
Checkpoint,Instructions,Tools,Inputs, andOutputs.Define the inputs the code will read and the outputs later steps will need.
Treat The Editor As A Function Body
Write TypeScript only.
Treat the editor as the body of an async function, not as a full file. Execution occurs in a linear fashion.
Use the generated globals:
inputs,tools,context.Do not add imports,
require, or package-install commands.Watch the generated types and autocomplete. Magical injects declarations from the current inputs, outputs, shared inputs, and available tools.
const customerId = inputs.customerId as string; return { status: 'success', message: 'Prepared customer lookup', output: { customerId }, };Call Another Step From Code
Wire the downstream agent on the canvas.
Use the typed
toolsobject instead of trying to import or invoke steps manually.The common pattern is
await tools.callSpecializedAgent(...)for a callable child agent.Check the result, then return the next output shape.
const lookup = await tools.callSpecializedAgent({ agent: { agentId: '<child-agent-id>', args: { customerId: inputs.customerId }, }, }); if (lookup.status === 'fail') { return { status: 'fail', message: lookup.message, }; } return { status: 'success', message: 'Customer lookup completed', output: { customerSummary: lookup.output, }, };Always Return A Final Result
End the code with a
return.Return
status: 'success'orstatus: 'fail'.Include a clear
message.Include
outputwhen the node should hand structured data to later steps.Magical handles the final
reportStopcall after your code returns, so your job is to return the final result object instead of callingreportStopyourself.
Fix Validation Errors Before Saving
Save blockers show
Code Validation Errorswith line numbers.Type errors come from the generated TypeScript context.
Security errors flag forbidden identifiers such as
require,import(),fetch,process,console, and similar globals.Resolve those errors before saving or publishing.
Team Guardrails
No package downloads or package imports inside a code node.
Keep code small, typed, and readable enough for another builder to review quickly.
Ask for regular code review on code-node work. Treat it as engineering work, not as a black-box prompt.
Important Boundaries
A code agent still uses the automation's configured
Inputs,Outputs,Tools, and downstream graph.Code nodes live inside the builder route
/automations/[automationId]; they do not create a separate script file or package.If a simpler agent or command can do the job, prefer the simpler node.