Oracle ADK Expert Skill

When to Use This Skill

Activate this skill when:

• Building AI agents on Oracle Cloud Infrastructure

• Creating multi-agent orchestration systems

• Integrating agents with Oracle Fusion, Autonomous Database, or OCI services

• Need code-first (not no-code) agent development

• Deploying enterprise-grade agents with OCI security

Use /adk-agent command to scaffold a new agent project.

Don't use when:

• Not on Oracle Cloud (use Claude SDK or OpenAI AgentKit instead)

• Need visual/no-code builder (use Oracle AI Agent Studio instead)

• Want framework-agnostic specs (use oracle-agent-spec skill instead)

Purpose

Master Oracle's Agent Development Kit (ADK) for building enterprise-grade agentic applications on OCI Generative AI Agents Service with code-first approach and advanced orchestration patterns.

Platform Overview

OCI Agent Development Kit (Released May 22, 2025)

Client-side library that simplifies building agentic applications on top of OCI Generative AI Agents Service.

Key Value: Code-first approach for embedding agents in applications (web apps, Slackbots, enterprise systems).

Requirements: Python 3.10 or later

Core Capabilities

1. Multi-Turn Conversations

Build agents that maintain context across multiple interactions.

Pattern:

from oci_adk import Agent

agent = Agent( name="customer_support", model="cohere.command-r-plus", system_prompt="You are a helpful customer support agent" )

Multi-turn conversation

conversation = agent.create_conversation() response1 = conversation.send("I need help with my order") response2 = conversation.send("It's order #12345")

Agent remembers context from previous messages

2. Multi-Agent Orchestration

Routing Pattern:

Route requests to specialized agents

def orchestrator(user_query): if requires_technical_support(user_query): return technical_agent.handle(user_query) elif requires_billing(user_query): return billing_agent.handle(user_query) else: return general_agent.handle(user_query)

Agent-as-a-Tool Pattern:

One agent uses another agent as a tool

main_agent = Agent( name="supervisor", tools=[research_agent, analysis_agent, report_agent] )

Main agent orchestrates specialist agents

result = main_agent.execute("Research and analyze Q4 performance")

3. Deterministic Workflows

Build predictable, orchestrated workflows with explicit control flow.

from oci_adk import Workflow, Step

workflow = Workflow([ Step("validate_input", validation_agent), Step("process_request", processing_agent), Step("generate_response", response_agent) ])

result = workflow.execute(user_input)

4. Function Tools

Add custom capabilities to agents through function tools.

from oci_adk import FunctionTool

@FunctionTool( name="get_customer_data", description="Retrieve customer information from CRM", parameters={ "customer_id": {"type": "string", "required": True} } ) def get_customer_data(customer_id: str): return crm_api.get_customer(customer_id)

agent = Agent( name="customer_agent", tools=[get_customer_data] )

Architectural Patterns

Pattern 1: Hierarchical Orchestration

Supervisor Agent ├─→ Research Agent (gathers information) ├─→ Analysis Agent (processes data) └─→ Report Agent (generates output)

Use Case: Complex tasks requiring specialized subtask agents

Implementation:

supervisor = Agent( name="supervisor", system_prompt="Coordinate specialist agents to complete complex tasks", tools=[research_tool, analysis_tool, report_tool] )

Pattern 2: Sequential Pipeline

Input → Agent 1 → Agent 2 → Agent 3 → Output

Use Case: Linear workflows with dependencies

Implementation:

pipeline = AgentPipeline([ ("extract", data_extraction_agent), ("transform", data_transformation_agent), ("load", data_loading_agent) ])

result = pipeline.execute(raw_data)

Pattern 3: Parallel Processing

Coordinator ├──→ Agent A ──┐ ├──→ Agent B ──┤→ Aggregator Agent └──→ Agent C ──┘

Use Case: Independent tasks that can run concurrently

Implementation:

import asyncio

async def parallel_processing(task): results = await asyncio.gather( agent_a.execute_async(task), agent_b.execute_async(task), agent_c.execute_async(task) ) return aggregator_agent.synthesize(results)

Oracle-Specific Best Practices

1. Leverage OCI Services

Integrate with OCI services

from oci import object_storage, database

agent = Agent( name="data_agent", tools=[ object_storage_tool, autonomous_db_tool, analytics_cloud_tool ] )

2. Enterprise Security

Use OCI IAM for authentication

from oci.config import from_file

config = from_file("~/.oci/config")

agent = Agent( name="secure_agent", oci_config=config, compartment_id="ocid1.compartment..." )

3. Multi-Region Deployment

Deploy agents across OCI regions

regions = ["us-ashburn-1", "eu-frankfurt-1", "ap-tokyo-1"]

