agent_platform_oci/docs/developer/en/INDEX_DEVELOPER_GUIDE.md

Developer Index — Agent Framework OCI

How to use this documentation

The documentation has three clear levels:

1. Main tutorial: README_en.md — creation, configuration, execution, and testing of an agent from start to finish.
2. Architecture: 01 — Architecture and Concepts — components, responsibilities, and where to implement each concern.
3. Specialized references: manuals 02 through 12 — in-depth implementation and troubleshooting by capability.

If you are starting a new agent, begin with README_en.md.

If something is not working, use Search by problem below.

Search by problem

Problem / question	What is usually involved	Where to look
The framework does not find the correct agent/intent	routing, intents, threshold, deterministic/LLM mode	Routing and Stickiness
The agent gets stuck on the same subject and does not change intent	route stickiness, intent shift, handoff	Routing and Stickiness
An answer that should fill a parameter is interpreted as a new intent	transactional precedence, parameter extraction	Transactional Workflows
The transaction keeps asking for the same parameter	transaction state, extractor, schema	Transactional Workflows and MCP/Tools
“yes/no” confirmation does not continue the flow	confirmation state, transaction state	Transactional Workflows
A completed transaction reappears	old checkpoint versus active transaction state	Transactional Workflows and LTM/Checkpoint
The system says it executed something, but there is no evidence	MCP result, COMPLETED state, transactional judges	Transactional Workflows and Guardrails/Judges
A tool does not appear or cannot be found	tools.yaml, MCP catalog, discovery	MCP/Tools
MCP Server does not appear in the catalog	registration, manifest/discovery, MCP Gateway	MCP/Tools and Gateways
Parameters sent to the tool are wrong	schema, mapping, BusinessContext, extractor	MCP/Tools
A transactional operation executes without confirmation	tool policy, require_confirmation	MCP/Tools
A name search requires an overly exact match	parameter extraction/mapping and agent logic	MCP/Tools
I receive 401 between gateway/backend/MCP	Basic Auth, credentials per hop	Gateways and Auth
I need to decide whether something belongs to the framework or the agent	core/agent boundary	Architecture and Concepts
An agent-specific guardrail is breaking another agent	extensibility, domain imports in the core	Guardrails and Judges
An incomplete phrase receives a generic “security rule” message	input-guardrail feedback, COER, blocked-turn state	Input Guardrail Feedback
route=blocked appears together with tools/results from another turn	blocked-turn state cleanup	Input Guardrail Feedback
A judge does not run in a transaction	sampling, always_run_for_transactional, transaction signals	Guardrails and Judges
Workflow completes and generates a protocol, but the final response becomes a safety message	expected_protocols, CMP, DLEX_OUT, output_guardrails ordering	Guardrails and Judges
Groundedness is evaluating without the correct context	RAG context, MCP evidence, judge inputs	RAG/Grounding
RAG does not find content	provider, ingestion, embeddings, configuration	RAG/Grounding
I do not know whether to use RAG, memory, or a tool	separation of responsibilities	Architecture and Concepts and RAG/Grounding
Memory disappears when changing sessions	LTM versus conversation memory	LTM and Checkpoint
Memory from one customer/agent appears in another	identity key, tenant/agent/customer isolation	LTM and Checkpoint
I need to retrieve reasoning_content	ainvoke_response()	LLM Rich Response
reasoning_content is None	provider/model does not expose the field	LLM Rich Response
There are unnecessary LLM calls	deterministic routing, concurrency, cache	Performance
There is a deadlock or wait across event loops	cross-loop sequence/runtime	Performance
Logs/traces do not correlate the same agent	labels, IDs, and observability mapping	Observability
Sequence is interfering with processing	asynchronous sequence implementation	Observability and Performance
An old example does not compile	historical documentation versus current API	README vs Code Validation
I need to create a new agent from scratch	complete flow	README_en.md
I need to know where to place a new feature	architecture and boundaries	Architecture and Concepts

Search by feature

01 — Architecture and Concepts

What it is: overview of components, contracts, and responsibility boundaries.

Use when: you need to understand the platform, decide where to implement something, or avoid coupling between core and agent.

02 — Routing, Route Stickiness, and Intent Shift

What it is: complete reference for agent/intent discovery, stickiness, handoff, and intent changes.

Use when: the message goes to the wrong agent, does not change intent, or loses continuity.

03 — Transactional Workflows and State

What it is: multi-turn transaction lifecycle, states, confirmation, pause/resume, and operational evidence.

Use when: there are loops, incorrect confirmations, incorrect resumes, or critical operations.

04 — MCP, Tools, Policies, and Parameter Extraction

What it is: reference for tools, MCP Servers, mappings, policies, and parameter extraction.

Use when: tool integration/execution is incorrect or needs to be created.

05 — Agent Gateway, MCP Gateway, and Authentication

What it is: gateway responsibilities, governance, and authentication between components.

Use when: there is an ingress, catalog, authorization, 401, or gateway deployment problem.

06 — Guardrails, Judges, and Transaction Evaluation

What it is: native/external validations, judges, grounding, and rules for transactional turns.

Use when: a validation blocks, does not run, or produces an incorrect evaluation.

07 — RAG, BusinessContext, and Grounding

What it is: RAG providers, retrieved context, BusinessContext, and grounding.

Use when: retrieved knowledge does not correctly reach the agent/judge.

08 — Long-Term Memory and Checkpoint

What it is: durable memory, conversation memory, identity, and state snapshots.

Use when: context disappears, leaks, or the workflow resumes from the wrong place.

09 — LLM Rich Response and reasoning_content

What it is: structured inference response beyond the str returned by ainvoke().

Use when: consumers need metadata, usage, or reasoning exposed by the provider.

10 — Performance, Cache, and Async Runtime

What it is: concurrency, cache, LLM, and event-loop optimizations.

Use when: there is avoidable latency, serial processing, or deadlock.

11 — Observability, Persistence, and Operational Readiness

What it is: correlation, events, labels, sequence, persistence, and diagnostics.

Use when: it is necessary to prove the executed path or diagnose production.

12 — Input Guardrail Feedback and Blocked-Turn Semantics

What it is: public handling of input blocks, blocked-turn state cleanup, and output-guardrail validation of generated feedback.

Use when: block messages are generic, COER should ask for clarification, or blocked-turn metadata contains stale routing/tool results.

Main tutorial

README_en.md remains the reference for the complete step-by-step flow:

architecture → configuration → agent creation → registration → state → routing → tools → MCP → identity → execution → tests → gateways → memory → RAG.

Maintenance

Do not create another tutorial in parallel with README_en.md.

When evolving a feature:

• update the README only if the normal development flow changed;
• update the specialized manual with behavior, configuration, examples, and troubleshooting;
• update SPECs if the contract changed;
• keep release notes as history, not as the only current documentation.