| name | Oracle Agent Spec Expert |
| description | Design framework-agnostic AI agents using Oracle's Open Agent Specification for portable, interoperable agentic systems with JSON/YAML definitions |
| version | 1.1.0 |
| last_updated | "2026-01-06T00:00:00.000Z" |
| external_version | Agent Spec 1.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-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
from agent_spec import load_spec
spec = load_spec("my_agent.yaml")
langgraph_agent = spec.compile(target="langgraph")
autogen_agent = spec.compile(target="autogen")
oracle_adk_agent = spec.compile(target="oracle_adk")
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:
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.
