aidp-agent-flows — agent flow lifecycle

Discover, author, deploy, and run agent flows through the AIDP REST AgentFlows API via oci raw-request. No MCP and no ai-data-engineer-agent repo are required.

CLI gap (no invented commands): the official aidp CLI v1.0.0 has no agent-flow group (the Python SDK ships agent_flow models only). Agent-flow CRUD / deploy / run / sessions / guardrails all stay on the REST API (LA 20240831, may be unprovisioned). Do not assume an aidp agent-flow command exists — see references/aidp-cli-map.md.

LA + verify-first (no-fabrication): AgentFlows is Limited Availability on 20240831 (not in the GA aiwap/ docs but still active). Path is workspace-scoped: …/dataLakes/<ocid>/workspaces/<ws>/agentFlows returned 200 live (2026-06-10, oaseceal); the lake-level …/dataLakes/<ocid>/agentFlows (no workspace) 404s — that earlier 404 was the wrong path, not necessarily missing provisioning. Still confirm the route with a live read before any write (provisioning can vary by tenancy), and record results in references/rest-endpoint-map.md. Frame the whole lifecycle as LA, not GA.

When to use

• "List/show agent flows" (read). "Create/update/deploy/run a flow", "manage flow sessions/guardrails", "attach compute to a flow" (write).
• "Connect my flow/agent to a remote MCP server / OAC MCP / ADW Select AI MCP / an MCP tool" → add an MCP_TOOL node (see the Native MCP Client Support section below).

Auth + base URL

Use the auth ladder and base URL in references/oci-raw-request.md: https://aidp.<region>.oci.oraclecloud.com/20240831/dataLakes/<dataLakeOcid>/…, --profile DEFAULT (api_key); on 401/403/"Security Token" refresh AIDP_SESSION and retry with --auth security_token.

Read / discover (REST — primary)

