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

• Framework-Agnostic - Design once, deploy anywhere

• Declarative - Describe what, not how

• Composable - Build complex systems from simple components

• Versioned - Track evolution over time

• Portable - Migrate between frameworks without rewrite

• 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.