AI

The AI action node invokes Port AI directly from your workflow. It supports two modes of operation: invoking an AI agent by identifier, or invoking Port AI with custom configuration.

The workflow pauses execution after sending the AI request and automatically resumes once the AI invocation completes (or fails).

Modes

Invoke AI Agent

Use the AI_AGENT type to invoke a pre-configured AI agent by its identifier. The agent's tools, system prompt, and domain configuration are defined on the agent itself — you only need to provide the prompt.

Configuration

Field	Type	Description
type	"AI_AGENT"	Required. Must be "AI_AGENT"
agentIdentifier	string	Required. The identifier of the AI agent to invoke
userPrompt	string	Required. The prompt or query to send to the agent
outputSchema	object	JSON Schema that defines the expected structure of the AI response. When provided, the AI will generate a structured JSON object matching the schema instead of free-form text

Example

Invoke an incident response agent to analyze a service's health:

{
  "identifier": "analyze-health",
  "title": "Analyze Service Health",
  "config": {
    "type": "AI_AGENT",
    "agentIdentifier": "incident-response-agent",
    "userPrompt": "Analyze the health of service {{ .outputs.trigger.service }} and provide a summary of any issues"
  }
}

Invoke AI

Use the AI type for general-purpose AI invocations where you configure the tools, system prompt, and other parameters directly in the node.

Configuration

Field	Type	Description
type	"AI"	Required. Must be "AI"
userPrompt	string	Required. The prompt or query to send to Port AI
systemPrompt	string	Instructions that guide the AI's behavior, role, and operational rules
tools	string[]	Required. List of regex patterns to match against available tool names. See available tools
provider	string	The AI provider to use. If not specified, the default provider is used
model	string	The AI model to use. Must be specified together with provider
outputSchema	object	JSON Schema that defines the expected structure of the AI response. When provided, the AI will generate a structured JSON object matching the schema instead of free-form text

Provider and model

The provider and model fields must both be specified together, or both omitted. When omitted, the organization's default AI provider and model are used. For more information, see LLM providers management.

Example

Invoke Port AI with a custom system prompt and specific tools to generate a deployment summary:

{
  "identifier": "generate-summary",
  "title": "Generate Deployment Summary",
  "config": {
    "type": "AI",
    "userPrompt": "Generate a deployment summary for service {{ .outputs.trigger.service }} in the {{ .outputs.trigger.environment }} environment",
    "systemPrompt": "You are a deployment analyst. Provide concise, actionable summaries of deployment status and any risks.",
    "tools": ["search_entities", "get_entity"]
  }
}

Structured output

Both AI modes support structured output through the outputSchema field. When you provide a JSON Schema, the AI generates a structured JSON object that conforms to the schema instead of free-form text. This is useful when you need to parse the AI response programmatically in subsequent workflow nodes.

Schema format

The outputSchema must be a valid JSON Schema with type: "object":

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" },
      "severity": { "type": "string" },
      "recommendations": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["summary", "severity"]
  }
}

When outputSchema is provided, the response output contains the JSON object as a string. You can parse specific fields using JQ in subsequent nodes.

Example with structured output

{
  "identifier": "analyze-service",
  "title": "Analyze Service Health",
  "config": {
    "type": "AI_AGENT",
    "agentIdentifier": "service-analyzer",
    "userPrompt": "Analyze the health of service {{ .outputs.trigger.service }}",
    "outputSchema": {
      "type": "object",
      "properties": {
        "status": { "type": "string" },
        "issues": {
          "type": "array",
          "items": { "type": "string" }
        },
        "score": { "type": "number" }
      },
      "required": ["status", "score"]
    }
  }
}

Structured output behavior

When structured output is requested, the AI must generate a valid JSON object matching the schema. If the AI fails to generate valid output, the node will fail with an error.

Outputs

When the AI invocation completes, the node produces the following outputs:

