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

1. Code-First - Leverage existing developer tooling and workflows
2. Enterprise-Grade - Built for production Oracle workloads
3. OCI-Native - Deep integration with Oracle Cloud services
4. Multi-Agent - Design for orchestration from the start
5. 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.