Open Agent Specification (Agent Spec)

Open Agent Specification (Agent Spec) is a portable, platform-agnostic configuration language that allows Agents and Agentic Systems to be described with high fidelity.

It defines the conceptual building blocks—called components—that make up agents in typical agent-based systems. This includes the properties that configure each component and the semantics that govern their behavior. Agent Spec is based on two main standalone components:

• Agents (e.g., ReAct agents), which are conversational agents or agent modules;

• Flows (e.g., business processes), which can invoke agents and perform workflow-like processes.

Runtimes implement Agent Spec components to enable execution within agentic frameworks or libraries. Agent Spec is designed to be supported by SDKs in various programming languages (such as Python), allowing agents to be serialized/deserialized to common formats like JSON or YAML, or instantiated from object representations—with guarantees of conformance to the Agent Spec specification. More information, including the motivation and complete specification, is available in the dedicated section of Agent Spec documentation.

PyAgentSpec

To facilitate the process of building framework-agnostic agents programmatically, Agent Spec SDKs can be implemented in various programming languages. These SDKs are expected to provide two core capabilities:

• Building Agent Spec component abstractions by implementing the relevant interfaces, in full compliance with the Agent Spec specification;

• Importing and exporting these abstraction from and to their serialized representations (e.g., JSON).

As part of the Agent Spec project, we provide a Python SDK called PyAgentSpec. It enables users to build Agent Spec-compliant agents in Python. Using PyAgentSpec, you can define assistants by composing components that mirror the interfaces and behavior specified by Agent Spec, and export them to different formats.

Quick Start

To install PyAgentSpec:

Use the following command to install pyagentspec (compatible with Python 3.10+):

pip install "pyagentspec==25.4.1"

For a complete list of supported Python versions and platforms, see the installation guide.

Once PyAgentSpec is installed, you can try it out with the following example:

from pyagentspec.agent import Agent
from pyagentspec.llms import VllmConfig
from pyagentspec.property import Property

llm_config = VllmConfig(
    name="Vllm model",
    url="vllm_url",
    model_id="model_id",
)

expertise_property = Property(json_schema={"title": "domain_of_expertise", "type": "string"})
system_prompt = """
You are an expert in {{domain_of_expertise}}.
Please help the users with their requests.
"""
agent = Agent(
    name="Adaptive expert agent",
    system_prompt=system_prompt,
    llm_config=llm_config,
    inputs=[expertise_property],
)

Next Steps

• Familiarize yourself with the basics – How-to Guides

  • Begin with How to Build a Simple Agent.

  • Then explore How to Build a Simple Flow.

• Explore the API documentation

  Review the API documentation to learn about the available classes, methods, and functions in the library.

Security Considerations

LLM-based assistants and flows require careful security assessment before deployment. See the Security Considerations page for guidelines and best practices.

Need Help?

Reach out to the Agent Spec team to ask questions, request features, or share suggestions.

Browse the Frequently Asked Questions for find answers to common questions.

Agent Spec is developed jointly between Oracle Cloud Infrastructure and Oracle Labs teams.