### Setup Development Environment

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/installation.rst

Commands to clone the repository, create a virtual environment, and install the package from source for development purposes.

```bash
git clone git@github.com:oracle/agent-spec.git
python3.10 -m venv <venv_name>
source <venv_name>/bin/activate
cd agent-spec/pyagentspec
bash install-dev.sh
```

--------------------------------

### Complete Agent Code Example

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_agents.rst

Provides the complete Python code for building a ReAct Agent as demonstrated throughout the guide. This includes LLM configuration, agent instantiation with system prompts, and the addition of tools.

```python
from agent_spec import Agent, LlmConfig
from agent_spec.tools import SearchTools
from agent_spec.serialization import AgentSpecSerializer

# Define LLM
llm = LlmConfig(
    model="gpt-3.5-turbo",
    temperature=0.7,
    model_kwargs={"top_p": 0.9}
)

# Create Agent with custom prompt and tools
agent = Agent(
    name="Article Assistant",
    llm=llm,
    system_prompt="You are a helpful assistant that writes articles for {username}. Your goal is to assist the user with their writing needs.",
    tools=[SearchTools.search_serp]
)

# Serialize Agent Configuration
spec = AgentSpecSerializer.from_agent(agent)
spec.save("../agentspec_config_examples/howto_agents.json")

print("Agent configured and saved successfully!")
```

--------------------------------

### Install Extra Dependencies

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/installation.rst

Command to install the package along with specific optional runtime adapters or evaluation tools.

```bash
pip install "|package_name|[extra-dep-1,extra-dep-2]==|stable_release|"
```

--------------------------------

### Install Agent Spec via pip

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/installation.rst

Standard installation command for the stable release of the package. Optionally includes a constraints file to ensure version consistency.

```bash
pip install "|package_name|==|stable_release|"
```

```bash
pip install "|package_name|==|stable_release|"  -c constraints.txt
```

--------------------------------

### Example Agent Spec Configuration (YAML)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_orchestrator_agent.rst

An example of the assistant configuration represented in YAML format. This provides an alternative, human-readable representation of the agent specification.

```yaml
name: oracle_it_assistant
description: An IT assistant for Oracle systems.
version: "1.0"
flow:
  nodes:
    - id: llm_model
      type: LLMNode
      config:
        model_name: gpt-4
    - id: tool_node
      type: ToolNode
      config:
        tool_name: oracle_db_tool
  edges:
    - source: llm_model
      target: tool_node
```

--------------------------------

### Example Agent Spec Configuration (JSON)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_orchestrator_agent.rst

An example of the assistant configuration represented in JSON format. This is the output of the AgentSpecSerializer, showing the structure of a complete agent specification.

```json
{
  "name": "oracle_it_assistant",
  "description": "An IT assistant for Oracle systems.",
  "version": "1.0",
  "flow": {
    "nodes": [
      {
        "id": "llm_model",
        "type": "LLMNode",
        "config": {
          "model_name": "gpt-4"
        }
      },
      {
        "id": "tool_node",
        "type": "ToolNode",
        "config": {
          "tool_name": "oracle_db_tool"
        }
      }
    ],
    "edges": [
      {
        "source": "llm_model",
        "target": "tool_node"
      }
    ]
  }
}
```

--------------------------------

### Create a Simple MCP Server in Python

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_mcp.rst

This Python code defines and starts a basic MCP server that exposes two example tools: 'get_user_session' and 'get_payslips'. The server listens on http://localhost:8080/sse. It requires no external dependencies beyond standard Python libraries.

```python
from fastapi import FastAPI
from mcp.server import MCPServer

app = FastAPI()

@app.get("/sse")
async def sse():
    return await MCPServer(app=app).stream_response()

@app.get("/get_user_session")
def get_user_session():
    return {"user_id": "123", "session_id": "abc"}

@app.get("/get_payslips")
def get_payslips(user_id: str):
    return [{"month": "January", "amount": 1000}, {"month": "February", "amount": 1200}]

# .. start-##Create_a_MCP_Server
# .. end-##Create_a_MCP_Server
```

--------------------------------

### Oracle Datastore Configuration Example

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_datastores.rst

Example JSON configuration for an Oracle Datastore. It demonstrates how connection details are represented, with sensitive fields masked using component references.

```json
{
    "name": "oracle_datastore",
    "kind": "oracle_database",
    "connection_config": {
        "kind": "tls",
        "user": "$component_ref: oracle_tls_config_id.user",
        "password": "$component_ref: oracle_tls_config_id.password",
        "dsn": "$component_ref: oracle_tls_config_id.dsn"
    }
}

```