Field	Description
response	The AI response. When outputSchema is provided, this contains the structured JSON object as a string. Otherwise, it contains free-form text
invocationIdentifier	The identifier of the AI invocation entity
error	Error message (only present if the invocation failed)

Reference these outputs in subsequent nodes:

{{ .outputs.analyze_health.response }}
{{ .outputs.analyze_health.invocationIdentifier }}

When using structured output, you can parse specific fields from the JSON response using JQ:

{{ .outputs.analyze_health.response | fromjson | .status }}
{{ .outputs.analyze_health.response | fromjson | .score }}

Examples

Invoke an AI agent and notify Slack with the result

This workflow invokes an AI agent to analyze a service and sends the AI response to Slack:

Workflow example (click to expand)

{
  "identifier": "ai-analyze-and-notify",
  "title": "AI Analysis with Notification",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Select Service",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "service": {
              "type": "string",
              "format": "entity",
              "blueprint": "service",
              "title": "Service"
            }
          },
          "required": ["service"]
        }
      }
    },
    {
      "identifier": "ai-analyze",
      "title": "Analyze with AI Agent",
      "config": {
        "type": "AI_AGENT",
        "agentIdentifier": "service-analyzer",
        "userPrompt": "Analyze the health and status of service {{ .outputs.trigger.service }}. Include any recent incidents and scorecard results."
      }
    },
    {
      "identifier": "notify-slack",
      "title": "Send Analysis to Slack",
      "config": {
        "type": "WEBHOOK",
        "url": "https://hooks.slack.com/services/xxx",
        "method": "POST",
        "body": {
          "text": "AI Analysis for {{ .outputs.trigger.service }}:\n{{ .outputs[\"ai-analyze\"].response }}"
        }
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "ai-analyze"
    },
    {
      "sourceIdentifier": "ai-analyze",
      "targetIdentifier": "notify-slack"
    }
  ]
}

Generate an incident summary on service degradation

This event-driven workflow detects service degradation and uses AI to generate an incident summary:

Workflow example (click to expand)

{
  "identifier": "ai-incident-summary",
  "title": "Generate Incident Summary on Degradation",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "On Service Degraded",
      "config": {
        "type": "EVENT_TRIGGER",
        "event": {
          "type": "ENTITY_UPDATED",
          "blueprintIdentifier": "service"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.before.properties.healthStatus == \"healthy\"",
            ".diff.after.properties.healthStatus != \"healthy\""
          ],
          "combinator": "and"
        }
      }
    },
    {
      "identifier": "ai-summarize",
      "title": "Generate Incident Summary",
      "config": {
        "type": "AI",
        "userPrompt": "Service {{ .outputs.trigger.diff.after.title }} has degraded from {{ .outputs.trigger.diff.before.properties.healthStatus }} to {{ .outputs.trigger.diff.after.properties.healthStatus }}. Analyze the service and its dependencies to generate a concise incident summary with potential root causes.",
        "systemPrompt": "You are an incident response analyst. Provide structured incident summaries with severity assessment, affected components, and recommended next steps.",
        "tools": ["search_entities", "get_entity"]
      }
    },
    {
      "identifier": "create-incident-entity",
      "title": "Create Incident Record",
      "config": {
        "type": "UPSERT_ENTITY",
        "blueprintIdentifier": "incident",
        "mapping": {
          "identifier": "incident-{{ .outputs.trigger.diff.after.identifier }}-{{ now | todateiso8601 }}",
          "title": "Degradation: {{ .outputs.trigger.diff.after.title }}",
          "properties": {
            "summary": "{{ .outputs[\"ai-summarize\"].response }}",
            "status": "open",
            "detectedAt": "{{ now | todateiso8601 }}"
          },
          "relations": {
            "service": "{{ .outputs.trigger.diff.after.identifier }}"
          }
        }
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "ai-summarize"
    },
    {
      "sourceIdentifier": "ai-summarize",
      "targetIdentifier": "create-incident-entity"
    }
  ]
}