for region in regions: deploy_agent( agent=my_agent, region=region, config=regional_config[region] )

Production Deployment

Application Integration

Embed in FastAPI application

from fastapi import FastAPI from oci_adk import Agent

app = FastAPI() support_agent = Agent.load("customer_support_v2")

@app.post("/support/chat") async def chat_endpoint(message: str, session_id: str): conversation = support_agent.get_conversation(session_id) response = await conversation.send_async(message) return {"reply": response.text}

Slackbot Integration

from slack_sdk import WebClient from oci_adk import Agent

slack_client = WebClient(token=slack_token) agent = Agent.load("slack_assistant")

@slack_app.event("message") def handle_message(event): user_message = event["text"] response = agent.execute(user_message) slack_client.chat_postMessage( channel=event["channel"], text=response.text )

Monitoring & Observability

Logging

import logging

logging.basicConfig(level=logging.INFO) logger = logging.getLogger("oci_agent")

agent = Agent( name="monitored_agent", on_tool_call=lambda tool: logger.info(f"Calling tool: {tool}"), on_error=lambda error: logger.error(f"Agent error: {error}") )

Metrics Collection

from oci.monitoring import MonitoringClient

def track_agent_metrics(agent_id, metrics): monitoring_client.post_metric_data( post_metric_data_details={ "namespace": "agent_performance", "dimensions": {"agent_id": agent_id}, "datapoints": metrics } )

Cost Optimization

Model Selection

Use appropriate models for tasks

simple_agent = Agent( model="cohere.command-light", # Cheaper for simple tasks )

complex_agent = Agent( model="cohere.command-r-plus", # More capable for complex reasoning )

Caching Strategies

from functools import lru_cache

@lru_cache(maxsize=1000) def cached_agent_call(prompt: str): return agent.execute(prompt)

Testing

Unit Testing Agents

def test_customer_agent(): agent = Agent.load("customer_support") response = agent.execute("What's your return policy?") assert "30 days" in response.text.lower()

Integration Testing

def test_agent_workflow(): workflow = Workflow([ Step("classify", classification_agent), Step("process", processing_agent) ])

result = workflow.execute(test_input)
assert result.status == "success"

Oracle Enterprise Integration

Fusion Applications

Integrate with Oracle Fusion

fusion_agent = Agent( name="fusion_assistant", tools=[ fusion_hcm_tool, fusion_erp_tool, fusion_scm_tool ] )

Database Integration

Connect to Autonomous Database

from oci_adk.tools import SQLTool

db_tool = SQLTool( connection_string=autonomous_db_connection, allowed_tables=["customers", "orders", "products"] )

agent = Agent( name="data_agent", tools=[db_tool] )

Decision Framework

Use Oracle ADK when:

• Building on OCI infrastructure

• Integrating with Oracle Fusion/Cloud applications

• Need enterprise-grade security and compliance

• Want code-first agent development

• Deploying multi-region applications

Consider alternatives when:

• Not on Oracle Cloud (use Claude SDK or AgentKit)

• Need visual builder interface (use AgentKit)

• Want framework-agnostic approach (use Agent Spec)

Resources

Documentation:

• Official Docs: https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/adk/

• API Reference: https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/adk/api-reference/

• Tutorials: https://docs.public.content.oci.oraclecloud.com/en-us/iaas/Content/generative-ai-agents/add-tool-adk.htm

Support:

• OCI Documentation

• Oracle Support Portal

• Oracle Cloud Community

Final Principles

• Code-First - Leverage existing developer tooling and workflows

• Enterprise-Grade - Built for production Oracle workloads

• OCI-Native - Deep integration with Oracle Cloud services

• Multi-Agent - Design for orchestration from the start

• Deterministic - Explicit control flow for predictable behavior

Quality Checklist

Before deploying an ADK agent, verify:

Architecture:

• Agent pattern matches use case (single, multi-agent, workflow, pipeline)

• Clear separation between supervisor and specialist agents

• Tools are properly scoped (minimal permissions)

• Error handling defined for all tool calls

OCI Integration:

• OCI config properly loaded (~/.oci/config )

• Compartment ID specified

• IAM policies grant necessary permissions

• Secrets stored in OCI Vault (not hardcoded)

Production Readiness:

• Logging configured for debugging

• Metrics collection enabled

• Health check endpoint implemented

• Rate limiting considered

• Cost optimization (model selection, caching)

Testing:

• Unit tests for each tool function

• Integration tests for workflows

• End-to-end conversation tests

• Error scenario coverage

Security:

• Input validation on all user inputs

• SQL injection prevention (parameterized queries)

• Tool permissions restricted to necessary tables/actions

• Audit logging enabled

This skill enables you to build production-ready agentic applications on Oracle Cloud Infrastructure using ADK's code-first approach.