Open Agent Specification

Agent Spec is a portable, platform-agnostic configuration language that allows Agents and Agentic Systems to be described with sufficient fidelity. It defines the conceptual objects and called components that compose Agents in typical Agent systems, including the properties that determine the components' configuration, and their respective semantics. Agent Spec is based on two main runnable standalone components:

• Agents (e.g., ReAct), that are conversational agents or agent components;
• Flows (e.g., business process) that are structured, workflow-based processes.

Runtimes implement the Agent Spec components for execution with Agentic frameworks or libraries. Agent Spec would be supported by SDKs in various languages (e.g. Python) to be able to serialize/deserialize Agents to JSON/YAML, or create them from object representations with the assurance of conformance to the specification.

For more information, including the motivation and specification, see the dedicated section in the Agent Spec documentation.

Get started

To get started, set up your Python environment (Python 3.10 or newer required), and then install the PyAgentSpec package.

venv

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install pyagentspec

Hello world example

Initialize a Large Language Model (LLM) of your choice:

from pyagentspec.llms import OciGenAiConfig
from pyagentspec.llms.ociclientconfig import OciClientConfigWithApiKey

OCIGENAI_ENDPOINT = "https://inference.generativeai..oci.oraclecloud.com"
COMPARTMENT_ID = "ocid1.compartment.oc1..<compartment_id>"
llm = OciGenAiConfig(
    name="OCI model",
    model_id="model_id",
    compartment_id=COMPARTMENT_ID,
    client_config=OciClientConfigWithApiKey(
        name="client_config",
        service_endpoint=OCIGENAI_ENDPOINT,
        auth_file_location="~/.oci/config",
        auth_profile="DEFAULT",
    ),
)

from pyagentspec.llms import OpenAiConfig

llm = OpenAiConfig(
    name="OpenAI model",
    model_id="model_id",
)

from pyagentspec.llms import OllamaConfig

llm = OllamaConfig(
    name="Ollama model",
    url="ollama_url",
    model_id="model_id",
)

See the list of supported LLMs in the PyAgentSpec documentation.

Then, create an agent using a PyAgentSpec Agent:

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

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],
)

For more information on how to build flexible Agents, structured Flows and multi-agent patterns, read the PyAgentSpec Guides

Why Agent Spec

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 to and from their serialized JSON/YAML representations.

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 JSON/YAML format.

Executing Agent Spec configurations

In order to execute Agent Spec configurations, an Agent Spec Runtime Adapter is needed in order to transform the Agent Spec representation of the agent to an equivalent representation according to the specifics of an agentic framework.

For example, WayFlow is an Agent Spec reference runtime developed by Oracle, which offers a complete set of APIs that enable users to load and execute Agent Spec configurations.

We also provide adapters for some of the most common agentic frameworks as part of pyagentspec. These adapters require to install extra dependencies, you can find more information in our installation guide. You can find some examples of how to use these adapters in the adapters_examples folder:

• LangGraph
• AutoGen
• CrewAI

Positioning in the Agentic Ecosystem

Get Support

• Open a GitHub issue for bug reports, questions, or requests for enhancements.
• Report a security vulnerability according to the Reporting Vulnerabilities guide.

Contributing

This project welcomes contributions from the community. Before submitting a pull request, please review the contributor guide.

Security

Please refer to the security guide for information on responsibly disclosing security vulnerabilities.

License

Copyright (c) 2025 Oracle and/or its affiliates.

This software is under the Apache License 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or Universal Permissive License (UPL) 1.0 (LICENSE-UPL or https://oss.oracle.com/licenses/upl), at your option.