--------------------------------

### Setup Environment and Install PyAgentSpec for AutoGen

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/adapters/autogen/index.rst

Commands to create a virtual environment and install the required dependencies for the Agent Spec AutoGen adapter. Requires Python 3.10 to 3.12.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install "pyagentspec[autogen]"
```

--------------------------------

### Install PyAgentSpec SDK

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/docs_home.rst

Commands to install the PyAgentSpec library. Supports both stable releases via pip and development versions from source.

```bash
pip install "|package_name|==|stable_release|"
```

```bash
bash install-dev.sh
```

--------------------------------

### Agent Spec Configuration Example (JSON)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_agent_with_remote_tools.rst

This is an example of the exported Agent Spec configuration in JSON format, representing the defined agent, its tools, and LLM configuration.

```json
{
  "name": "my_assistant",
  "description": "An assistant that can search the web.",
  "instructions": "You are a helpful assistant. Use the available tools to answer the user's query: {query}",
  "tools": [
    {
      "name": "web_search",
      "description": "Searches the web for information.",
      "type": "RemoteTool",
      "url": "https://example.com/api/search",
      "method": "POST",
      "input_properties": {
        "input": {
          "type": "string",
          "description": "The user's input query."
        },
        "output": {
          "type": "string",
          "description": "The tool's output."
        }
      },
      "output_properties": {
        "input": {
          "type": "string",
          "description": "The user's input query."
        },
        "output": {
          "type": "string",
          "description": "The tool's output."
        }
      },
      "requires_confirmation": false
    }
  ],
  "llm_config": {
    "model": "cohere_command",
    "api_key": "<your_api_key>"
  }
}
```

--------------------------------

### Plugin Component Example Configuration (JSON5)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_25_4_1.rst

An example configuration file demonstrating how a plugin component might be defined in JSON5 format. This includes specifying component type, name, and version.

```json5
{
    "component_type": "ExampleComponent",
    "plugin_name": "example_plugin",
    "plugin_version": "1.0.0",
    "attributes": {
        "some_attribute": "some_value"
    }
}
```

--------------------------------

### Agent Spec Configuration Example (YAML)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_agent_with_remote_tools.rst

This is an example of the exported Agent Spec configuration in YAML format, representing the defined agent, its tools, and LLM configuration.

```yaml
name: my_assistant
description: An assistant that can search the web.
instructions: "You are a helpful assistant. Use the available tools to answer the user's query: {query}"
tools:
  - name: web_search
    description: Searches the web for information.
    type: RemoteTool
    url: https://example.com/api/search
    method: POST
    input_properties:
      input:
        type: string
        description: The user's input query.
      output:
        type: string
        description: The tool's output.
    output_properties:
      input:
        type: string
        description: The user's input query.
      output:
        type: string
        description: The tool's output.
    requires_confirmation: false
llm_config:
  model: cohere_command
  api_key: <your_api_key>
```

--------------------------------

### Plugin Component Example in JSON5

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_26_1_0.rst

An example configuration file in JSON5 format demonstrating how a plugin component should be defined within the Agent Spec ecosystem. This format allows for comments and is used for specifying component types, names, and versions.

```JSON5
{
  "component_type": "example_plugin_component",
  "plugin_name": "my_plugin",
  "plugin_version": "1.0.0",
  "description": "An example plugin component."
}
```

--------------------------------

### Vector Search Built-in Tool Documentation Example

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_26_1_0.rst

An example of documentation for a 'vector_retrieval_tool' which retrieves relevant documents based on cosine similarity. It details the tool's name, inputs, outputs, configuration parameters, executor name, and versioning.

```text
**Vector Search Built-in Tool**

Retrieves the most relevant documents from a table based on cosine similarity
between a query text and stored embeddings.

**Tool Name:** "vector_retrieval_tool"

**Inputs:**

- ``StringProperty(title="query")``: user query text.

**Outputs:**

- ``ListProperty(title="results", item_type=StringProperty())``:
    list of retrieved document contents.

**Configuration Parameters:**

- ``schema`` (str): schema containing the table.
- ``target_table`` (str): name of the table storing embeddings.
- ``target_column`` (str): column containing embedding vectors.
- ``top_k`` (int): number of nearest results to return.

**Executor Name:** "my_execution_engine>=25.4.1".

