Learning Rest Openapi Agent Workflow

REST/OpenAPI Agent Workflow

Level

Intermediate to expert.

Audience

Full-stack developers, AI-agent engineers, platform teams, and instructors teaching tool-calling workflows.

Learning objectives

By the end, you can:

1. start the CaeReflex REST server in a bounded workspace;
2. inspect health and OpenAPI endpoints;
3. import a case through the API;
4. retrieve agent context and inspection flags; and
5. design safe tool instructions for Custom GPT, Claude-style, or internal agents.

Files used

• Architecture: REST API
• Reference: OpenAPI
• openapi/openapi.yaml
• examples/agent_workflow/

Walkthrough

Start the server from the repository root:

caereflex serve --host 127.0.0.1 --port 8765 --workspace .

In another terminal:

curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/openapi.yaml
curl -X POST "http://127.0.0.1:8765/cases/import" \
  -H "Content-Type: application/json" \
  -d '{"path":"examples/openfoam_cavity_minimal","adapter":"auto","attach_crossref":false,"return_agent_context":true}'

Use the returned case_id:

curl "http://127.0.0.1:8765/cases/CASE_ID/agent-context"
curl "http://127.0.0.1:8765/cases/CASE_ID/inspection-flags"

What to observe

• The OpenAPI schema describes the tool surface for action-capable agents.
• Case paths should be workspace-relative.
• CrossRef should be requested explicitly, not silently.
• Agent answers must preserve inspection warnings and safe-use policy.

Expected output and interpretation

A representative health response is intentionally small:

{"status": "success", "service": "caereflex", "version": "..."}

A representative import response for examples/openfoam_cavity_minimal should include the stored case identifier and optional agent context:

{
  "status": "success",
  "case_id": "case_6c5707a83ec1",
  "summary": "OpenFOAM case inspected. 8 files were considered.",
  "warnings": [],
  "provenance_summary": ["openfoam_inspection_started"],
  "next_recommended_actions": ["get_agent_context", "export_case_report"],
  "data": {
    "agent_context": {
      "case_type": "openfoam",
      "source_files": [{"relative_path": "system/controlDict", "hash_status": "complete"}],
      "do_not_claim": ["Do not claim simulation convergence unless explicit evidence is present."]
    }
  }
}

A representative inspection-flags response is:

{"inspection_flags": []}

Interpret the output as follows:

• Extracted evidence: source_files, detected_formats, field records, and hashes in data.agent_context come from the workspace-relative example path.
• Inferred context: summary, next_recommended_actions, and case classification help sequence agent behavior; they are not engineering conclusions.
• Warnings: top-level warnings and /inspection-flags must be fetched and echoed before summarization. An empty list is only an absence of emitted flags for that run.
• Provenance: provenance_summary identifies adapter events that produced the stored case.
• Unsafe claims to avoid: agents must not claim validation, convergence, mesh adequacy, certification, design safety, unrestricted filesystem access, or CrossRef attachment unless the corresponding endpoint was explicitly called.

Full-stack validation checklist

Use this sequence as a smoke test for a local UI, agent connector, or OpenAPI action configuration. The examples are self-contained: they validate request shape, response handling, and UX behavior without requiring CrossRef, solver execution, or any live external service.

1. Successful health check

curl -sS "http://127.0.0.1:8765/health"

Expected response: HTTP 200 with status: "success", service: "caereflex", and a version string. The client should treat this as API readiness only, not proof that any case has been inspected.

2. OpenAPI schema retrieval

curl -sS "http://127.0.0.1:8765/openapi.yaml" | sed -n '1,40p'

Expected response: HTTP 200 with YAML containing the CaeReflex API title, version, and paths such as /health, /cases/import, /cases/{case_id}/agent-context, and /cases/{case_id}/inspection-flags. A UI or agent setup screen can use this to verify that the configured server exposes the expected tool surface before enabling import actions.

3. Valid case import

curl -sS -X POST "http://127.0.0.1:8765/cases/import" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "examples/openfoam_cavity_minimal",
    "adapter": "auto",
    "attach_crossref": false,
    "return_agent_context": true
  }'

Expected response: HTTP 200 with an inspection status, a generated case_id, a short summary, warnings, inspection_flags, provenance_summary, and next_recommended_actions. When return_agent_context is true, the response also includes data.agent_context with safe-use policy and source-derived evidence. Store the returned case_id for follow-up calls rather than inventing one.

4. Invalid workspace-relative path

curl -sS -X POST "http://127.0.0.1:8765/cases/import" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "examples/does-not-exist",
    "adapter": "auto",
    "attach_crossref": false,
    "return_agent_context": false
  }'

Expected response: HTTP 400 or a failed/unsupported inspection response, depending on adapter detection and server configuration. The important client behavior is to show the path problem as an import failure, keep the path workspace-relative in any retry prompt, and avoid falling back to absolute host paths.

