oracle-agent-spec

name	oracle-agent-spec
description	Design framework-agnostic AI agents with Oracle's Open Agent Specification for portable, interoperable agents defined in JSON/YAML. Use when authoring an Open Agent Spec definition or making an agent portable across frameworks.
version	1.0.0

Oracle Agent Spec Expert Skill

Purpose

Master Oracle's Open Agent Specification (Agent Spec) to design framework-agnostic, declarative AI agents that can be authored once and deployed across multiple frameworks and runtimes.

What is Agent Spec?

Open Agent Specification

Framework-agnostic declarative language for defining agentic systems, building blocks for standalone agents and structured workflows, plus composition patterns for multi-agent systems.

Key Innovation: Decouple design from execution - write agents once, run anywhere.

Release: Technical report published October 2025 (arXiv:2510.04173)

Core Philosophy

The Problem: Fragmented agent development - each framework requires different implementation.

The Solution: Unified representation - Agent Spec defines structure and behavior in JSON/YAML that any compatible runtime can execute.

Benefit: Author agents once → Deploy across frameworks → Reduce redundant development.

Architecture

Component Model

Agent Spec defines conceptual building blocks (components) that make up agent-based systems.

Key Property: All components are trivially serializable to JSON/YAML.

Core Components

1. LLMNode

Purpose: Text generation via LLM

Definition:

type: LLMNode
name: "text_generator"
model: "claude-sonnet-4-6"
system_prompt: "You are a helpful assistant"
temperature: 0.7
max_tokens: 2000

2. APINode

Purpose: External API calls

Definition:

type: APINode
name: "weather_api"
endpoint: "https://api.weather.com/v1/current"
method: "GET"
parameters:
  location: "{input.location}"
headers:
  Authorization: "Bearer {env.API_KEY}"

3. AgentNode

Purpose: Multi-round conversational agent

Definition:

type: AgentNode
name: "support_agent"
model: "gpt-4"
system_prompt: "You are a customer support specialist"
tools:
  - type: function
    name: "lookup_order"
  - type: function
    name: "process_refund"

4. WorkflowNode

Purpose: Orchestrate sequence of nodes

Definition:

type: WorkflowNode
name: "data_pipeline"
steps:
  - node: extract_node
  - node: transform_node
  - node: load_node
error_handling: retry

Agent Specification Format

Basic Agent

{
  "version": "1.0",
  "agent": {
    "name": "CustomerSupportAgent",
    "description": "Handles customer inquiries and support requests",
    "components": {
      "classifier": {
        "type": "LLMNode",
        "model": "claude-haiku-4-5",
        "system_prompt": "Classify customer inquiry type",
        "output": "inquiry_type"
      },
      "technical_support": {
        "type": "AgentNode",
        "model": "claude-sonnet-4-6",
        "tools": ["diagnose_issue", "escalate_ticket"]
      },
      "billing_support": {
        "type": "AgentNode",
        "model": "gpt-4",
        "tools": ["lookup_invoice", "process_refund"]
      },
      "router": {
        "type": "ConditionalNode",
        "conditions": [
          {
            "if": "inquiry_type == 'technical'",
            "then": "technical_support"
          },
          {
            "if": "inquiry_type == 'billing'",
            "then": "billing_support"
          }
        ]
      }
    },
    "entry_point": "classifier"
  }
}

Multi-Agent System

version: "1.0"
system:
  name: "ResearchSystem"
  description: "Multi-agent research and analysis system"

  agents:
    researcher:
      type: AgentNode
      model: claude-sonnet-4-6
      tools:
        - web_search
        - fetch_document
      system_prompt: "Research topics thoroughly"

    analyzer:
      type: AgentNode
      model: gpt-4o
      tools:
        - analyze_data
        - generate_insights
      system_prompt: "Analyze research findings"

    synthesizer:
      type: AgentNode
      model: claude-sonnet-4-6
      system_prompt: "Synthesize findings into coherent report"

  workflow:
    - step: researcher
      output: research_data
    - step: analyzer
      input: research_data
      output: analysis
    - step: synthesizer
      input: [research_data, analysis]
      output: final_report

  output: final_report

Node Library

Orchestration Nodes

SequentialNode:

type: SequentialNode
nodes:
  - step1_node
  - step2_node
  - step3_node

ParallelNode:

type: ParallelNode
nodes:
  - agent_a
  - agent_b
  - agent_c
aggregator: synthesis_node

ConditionalNode:

type: ConditionalNode
condition: "{output.confidence} > 0.8"
if_true: high_confidence_path
if_false: manual_review_path

LoopNode:

type: LoopNode
condition: "{not output.success}"
max_iterations: 3
body: retry_agent

Integration Nodes

MCPNode:

type: MCPNode
server: "github-server"
resource: "issues"
operation: "list"
filters:
  assignee: "me"

DatabaseNode:

type: DatabaseNode
connection: "postgresql://..."
query: "SELECT * FROM customers WHERE id = {input.customer_id}"

Design Patterns

Pattern 1: Triage and Route