**Tool Version:**  Our vector_retrieval_tool is not versioned.
```

--------------------------------

### Configure OCI Generative AI LLM

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_llm_from_different_providers.rst

Demonstrates how to initialize OCI GenAI configuration with specific generation parameters and client authentication settings.

```python
default_generation_parameters = LlmGenerationConfig(max_tokens=256, temperature=0.8)
```

--------------------------------

### Configure OpenAI LLM integration

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_llm_from_different_providers.rst

Demonstrates how to initialize an OpenAI model configuration. Requires the OPENAI_API_KEY environment variable to be set for authentication.

```python
# Example usage for OpenAI configuration
from agent_spec import OpenAIConfig

llm_config = OpenAIConfig(
    model_id="gpt-4",
    api_key="your-api-key-here"
)
```

--------------------------------

### End-to-End Evaluation Example (Python)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/evaluation.rst

This snippet provides a complete example of setting up and running an end-to-end evaluation using Agent Spec Eval. It demonstrates the integration of various components like datasets, metrics, and evaluators.

```python
.. start-snippet

# Example code for end-to-end evaluation
# ... (actual code would be here)

.. end-snippet
```

--------------------------------

### Initialize OpenAI LLM Configuration

Source: https://github.com/oracle/agent-spec/blob/main/README.md

Initializes an OpenAI LLM configuration using PyAgentSpec. Requires only the model ID. This is a straightforward setup for integrating OpenAI models.

```python
from pyagentspec.llms import OpenAiConfig

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

--------------------------------

### Define data flow edge for MapNode in Python

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/misc/reference_sheet.rst

This Python example illustrates a DataFlowEdge connecting a list of 'x' values from a start node to the 'iterated_x' input of a MapNode. This enables the MapNode to process each element in the list.

```python
DataFlowEdge(
    name="list_of_x_edge",
    source_node=start_node,
    source_output="x_list",
    destination_node=square_numbers_map_node,
    destination_input="iterated_x",
)
```

--------------------------------

### Export Config to Agent Spec JSON Example

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_catchexception.rst

This Python code demonstrates how to serialize the Agent Spec flow configuration, including the exception handling setup, into a JSON format using AgentSpecSerializer. This JSON can then be used by Agent Spec runtimes.

```python
from agent_spec.nodes import BranchingNode, CatchExceptionNode, ToolNode
from agent_spec.serialization.agentspec_serializer import AgentSpecSerializer


def _flaky_tool(input: Dict[str, Any]) -> Dict[str, Any]:
    """A tool that may fail."""
    if "fail" in input and input["fail"]:
        raise ValueError("This tool is designed to fail.")
    return {"output": f"Processed input: {input.get('input', 'empty')}"}


flaky_tool = ToolNode(lambda x: _flaky_tool(x))


def _subflow_with_flaky_tool(input: Dict[str, Any]) -> Dict[str, Any]:
    """A subflow that uses the flaky tool."""
    return flaky_tool(input)


subflow_with_flaky_tool = ToolNode(lambda x: _subflow_with_flaky_tool(x))


# Define the branch to handle caught exceptions
caught_exception_branch = BranchingNode(
    {
        "continue": ToolNode(lambda x: {"output": "Continuing after exception"}),
        "handle_error": ToolNode(lambda x: {"output": "Handling the error"}),
    }
)

# Wrap the subflow with CatchExceptionNode
exception_handling_node = CatchExceptionNode(
    subflow=subflow_with_flaky_tool,
    caught_exception_branch=caught_exception_branch,
)

# Define the main flow using the exception handling node
main_flow = BranchingNode(
    {
        "start": exception_handling_node,
        "end": ToolNode(lambda x: {"output": "Flow finished"}),
    }
)


# Export the configuration to Agent Spec JSON
s = AgentSpecSerializer()
agent_spec_json = s.serialize(main_flow)

print(agent_spec_json)

```

--------------------------------

### Create a Basic Agent with PyAgentSpec

Source: https://context7.com/oracle/agent-spec/llms.txt

Demonstrates how to instantiate an Agent object with a dynamic system prompt using template variables and configure it with an LLM and input properties.

