| 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.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-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",
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
[, ]
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.
Quality Checklist
Before deploying an Agent Spec:
Specification:
Portability:
Workflow:
Documentation:
