---
sidebar_label: AI nodes
toc_max_heading_level: 3
doc_id: 529d54fa-20b1-4ac2-9809-ebd2098cc748
description: >-
  Hand non-deterministic tasks to AI inside a workflow: agents that analyze
  data, use other workflows as tools, and return structured results.
keywords:
  - workflows
  - AI nodes
  - agents
  - claude
  - AI automation
  - nullplatform
---

# AI nodes

Some steps can't be written as rules: reading a documentation page that has no API behind it, judging whether a metric trend looks healthy, summarizing a comment thread. An AI node hands that one step to an agent, while the workflow around it stays deterministic.

## When to use an AI node

Use regular nodes for everything you can express as a query, a condition, or code; they're faster, cheaper, and give the same answer every time. Use an AI node when the input is unstructured or the task needs judgment. Keep the AI part of a workflow small: regular steps fetch and validate, the agent does the one thing only it can do, and regular steps check its output before acting on it.

## Run an agent as a step

The `claude-code-agent` node runs a prompt through an agent loop and returns a result to the rest of the workflow. You give it a system prompt, a user prompt, and optionally an `outputSchema`. When the agent replies with JSON matching the schema, those fields become the step's outputs, ready for the next node to read.

Here's the step the Lambda runtime lifecycle suite uses to read the AWS docs page, a page with no API behind it:

```yaml
- id: scrape
  type: module
  plugin_type: claude-code-agent
  name: "Scrape AWS runtime tables"
  inputs:
    primary_url: "https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html"
  config:
    allowedHosts:
      - docs.aws.amazon.com
    systemPrompt: |
      You fetch AWS documentation pages and extract structured data.
      Return ONLY the JSON object requested by the user prompt.
    userPrompt: |
      Fetch ${{ inputs.primary_url }} and build the runtime catalog...
```

The agent runs isolated from everything else: it can only reach the hosts you allow, and anything it needs (like a nullplatform token) is handed in explicitly through `env` entries referencing [secrets](/docs/workflows/building-blocks/secrets-and-variables). Budgets are yours to set: `maxIterations` caps the number of reasoning turns, `maxTokensTotal` caps spend, and `model` picks which model runs the step; the editor lists the ones available to you.

Inside the node's prompts, reference the step's own declared `inputs.*`, as above. Wire values from other steps into the `inputs` block first rather than referencing `steps.*` directly in the prompt.

## Give the agent other workflows as tools

You can give an agent tools, and each tool is another workflow:

```yaml
config:
  tools:
    - type: workflow
      workflow: deploy_start
      name: deploy_start
    - type: workflow
      workflow: deploy_metrics
      name: deploy_metrics
  outputSchema:
    type: object
    required: [action, detail]
    properties:
      action: { type: string, enum: [wait, done] }
      wait_seconds: { type: number }
```

The agent decides, and the tools act. Each tool call starts a child run of that workflow, and the agent waits for its result before deciding what to do next. The tool's arguments come from the target workflow's declared inputs, so describe those inputs well: the descriptions are the agent's instructions for using the tool. Credentials never enter the model's context, because tool workflows resolve their own secrets when they run. Tool outputs do reach the model, so a tool workflow should never return a secret.

When the agent has to act, wait, and reassess (a progressive deployment, for example), enable a resumable session. It keeps one conversation across every visit to the node within a run, so the agent remembers what it did on the previous turn.

## Next steps

- [Nodes](/docs/workflows/building-blocks/nodes): the deterministic steps around the agent
- [Expressions](/docs/workflows/building-blocks/expressions): wiring agent outputs into the next step
- [Secrets and variables](/docs/workflows/building-blocks/secrets-and-variables): handing credentials to an agent safely