```python
from pyagentspec.agent import Agent
from pyagentspec.property import Property
from pyagentspec.llms import OpenAiConfig

# Configure the LLM
llm_config = OpenAiConfig(
    name="gpt-4o",
    model_id="gpt-4o"
)

# Define input properties for template substitution
expertise_property = Property(
    json_schema={"title": "domain_of_expertise", "type": "string"}
)

# Create an agent with a dynamic system prompt
system_prompt = """You are an expert in {{domain_of_expertise}}.
Please help the users with their requests."""

agent = Agent(
    name="Adaptive expert agent",
    description="An agent that adapts to different domains of expertise",
    system_prompt=system_prompt,
    llm_config=llm_config,
    inputs=[expertise_property],
    human_in_the_loop=True  # Allow the agent to request user input
)
```

--------------------------------

### Export and Load Agent Spec Configuration

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_plugin.rst

Demonstrates the process of exporting an assistant configuration to a file and subsequently loading it into the runtime environment using deserialization plugins.

```python
# Exporting configuration
config = assistant.export()
with open("config.json", "w") as f:
    f.write(config)

# Loading configuration
loaded_config = AgentSpecSerializer.load("config.json")
```

--------------------------------

### Install WayFlow Core

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_execute_agentspec_with_wayflow.rst

Installs the required wayflowcore package via pip to enable Agent Spec adapter functionality.

```bash
pip install "wayflowcore==|stable_release|"
```

--------------------------------

### Install Agent Spec WayFlow Adapter

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/adapters/wayflow/index.rst

Instructions for setting up a Python virtual environment and installing the necessary PyAgentSpec package with WayFlow support. Requires Python 3.10 or newer.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install pyagentspec[wayflow]
```

--------------------------------

### Agent Spec Configuration Formats

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_disaggregated_config.rst

Examples of main and component configurations represented in JSON and YAML formats. These files demonstrate how to reference external components within the main agent specification.

```json
{
  "agent": "weather_agent",
  "components": "./components.json"
}
```

```yaml
agent: weather_agent
components: ./components.yaml
```

--------------------------------

### Install PyAgentSpec with CrewAI extension

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/adapters/crewai/index.rst

Sets up a Python virtual environment and installs the necessary dependencies to use the Agent Spec adapter for CrewAI. Requires Python 3.10 through 3.13.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install "pyagentspec[crewai]"
```

--------------------------------

### Create Basic Agent

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_agents.rst

Creates a basic agent instance with a specified name and a system prompt. The system prompt instructs the agent on its primary function and behavior. This is the foundational step for agent creation.

```python
agent = Agent(
    name="Article Assistant",
    llm=llm,
    system_prompt="You are a helpful assistant that writes articles."
)
```

--------------------------------

### JSON5: Standalone Agent Specification Example

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_nightly.rst

An example of a standalone agent specification in JSON5 format. This configuration defines the structure and components of an agent, including tools and LLMs, for multi-turn conversations.

```JSON5
.. literalinclude:: ../agentspec_config_examples/standalone_agent.json5
        :language: JSON5
```

--------------------------------

### Python Flow Example using PyAgentSpec

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_nightly.rst

An example demonstrating how to define an Agent Spec Flow using the PyAgentSpec library in Python. This code snippet illustrates the creation of agents and their connections to form a workflow.

```python
.. start-code:
from pyagentspec import Agent, Flow, LLMConfig

# Define LLM configuration
llm_config = LLMConfig(
    name="Llama 3.1 8B instruct",
    url="url.of.my.llm.deployment:12345",
    model_id="meta-llama/Meta-Llama-3.1-8B-Instruct",
)

# Define an agent
agent = Agent(
    name="Adaptive expert agent",
    inputs=["domain_of_expertise"],
    llm_config=llm_config,
    system_prompt="You are an expert in {{domain_of_expertise}}. Please help the users with their requests.",
)

# Define a flow
flow = Flow(
    name="My first flow",
    description="A simple flow that uses an expert agent.",
    agents=[
        agent,
    ],
)

# Print the JSON representation of the flow
print(flow.model_dump_json(indent=2))
.. end-code
```

--------------------------------

### Agent JSON Serialization Example

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_26_1_0.rst

Shows the JSON representation of an Agent component. This example includes 'id', 'name', 'inputs', 'outputs', 'human_in_the_loop', 'llm_config', 'system_prompt', 'tools', and 'component_type' set to 'Agent'.

```json5
{
  "id": "expert_agent_id",
  "name": "Adaptive expert agent",
  "description": null,
  "metadata": {},
  "inputs": [
    {
      "title": "domain_of_expertise",
      "type": "string"
    }
  ],
  "outputs": [],
  "human_in_the_loop": true,
  "llm_config": {
    "id": "llama_model_id",
    "name": "Llama 3.1 8B instruct",
    "description": null,
    "metadata": {},
    "default_generation_parameters": {},
    "url": "url.of.my.llm.deployment:12345",
    "model_id": "meta-llama/Meta-Llama-3.1-8B-Instruct",
    "component_type": "VllmConfig"
  },
  "system_prompt": "You are an expert in {{domain_of_expertise}}. Please help the users with their requests.",
  "tools": [],
  "component_type": "Agent",
  "agentspec_version": "26.1.0"
}
```

