agentInvoke (agent)

Source: src/workflows/shared/actions/agent.ts. Runs an AI SDK tool-loop agent that can, when explicitly enabled, call httpRequest through an allowlisted connection.

Configuration

Requires OPENAI_API_KEY in the project Environment variables.
HTTP is disabled unless http.enabled is true.
Use http.allowedConnections to restrict which connection profile the model can call.

Usage

typescript

import { agentInvoke } from "@/workflows/shared/actions/agent";
import { createWorkflowActionContext } from "@/workflows/shared/actions/context";

const context = createWorkflowActionContext(record);
const result = await agentInvoke({
  record,
  context,
  stepKey: "agent",
  prompt: "Summarize the /health endpoint response.",
  http: {
    enabled: true,
    allowedConnections: ["production-api"],
  },
});

Failure behavior

Missing prompts, missing OPENAI_API_KEY, disallowed HTTP connections, and action failures fail the agent step and the enclosing workflow can mark the run failed with the existing lifecycle helpers.

The action records the generated text on the agent step and returns the full structured result to the workflow, so downstream approval or review steps can use result.text.

Agent steps also record diagnostics on the timeline: model, finishReason, tool calls, and token usage. Token usage is written to agentUsage for dashboard token-usage trends by day and workflow. Flowman stores tokens and model ids only in v1; dollar cost can be derived later from a maintained pricing table.