AgentSpec

AgentSpec downloads AgentSpec docs AgentSpec Reference Sheet License

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.

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

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

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

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.

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.

Positioning

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

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

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

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.