name: TriageSystem
components:
  classifier:
    type: LLMNode
    model: claude-haiku-4-5
    prompt: "Classify: {input}"

  router:
    type: ConditionalNode
    conditions:
      - if: "category == 'urgent'"
        then: urgent_agent
      - if: "category == 'standard'"
        then: standard_agent
      - default: fallback_agent

Pattern 2: Research-Analyze-Report

name: ResearchPipeline
workflow:
  - name: gather
    type: AgentNode
    tools: [web_search, fetch_docs]

  - name: analyze
    type: LLMNode
    prompt: "Analyze: {gather.output}"

  - name: report
    type: LLMNode
    prompt: "Generate report from: {analyze.output}"

Pattern 3: Parallel Processing with Synthesis

name: MultiPerspective
components:
  parallel_agents:
    type: ParallelNode
    nodes:
      - technical_expert
      - business_expert
      - user_perspective

  synthesizer:
    type: AgentNode
    system_prompt: "Synthesize perspectives into unified recommendation"
    input: "{parallel_agents.outputs}"

Framework Portability

Supported Runtimes

Agent Spec can be executed by any compatible runtime:

• Oracle ADK - Native support via agent_spec package
• LangGraph - Via Agent Spec → LangGraph compiler
• AutoGen - Via Agent Spec → AutoGen adapter
• Custom Runtimes - Implement Agent Spec interpreter

Compilation Example

# Load Agent Spec definition
from agent_spec import load_spec

spec = load_spec("my_agent.yaml")

# Compile to target framework
langgraph_agent = spec.compile(target="langgraph")
autogen_agent = spec.compile(target="autogen")
oracle_adk_agent = spec.compile(target="oracle_adk")

# All three agents have identical behavior

Best Practices

DO:

✅ Use descriptive names for all components ✅ Document purpose in description fields ✅ Define explicit input/output schemas ✅ Specify error handling strategies ✅ Version your agent specifications ✅ Test across multiple runtimes for true portability

DON'T:

❌ Embed runtime-specific logic in specs ❌ Hardcode credentials or secrets ❌ Use framework-specific syntax ❌ Skip input validation definitions ❌ Ignore version compatibility

Integration with Other Specs

MCP (Model Context Protocol)

Relationship: MCP standardizes tool/resource provisioning; Agent Spec standardizes agent configuration.

Together:

agent:
  name: DataAgent
  tools:
    - type: MCPTool
      server: "postgres-mcp"
      resource: "customers"
    - type: MCPTool
      server: "github-mcp"
      resource: "issues"

A2A (Agent-to-Agent Communication)

Relationship: A2A standardizes inter-agent communication; Agent Spec defines agent structure.

Together:

multi_agent_system:
  agents:
    - name: agent1
      a2a_endpoint: "https://agent1.example.com"
    - name: agent2
      a2a_endpoint: "https://agent2.example.com"
  communication: a2a_protocol

Ecosystem Benefits

For Developers

• Write Once, Run Anywhere - Single specification, multiple runtimes
• Reusable Components - Share agent definitions across projects
• Version Control - Track agent evolution in Git
• Collaboration - Common language for team communication

For Frameworks

• Standardized Input - Consistent agent definitions
• Faster Adoption - Lower barrier to entry
• Interoperability - Agents can migrate between frameworks

For Enterprises

• Vendor Independence - Not locked into single framework
• Reproducible Deployments - Consistent behavior across environments
• Compliance - Audit trail through declarative definitions

Tools & Resources

PyAgentSpec (Python Package)

pip install pyagentspec

from pyagentspec import AgentSpec, LLMNode, AgentNode

spec = AgentSpec(
    name="MyAgent",
    components=[
        LLMNode(name="classifier", model="claude-haiku-4-5"),
        AgentNode(name="executor", model="gpt-4")
    ]
)

spec.save("my_agent.yaml")
spec.compile(target="oracle_adk")

Validation

from pyagentspec import validate_spec

is_valid, errors = validate_spec("agent.yaml")
if not is_valid:
    print(f"Validation errors: {errors}")

Decision Framework

Use Agent Spec when:

• Need framework portability (deploy across multiple platforms)
• Want declarative, version-controlled agent definitions
• Building reusable agent components
• Require reproducible deployments
• Team collaboration on agent design

Combine with:

• Oracle ADK (for OCI deployment)
• LangGraph (for complex state machines)
• Claude SDK (for Anthropic models)
• MCP (for data source standardization)

Resources

Official:

• GitHub: https://github.com/oracle/agent-spec
• Documentation: https://oracle.github.io/agent-spec/
• Technical Paper: https://arxiv.org/pdf/2510.04173
• PyAgentSpec: https://pypi.org/project/pyagentspec/

Citation:

Oracle Corporation. (2025). Open Agent Specification (Agent Spec) Technical Report.

Final Principles

1. Framework-Agnostic - Design once, deploy anywhere
2. Declarative - Describe what, not how
3. Composable - Build complex systems from simple components
4. Versioned - Track evolution over time
5. Portable - Migrate between frameworks without rewrite
6. Interoperable - Works with MCP, A2A, and other standards

---

This skill enables you to design portable, reusable AI agents using Oracle's open specification standard for 2025 and beyond.