Oracle Agentic AI Foundations cheat sheet

Agent = LLM reasoning core + planning loop + tool/memory layer + runtime harness; the model alone is not the agent.

ReAct pattern interleaves Thought → Action (tool call) → Observation steps until a stop condition or max-iteration budget is hit.

Planning variants: fixed workflow (deterministic DAG) vs. dynamic planning (model decomposes goal at runtime); choose fixed when steps are known and auditable.

Multi-agent topologies: supervisor/orchestrator-worker, sequential pipeline, debate/critic, and peer handoff; each adds latency and coordination failure modes.

Memory tiers: short-term context window, scratchpad/state object persisted by the runtime, and long-term store (vector or relational) retrieved on demand.

Human-in-the-loop checkpoints are architectural components, not afterthoughts: define approval gates for irreversible or high-value actions.

Idempotency and compensating actions are required because agent retries can duplicate side effects on external systems.

Determinism boundary: temperature, tool schemas, and prompt version pinning determine reproducibility; log all three per run.

OCI Generative AI service exposes hosted models via API; agents call it as the reasoning backend rather than hosting weights themselves.

OCI Generative AI Agents (RAG service) couples a knowledge base, a data source connection, and a vector store into a managed retrieval endpoint.

Vector store options on OCI include Autonomous Database 23ai AI Vector Search and OCI Search with OpenSearch; the agent references the store, not raw files.

Oracle Fusion/NetSuite agent offerings embed agents in enterprise workflows; distinguish platform-level build services from packaged business agents.

OCI IAM governs both human and workload identities; agent service principals should be distinct from end-user identities.

Model choice is per-task, not per-agent: route cheap classification steps to small models and complex planning to larger ones.

Regional availability and model catalog differ per OCI region; verify model and service availability before designing cross-region agents.

Prefer managed connectors and private endpoints over public internet egress when the agent must reach Oracle databases or object storage.

Tool schema quality dominates tool-use reliability: precise names, typed parameters, enums for constrained values, and explicit units.

Write tool descriptions as selection instructions - state when to use and when NOT to use the tool, since the model routes on description text.

Return structured errors to the model (code, message, retryable flag) so it can self-correct instead of hallucinating success.

Prefer narrow, single-purpose tools over a monolithic do-everything tool; fewer parameters reduce invalid-argument rates.

Set per-tool timeouts, retry budgets with backoff, and circuit breakers; the agent loop must handle partial failure gracefully.

Tool outputs are untrusted input: treat retrieved text and API responses as data, never as instructions (prompt-injection defense).

Expose Oracle Database PL/SQL or REST endpoints as tools via API gateways; keep credentials in a vault, never in the prompt.

Cap the agent with max steps, max tokens, and a cost ceiling; unbounded loops are the most common production failure.

RAG pipeline stages: ingest → parse/chunk → embed → index → retrieve → rerank → ground the prompt with citations.

Chunking tradeoff: small chunks improve precision but fragment context; overlap and structure-aware splits (headings, tables) usually beat fixed-size.

Hybrid retrieval (dense vector + keyword/BM25) with reranking generally outperforms pure vector search on enterprise text.

Embedding model must match between indexing and query time; changing models requires re-embedding the whole corpus.

Metadata filters (tenant, date, classification) enforce both relevance and access control at retrieval time.

Grounding requires citation of source chunks; if retrieval returns nothing above threshold, the agent should say so rather than answer from parametric memory.

Freshness: incremental re-index on source change; stale indexes cause confidently wrong answers that are hard to detect downstream.

Evaluate retrieval separately from generation (recall@k, context precision) to localize failures before tuning prompts.

Least-privilege tool credentials: scope each tool's identity to the minimum actions, and prefer read-only unless write is required.

Prompt injection is the top agent-specific risk; mitigations are instruction/data separation, output validation, and allow-listed tool calls.

Confused-deputy risk: an agent acting for a user must propagate the user's authorization context, not use a superuser service account.

Guardrails layer: input filtering, PII redaction, toxicity checks, and output schema validation before any action executes.

Governance artifacts: model card, prompt/tool version registry, decision logs, and approval records for high-impact actions.

Regulatory alignment commonly cited: NIST AI RMF (govern/map/measure/manage) and ISO/IEC 42001 for AI management systems; EU AI Act risk tiers shape documentation duties.

Data residency and tenancy isolation must be enforced in the vector store and tool layer, not only in the UI.

Red-team the agent with adversarial documents and tool-output spoofing before launch; log and review every tool invocation.

Trace every run end to end: prompt version, model, tool calls with arguments, latency per step, token counts, and final outcome.

Key metrics: task success rate, tool error rate, steps per task, p95 latency, cost per successful task, and escalation rate.

Golden datasets with regression tests gate prompt, model, or tool changes; treat prompts as versioned code in CI.

Canary or shadow deployment for agent changes; roll back on success-rate or cost regression thresholds.

Observability signals come from three planes: application logs, LLM traces (spans per reasoning step), and infrastructure metrics.

Cost control levers: prompt caching, smaller models for routing, retrieval top-k limits, and hard budget caps per session.

Drift detection covers model updates, source-data changes, and user-behavior shifts; re-evaluate on a fixed cadence, not only on incidents.

Incident runbook must include a kill switch that disables tool execution while leaving the agent in read-only or answer-only mode.