--------------------------------

### Python Flow Definition Example

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_25_4_1.rst

An example demonstrating how to define an Agent Spec Flow using the PyAgentSpec library in Python. This code illustrates the creation of nodes, edges, and the overall flow structure.

```python
from typing import List, Optional

from pyagentspec.agent_spec import AgentSpec, Component, ComponentSerializationPlugin, ComponentDeserializationPlugin
from pyagentspec.flow import Flow, StartNode, LlmNode, EndNode, ControlFlowEdge


class AgentSpecSerializer:
  def __init__(self, plugins: Optional[List[ComponentSerializationPlugin]] = None) -> None:
    ...  # Placeholder for initialization logic

  def to_json(self, component: Component) -> str:
    # gets the JSON string representation for the component
    pass

class AgentSpecDeserializer:
  def __init__(self, plugins: Optional[List[ComponentDeserializationPlugin]] = None) -> None:
    ...  # Placeholder for initialization logic

  def from_json(self, json_content: str) -> Component:
    # creates a component, given its JSON string representation
    pass

# Create a Python object Agent Spec flow
node_1 = StartNode(id="NODE_1", name="node_1")
node_2 = LlmNode(id="NODE_2", name="node_2", prompt_template="Hi!")
end_node = EndNode(id="end_node", name="End node")

control_flow_edges = [
    ControlFlowEdge(id="1to2", name="1->2", from_node=node_1, to_node=node_2),
    ControlFlowEdge(id="2toend", name="2->end", from_node=node_2, to_node=end_node),
]

flow = Flow(
    id="FLOW_1",
    name="My Flow",
    start_node=node_1,
    nodes=[node_1, node_2, end_node],
    control_flow_connections=control_flow_edges,
    data_flow_connections=[],
)

# Serialize it to JSON
serializer = AgentSpecSerializer()
serialized_flow = serializer.to_json(flow)

print(serialized_flow)

```

--------------------------------

### PostgreSQL Datastore Configuration

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/api/datastores.rst

Configuration models and datastore classes for connecting to PostgreSQL databases.

```APIDOC
## PostgreSQL Database Integration

### Description
Classes for managing PostgreSQL database connections, including standard and TLS-encrypted configurations.

### Classes
- **PostgresDatabaseDatastore**: Main class for PostgreSQL database operations.
- **PostgresDatabaseConnectionConfig**: Standard connection configuration.
- **TlsPostgresDatabaseConnectionConfig**: Configuration for TLS-encrypted connections.
```

--------------------------------

### Create Assistant with Custom Component (Python)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_plugin.rst

Demonstrates how to create an assistant that utilizes the custom 'PluginRegexNode'. This code snippet shows the integration of the custom node into an Agent Spec Flow, including LLM configuration and the definition of the agent's structure. It highlights how to instantiate and configure the custom node within the assistant's definition.

```python
from agent_spec.assistant import Assistant
from agent_spec.flows.flow import Flow

# Assuming PluginRegexNode is defined and imported
# from .plugin_regex_node import PluginRegexNode

# LLM Configuration (example using vLLM)
llm_config = {
    "provider": "vllm",
    "model": "Llama3.3 70B",
    "base_url": "http://localhost:8000/v1"
}

# Create a Flow that uses the custom PluginRegexNode
flow = Flow(
    name="RegexExtractionFlow",
    description="A flow that extracts information using regex.",
    nodes=[
        PluginRegexNode(
            name="RegexExtractor",
            regex=r"Hello, (.*?)",
            input_key="input_text",
            output_key="extracted_name"
        )
    ]
)

# Create the Assistantassistant = Assistant(
    name="RegexAssistant",
    description="An assistant that uses a custom regex node.",
    llm_config=llm_config,
    flows=[
        flow
    ]
)

```

--------------------------------

### Example Structured Generation Output (JSON)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/language_spec_26_1_0.rst

This JSON snippet shows an example of a structured output generated by an LLM for a component defined with structured generation capabilities. It adheres to the 'outputs' schema defined in the component configuration.

