aidp-agent-highcode

aidp-agent-highcode — code-first AIDP agents (aidputils + LangGraph)

The GA high-code path: write a Python agent class using aidputils (pre-installed in AI Compute; not pip-installable locally; legacy name aidp_flowutils) on top of LangGraph 1.x. You author the .py in the workspace (aidp-workspace-files / aidp-notebooks) and run it on AI Compute. Grounded in AIDP_High_Code_Complete_Reference.md §4–12, §22.

When to use

• "Write/code an AIDP agent", LangGraph, create_react_agent, StateGraph, custom tool logic, multi-agent supervisor in code, or anything aidputils.
• NOT the drag-and-drop / REST node graph → aidp-agent-flows. NOT building the RAG corpus → aidp-knowledge-bases.

Imports (current aidputils; legacy aidp_flowutils still works)

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.agent_helper import init_oci_llm, pre_invoke_setup
from aidputils.agents.toolkit.configs import AIDPToolConf, OCIAIConf, ModelArgs
from langgraph.prebuilt import create_react_agent
from langgraph.graph import StateGraph, MessagesState, START, END
from langchain_core.messages import HumanMessage

The agent class contract (REQUIRED)

Every agent MUST implement __init__ / setup() / async invoke():

class MyAgent:
    def __init__(self) -> None:
        self.agent = None                      # or self.graph = None

    def setup(self) -> None:                   # sync, called once: build LLM + tools + agent
        llm = init_oci_llm(OCIAIConf(
            model_provider="generic", model_id="xai.grok-4",
            compartment_id="ocid1.compartment.oc1..…",
            endpoint="https://inference.generativeai.us-ashburn-1.oci.oraclecloud.com",
            model_args=ModelArgs(temperature=0.7, max_tokens=4096),
            guardrails_config={"policies": []}, auth_type="SECURITY_TOKEN", auth_profile="DEFAULT"))
        tool = create_langgraph_tool(AIDPToolConf(
            name="summarizer", description="Summarize text",
            tool_class="PromptTool",            # or "SQLTool" / "RAGTool"
            conf={...}, params=[{"name":"text","type":"string","description":"…"}]).model_dump())
        self.agent = create_react_agent(llm, [tool])    # single-agent; StateGraph for multi-agent

    async def invoke(self, user_query: str, **kwargs):
        config = pre_invoke_setup(**kwargs)             # MUST be first line of every invoke
        message = {"messages": [dict(HumanMessage(content=user_query))]}
        return await self.agent.ainvoke(input=message, config=config)

Rules (HC ref §5): setup() is synchronous, runs once; invoke() is async, per query; pre_invoke_setup(**kwargs) must be the first call in invoke(); input is always {"messages": [dict(HumanMessage(content=…))]}.

Building blocks

Piece	API	Notes
LLM	OCIAIConf(model_provider, model_id, compartment_id, endpoint, model_args, guardrails_config, auth_type, auth_profile) → init_oci_llm()	Models: xai.grok-4 (default), xai.grok-4-fast-reasoning, cohere.command-r-08-2024
Tools	AIDPToolConf(name, description, tool_class, conf, params) → create_langgraph_tool(.model_dump())	tool_class ∈ PromptTool / SQLTool / RAGTool (RAGTool needs a KB → aidp-knowledge-bases)
Single agent	create_react_agent(llm, tools)	LangGraph prebuilt
Multi-agent	StateGraph(MessagesState) + supervisor (HC ref §10)	nodes + START/END edges
Observability	AIDPObservability (HC ref §12)	tracing

Deploy

Place the agent .py in the workspace and designate the entry file + dependency files (HC ref §22), then run/deploy on AI Compute (Preview — see aidp-cluster-ops). Deployment + sessions can also be managed via the agent-flow deploy action (aidp-agent-flows).

Live-verified 2026-06-10 on de-agent — correction: the agent-flow deploy action is gated and has a required-field contract. (1) The ENTIRE agentFlows write surface (create included) is gated on the DataLake's aiFeatureStatus=Ready — on a fresh datalake, create returns 409 IncorrectState AiFeatureStatus=None ("try again later") until the Enable-AI-Feature workflow completes; this is a platform-provisioning state, not a body defect. (2) POST …/actions/deployAgentFlow requires a deploymentType enum (the agentFlowKey alone → 400 "deploymentType must not be null"); the valid value is NOT AI_COMPUTE/SERVERLESS/DEDICATED/ON_DEMAND/QUICK_START/STANDARD/DEFAULT (all 400 "Invalid DeploymentType") — pull the real enum from the SDK DeploymentType/Deployment models before deploying.

Guardrails

• aidputils only exists inside AI Compute — examples are authored/edited via aidp-workspace-files, not run locally. Don't claim a local pip install aidputils.
• Don't fabricate model_ids/endpoints — list live via aidp-models-catalog. Attach safety policies via guardrails_config (enums in aidp-agent-flows guardrails section).

References

• aidp-agent-flows (low-code/REST path + guardrail enums) · aidp-knowledge-bases (RAGTool corpus) · aidp-tools (standalone tools) · aidp-workspace-files (author the .py) · aidp-models-catalog