5. Missing or unknown case_id

curl -sS "http://127.0.0.1:8765/cases/CASE_ID_THAT_WAS_NOT_RETURNED/agent-context"
curl -sS "http://127.0.0.1:8765/cases/CASE_ID_THAT_WAS_NOT_RETURNED/inspection-flags"

Expected response: an error response for the unknown case identifier. The client should tell the user that the case is not in the current workspace case store, then offer to import a workspace-relative path. It should not fabricate agent context, suppress the error, or reuse a stale case_id from another workspace.

6. External binding and API-key safety expectations

For localhost development, no API key is required:

caereflex serve --host 127.0.0.1 --port 8765 --workspace .

For external exposure, require an API key at server startup and send it with every request:

caereflex serve --host 0.0.0.0 --port 8765 --workspace . --api-key "$CAEREFLEX_API_KEY"

curl -sS "http://SERVER_HOST:8765/health" \
  -H "x-api-key: $CAEREFLEX_API_KEY"

Expected behavior: serving outside localhost without an API key is rejected by the CLI, and external-mode API calls require the x-api-key header. Tool descriptions for agents should also say that case paths are bounded by the configured workspace and that the API is an inspection interface, not unrestricted filesystem access.

7. Client-side UX guidance for inspection warnings

After a successful import, retrieve warnings before generating any summary:

curl -sS "http://127.0.0.1:8765/cases/CASE_ID/inspection-flags"
curl -sS "http://127.0.0.1:8765/cases/CASE_ID/agent-context"

Expected UX behavior:

• Show inspection_flags, top-level import warnings, and agent_context.inspection_warnings in a visible review panel before the summary body.
• If warnings are empty, show neutral copy such as "No inspection warnings were emitted for this run" rather than "the case is valid."
• Require users or agent policies to acknowledge warnings before presenting engineering interpretation.
• Keep safety copy near the summary: CaeReflex reports structured evidence and limitations; it does not certify validation, convergence, mesh adequacy, design safety, or solver correctness.

UX presentation guidance

For a REST/OpenAPI client, design the user journey around response interpretation and safety gates, not just HTTP status. HTTP 200, status: "success", or a reachable OpenAPI schema confirms API workflow health only; it does not clear inspection warnings or engineering risk.

• Extracted facts: show fields from data.agent_context, /agent-context, and stored case records in an evidence view with source paths, hashes, detected formats, and trace links. Keep raw JSON available, but summarize it into human-readable evidence rows.
• Inferred facts: present summary, next_recommended_actions, case classification, and agent-generated text in a distinct inferred/assistant section. Make the UI language clear that these are workflow interpretations, not validation results.
• Inspection warnings: fetch and merge top-level import warnings, inspection_flags, /inspection-flags, and agent_context.inspection_warnings before producing or displaying a case summary. Render them as prominent alert banners or review cards that remain visible even when the API call returned success; never hide them behind successful HTTP/API status indicators.
• Provenance: show the case_id, request path, workspace-relative path, provenance_summary, and links to follow-up endpoints so users can trace which API calls produced each displayed statement. If data is stale or the case_id came from another workspace, mark provenance as uncertain and require re-import.
• Safe-use policy: place safe-use rules directly in the agent/tool UI: the API supports bounded inspection, not unrestricted filesystem access, solver execution, validation, certification, convergence proof, or design-safety approval. If CrossRef was not explicitly requested, do not imply external literature was attached.
• Human follow-up checks: include a post-import checklist that prompts qualified users to review warnings, raw source files, OpenFOAM-specific engineering checks, solver logs, validation evidence, authentication/workspace exposure, and any absolute-path or stale-case-id issues before accepting an AI-generated summary. Empty warning arrays should be displayed as "No inspection warnings were emitted for this run," not as an all-clear.

Beginner exercise

Identify the health endpoint, OpenAPI endpoint, import endpoint, and agent-context endpoint.

Practitioner exercise

Draft safe agent instructions that require health check, case import, agent context retrieval, and inspection flag review before summarization.

Expert extension

Review API exposure risks:

1. What changes when binding outside localhost?
2. Why is an API key required for external exposure?
3. How should workspace boundaries shape agent tool descriptions?
4. What should an agent do if a user provides an absolute path?

Assessment checklist

• The learner understands the REST workflow sequence.
• The learner can write a safe agent prompt or tool policy.
• The learner explains workspace and authentication risks.

Answer key

Use these examples to check that learners design safe REST/OpenAPI workflows rather than over-permissive agent tools.

Beginner exercise answer key

Sample acceptable answer

