DOCSEARCHbyAlgolia
Submit Docs

Oracle Open Agent Specification

repository·main·Indexed 18 days ago

https://github.com/oracle/agent-spec

A portable, platform-agnostic configuration language for describing Agents and Flows. It allows developers to define agentic systems that can be serialized to JSON/YAML and executed across different frameworks via runtime adapters such as LangGraph, AutoGen, and CrewAI. The project provides a Python library (pyagentspec) and a TypeScript SDK (agentspec) for defining LLM configurations, tools, and multi-agent patterns.

Tokens
128.7K
Snippets
339
Records
558
Agent score
62%

What's inside Agent Spec

  1. Overview of agentspec TypeScript SDK examples

    main

    The agentspec TypeScript SDK provides several patterns for building agentic systems. Key example files include:

    • Basic Agent: Creating an agent with LLM configuration, system prompts, and template variables (01-basic-agent.ts).
    • Tools: Implementing various tool types including ServerTool, ClientTool, RemoteTool, and BuiltinTool (02-tools.ts).
    • Multi-Agent Systems: Implementing patterns like Swarm, ManagerWorkers, and SpecializedAgent (03-multi-agent.ts).
    • Workflows: Using FlowBuilder to create linear, branching, and data-flow workflows (04-flows.ts).
    • MCP Tools: Using Model Context Protocol (MCP) tools with Stdio, SSE, and HTTP transports (05-mcp-tools.ts).
    • Serialization: Handling JSON/YAML serialization, camelCase conversion, and disaggregated components (06-serialization.ts).
    • Agent-to-Agent (A2A): Implementing the A2A protocol and working with remote agents (07-a2a-agent.ts).
    • Datastores: Using in-memory, Oracle DB, and PostgreSQL datastores (08-datastores.ts).

  2. What is Agent Spec?

    main

    Open Agent Specification (Agent Spec) is a portable, platform-agnostic configuration language used to define agentic systems. It serves as an intermediate representation that abstracts away the implementation details of specific agentic frameworks.

    Core Components

    • Agents: LLM-powered assistants that can converse with users, use external tools, and cooperate with other agents to achieve tasks autonomously.
    • Flows: Structured assistants composed of connected nodes that form coherent action sequences. Each node performs a specific function, allowing for controllable execution of business processes.

    Key Benefits

    • Portability: Author agents once and run them with any compatible runtime (e.g., WayFlow) or via adapters for frameworks like AutoGen, CrewAI, and LangGraph.
    • Reliability: Promotes uniform behavior across different frameworks through explicit specifications.
    • Modularity: Component-based design allows agents and flows to be developed independently and reused in complex systems.
    • Extensibility: Supports custom components to meet specific requirements.
    • Evaluation-Ready: Standardized representation facilitates testing and side-by-side framework comparisons.

  3. Supported Agent Spec integrations

    main

    Agent Spec provides integrations for several AI Agent frameworks to facilitate execution and management. The following frameworks are currently supported:

    • LangGraph: For long-running, stateful agents with durable execution and human-in-the-loop capabilities.
    • WayFlow: The reference framework for Agent Spec, providing modular components for workflow-based and agent-style applications.
    • CrewAI: For collaborative AI agents and workflows with guardrails, memory, and observability.
    • AutoGen: (Deprecated) For multi-agent conversational systems. Note that AutoGen is marked as a deprecated framework within the ecosystem.

  4. Use the Agent Spec adapter for AutoGen

    main

    The AutoGen adapter allows you to bridge Agent Spec and Microsoft AutoGen. You can use it for two primary workflows:

    1. Run Agent Spec configurations with AutoGen: Import agents defined via Agent Spec and execute them within the AutoGen framework.
    2. Convert AutoGen agents to Agent Spec: Export existing AutoGen agents into the Agent Spec format for interoperability.

  5. Use the CrewAI adapter for Agent Spec

    main

    The CrewAI adapter allows you to bridge Agent Spec and the CrewAI framework in two primary ways:

    1. Run Agent Spec configurations with CrewAI: Execute Agent Spec definitions using the CrewAI engine.
    2. Convert CrewAI agents to Agent Spec: Export existing CrewAI agent configurations into the Agent Spec format.

    Refer to the specific guides for spec_to_crewai and crewai_to_spec for implementation details.

  6. Use the OpenAI Agents adapter

    main

    The OpenAI Agents adapter allows you to bridge Agent Spec and the OpenAI Agents SDK. You can use it for two primary workflows:

    1. Run Agent Spec configurations with OpenAI Agents: Import agents defined in Agent Spec and execute them using the OpenAI Agents runtime.
    2. Convert OpenAI agents to Agent Spec: Export agents built with the OpenAI Agents SDK into the Agent Spec format for interoperability.

  7. Use the FlowBuilder to assemble agent flows

    main

    The FlowBuilder is a utility for assembling agentic flows without manually wiring every edge. It provides high-level methods for common patterns like linear sequences and conditional branching, as well as low-level methods for manual topology control.

    Key Capabilities:

    • Linear Sequences: Use build_linear_flow to quickly connect a sequence of nodes.
    • Manual Wiring: Use add_node and add_edge to add individual nodes and define control edges.
    • Data Flow: Use add_data_edge to specify how data moves between nodes.
    • Sequences: Use add_sequence to add multiple nodes in order with automatic control edges.
    • Flow Control: Use set_entry_point and set_finish_points to define the start and end of the flow.
    • Branching: Use add_conditional to branch execution based on node outputs.

  8. Agent Spec integrations with AGNTCY and AG-UI

    main

    Open Agent Specification provides integrations with external AI Agent initiatives to support agent discovery, deployment, and standardized UI interactions.

    AGNTCY Integration

    AGNTCY supports Agent Spec metadata within OASF Agent records. This allows developers to:

    • Specify how to consume a deployed agent.
    • Instantiate new agents with minimal effort.
    • Enable agent discovery and deployment workflows.

    AG-UI Integration

    AG-UI integrates with Open Agent Spec to connect AG-UI-compatible frontends with Agent Spec configurations. This enables users to:

    • Load any Agent Spec configuration file.
    • Choose a supported runtime to execute the configuration.
    • Enable agentic frontends.

  10. What is Agent Spec and why use it?

    main

    Oracle Agent Specification (Agent Spec) is a standardized, framework-agnostic configuration language used to define AI agents and their workflows with high fidelity.

    Unlike framework-specific configurations (e.g., LangGraph or AutoGen) which bind agent logic to a specific runtime, Agent Spec acts as a unifying abstraction layer. This allows you to design an agent once and deploy it across multiple different agentic frameworks without reimplementation.

    Core use cases:

    • Cross-framework Portability: Decouple agent design from runtime execution.
    • Modular Workflows: Use a component-based structure to compose complex orchestrator-worker flows.
    • Standardized Evaluation: Use built-in metadata and behavior constraints to benchmark agent performance consistently across different frameworks.
    • Serialization: Use available SDKs (starting with Python) to serialize and deserialize agents into Agent Spec-compatible configurations for easier deployment and debugging.

  11. What is the Swarm pattern and when to use it?

    main

    The Swarm pattern is an agentic pattern where coordinated behavior emerges from many simple actors rather than a central controller. Each agent is assigned a specific responsibility and can delegate tasks to other specialized agents.

    When to use Swarm vs. Hierarchical

    • Hierarchical Pattern: Requires intermediate agents to call sub-agents and then relay the answers back up the chain. This increases the number of LLM calls and latency.
    • Swarm Pattern: Reduces LLM calls by allowing agents to communicate more directly. If using handoff, an agent can transfer the entire conversation to a specialized agent, which then communicates directly with the user, effectively replacing the previous agent in the conversation loop.

  12. What is Agent Spec and PyAgentSpec?

    main

    Agent Spec is a portable, platform-agnostic configuration language used to describe Agents and Agentic Systems with high fidelity. It defines the building blocks, known as components, including their configuration properties and behavioral semantics.

    Core Components

    • Agents: Conversational agents or agent modules (e.g., ReAct agents).
    • Flows: Workflow-like processes that can invoke agents (e.g., business processes).

    PyAgentSpec SDK

    PyAgentSpec is the Python SDK for Agent Spec. It allows you to:

    1. Build abstractions: Programmatically define Agent Spec-compliant agents by implementing relevant interfaces.
    2. Serialize/Deserialize: Import and export these agent abstractions to and from common formats like JSON or YAML, ensuring conformance to the specification.