```json
{"brand": "Pininfarina", "model": "Battista", "hp": 1400}
```

--------------------------------

### Standalone LLM-based Metric Example (Python)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/agentspec/evaluation.rst

This example illustrates how to use a standalone LLM-based metric within the Agent Spec Eval framework. It shows the configuration and execution of a single LLM metric.

```python
.. start-snippet

# Example code for a standalone LLM-based metric
# ... (actual code would be here)

.. end-snippet
```

--------------------------------

### Import necessary packages for MCP integration in Python

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_mcp.rst

This Python snippet imports essential libraries for setting up an LLM and integrating with MCP tools. It includes imports for Agent, LLM, and MCPToolBox, which are fundamental for building agents that can interact with MCP servers.

```python
from langgraph.graph import Agent, StateGraph
from langgraph.checkpoint.memory import MemorySaver
from langgraph.llms import OpenAI
from langgraph.tools.mcp import MCPToolBox

# .. start-##_Imports_for_this_guide
# .. end-##_Imports_for_this_guide
```

--------------------------------

### Create Agent with Custom Prompt

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_agents.rst

Creates an agent with a context-aware system prompt that includes placeholders for dynamic input. This allows the agent to incorporate user-specific information, such as a username, into its instructions, making it more personalized.

```python
agent = Agent(
    name="Article Assistant",
    llm=llm,
    system_prompt="You are a helpful assistant that writes articles for {username}. Your goal is to assist the user with their writing needs."
)
```

--------------------------------

### All LLM Models Configuration

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/api/llmmodels.rst

Details configurations for various LLM model providers including OpenAI, VLLM, Ollama, and OCI GenAI.

```APIDOC
## All LLM Models Configuration

### Description
This section outlines the configuration classes for different LLM model providers, enabling integration with various services.

### OpenAI Compatible Models

#### OpenAiCompatibleConfig

- **Description**: Configuration for OpenAI compatible models.
- **Members Excluded**: `model_post_init`, `model_config`

### VLLM Models

#### VllmConfig

- **Description**: Configuration for VLLM models.
- **Members Excluded**: `model_post_init`, `model_config`

### Ollama Models

#### OllamaConfig

- **Description**: Configuration for Ollama models.
- **Members Excluded**: `model_post_init`, `model_config`

### OpenAI Models

#### OpenAiConfig

- **Description**: Configuration for OpenAI models.
- **Members Excluded**: `model_post_init`, `model_config`

### OciGenAi Models

#### ServingMode

- **Description**: Represents the serving mode for OCI GenAI models.

#### ModelProvider

- **Description**: Represents the model provider for OCI GenAI.

#### OciGenAiConfig

- **Description**: Configuration for OCI GenAI models.
- **Members Excluded**: `model_post_init`, `model_config`

### OCI Client Configurations

#### OciClientConfig

- **Description**: Base client configuration for OCI services.
- **Members Excluded**: `model_post_init`, `model_config`

#### OciClientConfigWithApiKey

- **Description**: OCI client configuration using an API key.
- **Members Excluded**: `model_post_init`, `model_config`

#### OciClientConfigWithSecurityToken

- **Description**: OCI client configuration using a security token.
- **Members Excluded**: `model_post_init`, `model_config`

#### OciClientConfigWithInstancePrincipal

- **Description**: OCI client configuration using instance principal authentication.
- **Members Excluded**: `model_post_init`, `model_config`

#### OciClientConfigWithResourcePrincipal

- **Description**: OCI client configuration using resource principal authentication.
- **Members Excluded**: `model_post_init`, `model_config`
```

--------------------------------

### Agent Spec Parallel Execution Example (Python)

Source: https://github.com/oracle/agent-spec/blob/main/docs/pyagentspec/source/howtoguides/howto_parallelflownode.rst

A Python script demonstrating how to define and execute parallel tasks within Agent Spec. This example utilizes the Agent Spec library to orchestrate concurrent operations.

```python
from agentspec import AgentSpec

# Define the AgentSpec configuration for parallel execution
spec_config = {
    "nodes": [
        {
            "name": "parallel_node",
            "type": "parallel",
            "nodes": [
                {
                    "name": "task1",
                    "type": "task",
                    "script": "echo 'Running task 1'"
                },
                {
                    "name": "task2",
                    "type": "task",
                    "script": "echo 'Running task 2'"
                }
            ]
        }
    ]
}

# Initialize AgentSpec with the configuration
spec = AgentSpec(spec_config)

# Execute the defined flow
spec.run()

```