• Health endpoint: GET /health, called with curl http://127.0.0.1:8765/health.
• OpenAPI endpoint: GET /openapi.yaml, called with curl http://127.0.0.1:8765/openapi.yaml.
• Import endpoint: POST /cases/import, called with a JSON body containing a workspace-relative path, adapter, attach_crossref, and return_agent_context.
• Agent-context endpoint: GET /cases/{case_id}/agent-context, called after replacing {case_id} with the returned case identifier.
• Inspection-flags endpoint: GET /cases/{case_id}/inspection-flags, used before summarization even when the import response includes warnings.

Unsafe or incorrect answer

• "Skip health and flags, call any URL exposed by OpenAPI, use absolute paths such as /etc/passwd, and summarize the case as validated if the import succeeds."

Why the acceptable answer passes

• It preserves the documented sequence and uses the case_id returned by import.
• It treats inspection flags as a required safety check before agent summarization.
• It keeps paths workspace-relative for safe tool descriptions.

Why the unsafe answer fails

• It bypasses readiness and warning checks.
• It encourages unsafe filesystem access and unsupported validation claims.

References

• Command output to cite: curl http://127.0.0.1:8765/health, curl http://127.0.0.1:8765/openapi.yaml, the POST /cases/import response, curl .../agent-context, and curl .../inspection-flags.
• Adapter/API behavior: caereflex/server/app.py implements /health, /openapi.yaml, /cases/import, /cases/{case_id}/agent-context, and /cases/{case_id}/inspection-flags.
• Safety rule: agent answers must preserve inspection warnings and the safe-use/do-not-claim lists returned in agent context.

Practitioner exercise answer key

Sample acceptable answer

Before answering engineering questions, call GET /health and stop if the service is unavailable. Import only user-approved, workspace-relative case paths with POST /cases/import; set attach_crossref to false unless the user explicitly requests literature metadata. After import, store the returned case_id, call GET /cases/{case_id}/agent-context, and call GET /cases/{case_id}/inspection-flags. In the answer, cite file-derived evidence from source_files, result_fields, and other extracted records, echo all warnings or flags, and state that empty flags do not prove correctness. Never claim validation, convergence, mesh adequacy, certification, design safety, unrestricted filesystem access, or CrossRef attachment unless the corresponding endpoint output explicitly supports that limited statement.

Unsafe or incorrect answer

• "The agent may import any path the user types, attach CrossRef automatically, skip flag retrieval, and present the API result as a certified engineering review."

Why the acceptable answer passes

• It defines an auditable, least-privilege workflow.
• It separates endpoint outputs from engineering conclusions and requires warning preservation.
• It avoids silent CrossRef attachment.

Why the unsafe answer fails

• It is over-permissive with filesystem paths and external metadata.
• It skips explicit warning retrieval and misrepresents inspection as certification.

References

• Command output to cite: health response, import response with case_id, agent-context response, and inspection-flags response.
• API behavior: caereflex/server/app.py returns import warnings, full inspection_flags, provenance_summary, and optional data.agent_context; the agent-context endpoint returns safe_use_policy, inspection_warnings, do_not_claim, and source_references from caereflex/exporters.py.
• Safety rule: wiki/docs/user-guide/safe-use-policy.md states that CaeReflex output is structured evidence, not engineering validation.

Expert extension answer key

Sample acceptable answer

1. Binding outside localhost changes the threat model: the API can be reached by other machines, so unauthenticated access could expose inspection, export, and case-store operations.
2. An API key is required for external exposure because caereflex serve rejects non-localhost binding without one, and the server checks x-api-key for external mode.
3. Workspace boundaries should be reflected in tool descriptions: tools should accept workspace-relative paths, should not advertise arbitrary filesystem access, and should tell agents to reject or ask the user to relocate paths that are outside the configured workspace.
4. If a user provides an absolute path, an agent should not pass it blindly. Prefer asking for or constructing a workspace-relative path; for external deployments, paths outside the workspace are rejected by path-safety checks.

Unsafe or incorrect answer

• "Bind to 0.0.0.0 without a key for convenience, describe the tool as able to read any path on the host, and pass absolute paths directly because the API will validate the engineering content."

Why the acceptable answer passes

• It recognizes that network exposure, authentication, and workspace scoping are part of safe agent operation.
• It ties path handling to the server's safety behavior instead of inventing broad capabilities.

Why the unsafe answer fails

• It creates an avoidable remote-access risk.
• It misstates the tool's filesystem and engineering-validation capabilities.

References

• Command output to cite: caereflex serve --host 127.0.0.1 --port 8765 --workspace ., curl .../health, and the OpenAPI output from curl .../openapi.yaml.
• API behavior: caereflex/cli/main.py requires an API key when serving outside localhost; caereflex/server/app.py enforces x-api-key in external mode and resolves request paths against the workspace; caereflex/core/validation.py provides workspace path checks.
• Safety rule: agent tool descriptions must not claim unrestricted filesystem access or engineering validation beyond endpoint evidence.