oracle-agent-spec

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-5"
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",
        "system_prompt": "Classify customer inquiry type",
        "output": "inquiry_type"
      },
      "technical_support": {
        "type": "AgentNode",
        "model": "claude-sonnet-4-5",
        "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-5
      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-5
      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
    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"),
        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.