• GET …/workspaces/<ws>/agentFlows — enumerate flows (workspace-scoped; live 200 on oaseceal 2026-06-10). GET …/workspaces/<ws>/agentFlows/<key> — flow detail for authoring.
• A 404 usually means you dropped the …/workspaces/<ws>/ segment (the lake-level …/agentFlows doesn't exist) — re-check the path first; if the workspace-scoped path also 404s, AgentFlows isn't provisioned in this tenancy (see note above) — surface that rather than assuming the flow is missing.
• Optional accelerator: if an aidp MCP happens to be configured, list_agent_flows is a convenience read over the same control-plane. It is not required and not the primary path.

Write (REST, LA 20240831, via oci raw-request)

All flow/session paths are workspace-scoped (…/dataLakes/<ocid>/workspaces/<ws>/…); guardrails are lake-scoped.

• …/workspaces/<ws>/agentFlows (create / get / update / delete); …/agentFlows/<key>/permissions, …/agentFlows/<key>/sessionMetrics. Validate the definition before deploy.
• Deploy is a workspace action: POST …/workspaces/<ws>/actions/deployAgentFlow (and …/actions/redeployAgentFlow) — async (202 + operation key); attach AI compute in the body.
• …/workspaces/<ws>/agentFlowSessions (create / run sessions); …/agentFlowSessions/<key>/chatHistory, …/agentFlowSessions/<key>/traces/<traceKey>.
• …/agentFlowGuardrails — lake-scoped (…/dataLakes/<ocid>/agentFlowGuardrails, not under a workspace).

Attach a remote MCP server to a flow — Native MCP Client Support (LA)

AIDP's LA Native MCP Client Support lets a flow call out to a remote MCP server (OAC /api/mcp, ADW Select AI MCP, OIC, or any MCP-compatible service) by adding an MCP_TOOL node to the flow. AIDP is the client here — it does not host an MCP server (all standalone /mcp endpoints 404). This is distinct from the optional local-stdio aidp MCP that can back this plugin's skills (see references/mcp-tool-map.md) — different thing, different direction.

Verified live 2026-06-10: GET …/workspaces/<ws>/agentFlows → 200 on the oaseceal tenancy (IAD). That agentFlows collection is the surface that holds MCP_TOOL nodes; there is no separate /mcp path. Provisioning still varies by tenancy (a prior env returned 404 — see the LA note above), so read first.

MCP_TOOL node shape (official SDK CreateMcpToolNodeDetails → wire JSON; lives in the flow's node graph):

{
  "type": "MCP_TOOL",
  "name": "oac-mcp",
  "description": "Read KPIs from OAC via MCP",
  "positionX": 0, "positionY": 0,
  "toolConfig": {
    "endpoint": "https://<oac-host>/api/mcp",
    "auth": { "authType": "OAUTH" },
    "allowedTools": [
      { "instruction": "use for KPI lookups", "argOverrides": {}, "tool": { "__": "McpToolObject from the fetch step" } }
    ],
    "customHeaders": {}
  },
  "toolKey": null, "inputSchema": {}, "configuration": {}
}

• toolConfig.endpoint — the remote MCP URL to connect to (verified field).
• toolConfig.auth.authType ∈ NO_AUTH · BEARER_TOKEN · OAUTH · OCI_RESOURCE_PRINCIPAL (verified enum). For BEARER_TOKEN, carry the token via customHeaders ({"Authorization":"Bearer <…>"}) or the matching auth subtype — confirm the exact per-auth credential fields against the live API / SDK auth subtype before authoring; never inline a secret into a committed file (prefer the credential store — see aidp-credentials).
• toolConfig.allowedTools[] — restrict which remote tools the flow may call: { instruction, argOverrides, tool } (verified shape).
• toolConfig.customHeaders — extra request headers (dict[str,str]).

Introspect + test the remote MCP first (bind real tool names, not guesses):

• Fetch the MCP's objects — FetchMcpObjectsDetails { agentFlowId, type ("Tool"|"prompt"|"resource"), mcpTool, limit, page, paramValues } → lists the tools/prompts/resources the remote MCP exposes; use the returned McpToolObjects to populate allowedTools.
• Test connection / a tool — TestMcpConnection / TestMcpExternalTool { testType, externalToolName, paramValues } before deploy.

Author it (REST via oci raw-request, LA 20240831): create/update the flow with the MCP_TOOL node in its node list at …/workspaces/<ws>/agentFlows[/<key>], validate, then deploy per the Workflow below. Persist the node payload to .aidp/payloads/ and confirm first.

Verify-first (no-fabrication): the toolConfig / auth / allowedTools field names above are from the official SDK models (CreateMcpToolNodeDetails, McpToolConfiguration, Auth, AllowedToolDetails) — confirmed. The full flow node-graph wrapper and the per-authType credential fields should be confirmed by round-tripping an existing flow (GET …/agentFlows/<key>) before a first write, and recorded in rest-endpoint-map.md.

Publish a flow as an A2A agent (agent card) — outbound discovery (LA)

A2A publishing exposes a deployed flow as an agent that external agents can discover and call. This is the outbound-publishing direction and is distinct from the two MCP/agent directions above:

Mechanism	Direction	Role
EXTERNAL_AGENT node	inbound — your flow calls another agent	flow is the caller
MCP_TOOL node	outbound — your flow connects out to a remote MCP server	flow is an MCP client
Agent card (A2A)	outbound publishing — external agents discover + call your flow	flow is the published agent

Set it on the flow body, not as a node: the create/update flow body carries a top-level agentCardConfig field (wire agentCardConfig, type AgentCardConfigDetail — confirmed on create_agent_flow_details.py:99, update_agent_flow_details.py:97, and read back on agent_flow.py:186).

AgentCardConfigDetail (verified wire fields — agent_card_config_detail.py:60-68):

{
  "agentCardConfig": {
    "name": "supplier-spend-agent",
    "description": "Answers supplier-spend questions over the gold lakehouse",
    "version": "1.0.0",
    "documentationUrl": "https://…",
    "capabilities": { "isStreaming": true },
    "provider": { "organization": "Oracle", "url": "https://…" },
    "skills": [
      { "id": "spend_lookup", "name": "Supplier spend lookup",
        "description": "Returns spend by supplier", "tags": ["finance"], "examples": ["top 10 suppliers by spend"] }
    ]
  }
}

Field	Wire	Type / shape
name (required)	name	str — human-readable agent name
description	description	str
skills[]	skills	AgentCardSkillDetail { id*, name*, description, tags[], examples[] } (agent_card_skill_detail.py:50-56)
capabilities	capabilities	AgentCardCapabilitiesDetail { isStreaming } bool (agent_card_capabilities_detail.py:30-32)
version	version	str
provider	provider	AgentProvider { organization, url } (agent_provider.py:35-38)
documentationUrl	documentationUrl	str

Preview the generated card before publishing — the SDK exposes a preview action: PreviewAgentFlowAgentCardDetails { agentCardConfigDetails: AgentCardConfigDetail } → AgentCardPreviewResponse { agentCardJson } (a JSON-string A2A AgentCard) (preview_agent_flow_agent_card_details.py:30-34, agent_card_preview_response.py:30-32). Use this to inspect the exact A2A card the platform will publish before committing the flow update.

Author it (REST via oci raw-request, LA 20240831): set agentCardConfig on the create/update flow body at …/workspaces/<ws>/agentFlows[/<key>], then deploy per the Workflow below (a card describes a deployed flow). Persist the body to .aidp/payloads/ and confirm first.

CLI gap + verify-first (no-fabrication): the agentCardConfig field and all child field names/types above are from the SDK models cited inline — confirmed. There is no aidp CLI agent-card command (the v1.0.0 CLI README has no agent-card/a2a verb). The exact create/update wrapper (whether agentCardConfig rides inside CreateAgentFlowDetails/UpdateAgentFlowDetails as shown vs. a dedicated publish action) and the route that serves the published card to external agents are verify-first — confirm against a live GET …/workspaces/<ws>/agentFlows/<key> round-trip and record in rest-endpoint-map.md before a first write.

Node types

A flow is a node graph; the 13 node types (START / AGENT / SUPERVISOR_AGENT / NESTED_AGENT_FLOW / EXTERNAL_AGENT / HUMAN_IN_THE_LOOP / GUARDRAILS / SQL_TOOL / PROMPT_TOOL / RAG_TOOL / MCP_TOOL / HTTP_TOOL / CUSTOM_TOOL) and their config shapes are enumerated in references/agent-flow-nodes.md. A tool node can inline its toolConfig or reference a reusable standalone Tool by toolKey (aidp-tools).

Author guardrails (safety policies) — LA

Guardrails are lake-scoped (…/dataLakes/<ocid>/agentFlowGuardrails, live 200 2026-06-10) and attach to a flow as a GUARDRAILS node.

Defaults already there: every fresh DataLake auto-provisions 5 default guardrail policies, so a GET …/agentFlowGuardrails on a new instance returns 5 items (not 0). The defaults (verified 2026-06-12):

policyType	scope	action
CONTENT_MODERATION	USER_REQUEST	BLOCK
CONTENT_MODERATION	AGENT_RESPONSE	BLOCK
PROMPT_ATTACKS_PREVENTION	USER_REQUEST	BLOCK
PII_DETECTION	AGENT_RESPONSE	INFORM
PII_DETECTION	USER_REQUEST	INFORM
These are a security-first baseline — don't mistake them for leftover/test data, and account for them when
diffing or round-tripping guardrails.

A SafetyPolicy (verified enums):

{ "policyType": "PII_DETECTION", "policyName": "block_pii", "policyDescription": "…",
  "scope": "BOTH", "action": "BLOCK", "threshold": 0.8 }

• policyType ∈ CONTENT_MODERATION · PROMPT_ATTACKS_PREVENTION · PII_DETECTION · DENIED_TOPICS · WORD_FILTERS · CONTEXTUAL_GROUNDING · CUSTOM_POLICY
• scope ∈ USER_REQUEST · AGENT_RESPONSE · BOTH · action ∈ BLOCK · INFORM · MASK · threshold float

Per-policyType config (subtype models extend the base SafetyPolicy) — each subtype carries the base six fields above plus the extra child fields below. The 5 subtype models are ContentModerationPolicy, PromptAttacksPreventionPolicy, PiiDetectionPolicy, DeniedTopicsPolicy, WordFiltersPolicy (CONTEXTUAL_GROUNDING and CUSTOM_POLICY are base-only — no extra fields confirmed in the SDK):

policyType (subtype model)	Extra wire fields	Element shape (child model)
CONTENT_MODERATION (ContentModerationPolicy)	categories[]	ContentModerationCategoryConfig { category, isEnabled, threshold, action } — category ∈ HATE_SPEECH·HARASSMENT·VIOLENCE·SEXUAL·DEROGATORY·TOXIC; action ∈ BLOCK·INFORM·MASK
PROMPT_ATTACKS_PREVENTION (PromptAttacksPreventionPolicy)	(none — base fields only)	—
PII_DETECTION (PiiDetectionPolicy)	piiCategories[], customPiiRules[]	PiiCategory { category, isEnabled, action, threshold } — category ∈ PERSON·ADDRESS·TELEPHONE_NUMBER·EMAIL; action ∈ BLOCK·INFORM·MASK. CustomPiiRule { name, pattern, prefix, suffix, isCaseSensitive, maxDistance, priority }
DENIED_TOPICS (DeniedTopicsPolicy)	topics[]	DeniedTopic { name, definition, examples[] }
WORD_FILTERS (WordFiltersPolicy)	words[], regexPatterns[]	both list[str]

Example PII policy with a custom rule (base fields + child fields):

{ "policyType": "PII_DETECTION", "policyName": "mask_pii", "scope": "BOTH", "action": "MASK", "threshold": 0.8,
  "piiCategories": [ { "category": "EMAIL", "isEnabled": true, "action": "MASK", "threshold": 0.7 } ],
  "customPiiRules": [ { "name": "emp_id", "pattern": "EMP-\\d{6}", "isCaseSensitive": false, "priority": 1 } ] }

Field names/enums above are from the SDK subtype + child models (content_moderation_policy.py:64-71, content_moderation_category_config.py:83-88, prompt_attacks_prevention_policy.py:59-66, pii_detection_policy.py:69-78, pii_category.py:75-80, custom_pii_rule.py:60-68, denied_topics_policy.py:64-72, denied_topic.py:40-44, word_filters_policy.py:69-78) — confirmed. The discriminator/wrapper used to POST these to …/agentFlowGuardrails (and whether subtypes nest under a policies[] array) should be confirmed by round-tripping a live GET …/agentFlowGuardrails before a first write, and recorded in rest-endpoint-map.md.

High-code agents pass the same policies via OCIAIConf(guardrails_config=…) (aidp-agent-highcode).

Workflow

1. Discover with GET …/workspaces/<ws>/agentFlows; verify the route with this read before any write (handle the LA 404 — check the workspace segment first). For a specific flow, GET …/workspaces/<ws>/agentFlows/<key>.
2. Author: create/update the flow definition; validate before deploy.
3. Deploy: create a deployment, attach AI compute; deploy is async (202 + operation key) — poll to terminal via aidp-observability / the async-ops endpoint per oci-raw-request.md.
4. Run/monitor: create a session, run it, read traces / chat history.
5. Confirm before deploy/delete (deployment consumes compute).

Guardrails

• Deploy/delete are heavy/outward — confirm first. Don't print any embedded secrets in a flow definition.
• No-fabrication: don't present an agentFlows endpoint as confirmed until a live 2xx (or documented 4xx) is recorded in rest-endpoint-map.md.
• For mutating ops (create / update / delete / deploy / run a flow or session), persist the request body to .aidp/payloads/ and confirm first — see references/payloads.md.

References

• references/aidp-cli-map.md — official aidp CLI v1.0.0 has no agent-flow group
• references/oci-raw-request.md · references/rest-endpoint-map.md · references/no-mcp-rest-map.md
• references/payloads.md — persist + confirm request bodies for mutating ops