Splunk Enterprise SDK for Python

https://github.com/splunk/splunk-sdk-python
Admin
The Splunk Enterprise SDK for Python is the primary way for developers to communicate with the...
Tokens:49,568
Snippets:434
Trust Score:9.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies with make install

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/AGENTS.md

Use `make install` to set up or update the virtual environment and sync dependencies. Run this after manually editing pyproject.toml to update uv.lock.

```sh
make install
```

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

### Install SDK with uv

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Initializes a new Python project and adds the splunk-sdk package using uv.

```python
uv init
uv add splunk-sdk
uv sync
```

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

### Install SDK with pip

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Creates a virtual environment and installs the splunk-sdk package using pip.

```sh
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install splunk-sdk
```

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

### Install Google extra

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Install the 'google' optional extra for GoogleModel support. Use pip or uv.

```sh
pip install "splunk-sdk[google]"
# or with uv:
uv add splunk-sdk[google]
```

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

### OpenAI model setup

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Configure an OpenAIModel with model, base_url, and api_key. Use with the Agent in an async context.

```python
from splunklib.ai import Agent, OpenAIModel

model = OpenAIModel(
    model="gpt-4o-mini",
    base_url="https://api.openai.com/v1",
    api_key="SECRET",
)

async with Agent(model=model) as agent: ....
```

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

### Define local tools with ToolRegistry in tools.py

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Example implementation of a local tools file. The registry.tool() decorator registers the function as a tool, and the registry.run() call in the main block starts the tool server.

```python
from splunklib.ai.registry import ToolRegistry

registry = ToolRegistry()


@registry.tool()
def hello(name: str) -> str:
    """Returns a hello message"""
    return f"Hello {name}!"


if __name__ == "__main__":
    registry.run()
```

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

### Start Splunk Docker container and run integration tests

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Commands to start a Splunk Docker container and run integration tests. The integration suite requires docker/podman. Do not run against a production instance.

```sh
# This command starts a Splunk Docker container
# and waits until it reaches an operational state.
SPLUNK_VERSION=latest make docker-start

# Run the integration tests:
make test-integration
```

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

### Anthropic model setup

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Configure an AnthropicModel with model, base_url, and api_key. Use with the Agent in an async context.

```python
from splunklib.ai import Agent, AnthropicModel

model = AnthropicModel(
    model="claude-haiku-4-5-20251001",
    base_url="https://api.anthropic.com",
    api_key="SECRET",
)

async with Agent(model=model) as agent: ....
```

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

### Configure remote tool filtering with allowlist

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Example of setting up tool filtering for an Agent. Remote tools must be intentionally allowlisted before being made available to the LLM.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.ai.tool_settings import (
    LocalToolSettings,
    RemoteToolSettings,
    ToolAllowlist,
    ToolSettings,
)
from splunklib.client import connect

model = OpenAIModel(...)
service = connect(...)

async with Agent(
    model=model,
    system_prompt="Your name is Stefan",
    service=service,
    tool_settings=ToolSettings(
        local=True,
        remote=RemoteToolSettings(
            allowlist=ToolAllowlist(names=["tool_name"], tags=["tag1", "tag2"])
        ),
    ),
) as agent:
    ...
```

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

### Application

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Represents a Splunk application. Provides methods to retrieve setup information, package details, and update information.

```APIDOC
## Application

### Description
Represents a Splunk application. Provides methods to retrieve setup information, package details, and update information.

### Methods
- **setupInfo** - Retrieves setup information for the application.
- **package** - Retrieves the application package.
- **updateInfo** - Retrieves update information for the application.
```

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

### Package App for Splunk

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Installs dependencies to bin/lib/ with a platform-specific wheel and creates a tarball of the App. The --platform flag must match the Splunk platform, not your development machine.

```sh
python3 -m pip install . \
  --target bin/lib/ \
  # Needs to match the platform Splunk is built and
  # ran on, NOT the one you're writing your App on
  --platform manylinux2014_aarch64 \
  --only-binary=:all:

gtar --transform='s,^,<your_app>/,' \
  --exclude="__pycache__" \
  -czf dist/<your_app>.tgz \
  bin default

# `<your_app>.tgz` should be now ready in `dist/`!
```

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

### Structured output with output_schema

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to configure an Agent with a pydantic BaseModel output schema and use invoke_with_data to get structured results, reducing prompt injection risk.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.client import connect
from typing import Literal
from pydantic import BaseModel, Field

model = OpenAIModel(...)
service = connect(...)


class Output(BaseModel):
    service_name: str = Field(
        description="Name of the service or component where the failure occurred",
        min_length=1,
    )

    severity: Literal["critical", "high", "medium", "low", "info"] = Field(
        description="Assessed severity of the failure based on impact and urgency"
    )

    summary: str = Field(
        description="Concise human-readable summary of what went wrong",
        min_length=1,
    )


async with Agent(
    model=model,
    service=service,
    system_prompt="You are an agent, whose job is to determine the details of provided failure logs",
    output_schema=Output,
) as agent:
    # Use invoke_with_data when passing external data to the agent to reduce
    # the risk of prompt injection.
    result = await agent.invoke_with_data(
        instructions="Analyze this log and determine the failure details.",
        data=log,
    )

    # Make use of the output.
    result.structured_output.service_name
    result.structured_output.severity
    result.structured_output.summary
```

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

### Example enriched event output

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/examples/ai_modinput_app/README.md

Sample output of an enriched event from the modular input, showing fields like date, human_readable, precipitation, temp_max, temp_min, weather, and wind.

```txt
{
    date: 2012-01-04
    human_readable: On January 4, 2012, it was rainy with 20.3 mm of precipitation, temperatures ranged from 5.6°C to 12.2°C, and there was a light wind of 4.7 m/s.
    It was probably not a great day to go outside for most people, due to the rainy weather.
    precipitation: 20.3
    temp_max: 12.2
    temp_min: 5.6
    weather: rain
    wind: 4.7
}
```

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

### Decorator-based tool middleware (mock_temperature)

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Example of a decorator-based tool middleware using @tool_middleware. It returns a mocked result for the 'temperature' tool and passes other calls to the handler.

```python
from splunklib.ai.middleware import (
    tool_middleware,
    ToolMiddlewareHandler,
    ToolRequest,
    ToolResponse,
)


@tool_middleware
async def mock_temperature(request: ToolRequest, handler: ToolMiddlewareHandler) -> ToolResponse:
    if request.call.name == "temperature":
        return ToolResponse(result=ToolResult(content="25.0", structured_content=None))
    return await handler(request)
```

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

### Decorator-based agent middleware (force_tool_call)

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Example of a decorator-based agent middleware using @agent_middleware. It retries the handler until the agent makes at least one tool call.

```python
from typing import Any
from splunklib.ai.middleware import (
    agent_middleware,
    AgentMiddlewareHandler,
    AgentRequest,
)
from splunklib.ai.messages import AgentResponse, ToolCall


@agent_middleware
async def force_tool_call(
    request: AgentRequest, handler: AgentMiddlewareHandler
) -> AgentResponse[Any | None]:
    # Keep retrying until the agent makes at least one tool call.
    resp = await handler(request)
    while not any(m for m in resp.messages if isinstance(m, ToolCall)):
        resp = await handler(request)
    return resp
```

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

### Class-based middleware example

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows a full class-based middleware implementing all four middleware hooks: agent, model, tool, and subagent. The agent middleware retries until a tool call is made, the model middleware redacts 'SECRET' from the system message, the tool middleware mocks the 'temperature' tool, and the subagent middleware mocks the 'SummaryAgent' subagent.

```python
from typing import Any, override
from splunklib.ai.messages import SubagentTextResult, ToolResult
from splunklib.ai.middleware import (
    AgentMiddleware,
    AgentMiddlewareHandler,
    AgentRequest,
    ModelMiddlewareHandler,
    ModelRequest,
    ModelResponse,
    SubagentMiddlewareHandler,
    SubagentRequest,
    SubagentResponse,
    ToolMiddlewareHandler,
    ToolRequest,
    ToolResponse,
)
from splunklib.ai.messages import AgentResponse, ToolCall


class ExampleMiddleware(AgentMiddleware):
    @override
    async def agent_middleware(
        self, request: AgentRequest, handler: AgentMiddlewareHandler
    ) -> AgentResponse[Any | None]:
        # Keep retrying until the agent makes at least one tool call.
        resp = await handler(request)
        while not any(m for m in resp.messages if isinstance(m, ToolCall)):
            resp = await handler(request)
        return resp

    @override
    async def model_middleware(
        self, request: ModelRequest, handler: ModelMiddlewareHandler
    ) -> ModelResponse:
        return await handler(
            ModelRequest(
                system_message=request.system_message.replace("SECRET", "[REDACTED]"),
                state=request.state,
            )
        )

    @override
    async def tool_middleware(
        self, request: ToolRequest, handler: ToolMiddlewareHandler
    ) -> ToolResponse:
        if request.call.name == "temperature":
            return ToolResponse(result=ToolResult(content="25.0", structured_content=None))
        return await handler(request)

    @override
    async def subagent_middleware(
        self, request: SubagentRequest, handler: SubagentMiddlewareHandler
    ) -> SubagentResponse:
        if request.call.name == "SummaryAgent":
            return SubagentResponse(
                result=SubagentTextResult(
                    content="Executive summary: no critical incidents detected."
                )
            )
        return await handler(request)
```

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

### Decorator-based subagent middleware (mock_subagent)

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Example of a decorator-based subagent middleware using @subagent_middleware. It returns a mocked response for the 'SummaryAgent' subagent and passes other calls to the handler.

```python
from splunklib.ai.messages import SubagentTextResult
from splunklib.ai.middleware import (
    subagent_middleware,
    SubagentMiddlewareHandler,
    SubagentRequest,
    SubagentResponse,
)


@subagent_middleware
async def mock_subagent(
    request: SubagentRequest, handler: SubagentMiddlewareHandler
) -> SubagentResponse:
    if request.call.name == "SummaryAgent":
        return SubagentResponse(
            result=SubagentTextResult(content="Executive summary: no critical incidents detected.")
        )
    return await handler(request)
```

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

### Endpoint

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Base class for endpoints. Provides get and post methods.

```APIDOC
## Endpoint

### Description
Base class for endpoints. Provides get and post methods.

### Methods
- **get** - Performs a GET request to the endpoint.
- **post** - Performs a POST request to the endpoint.
```

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

### Access Service via ToolContext in a tool

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Example of a tool that uses ToolContext to access the SDK's Service object and run a Splunk query. The service is injected automatically and represents the user who executed the Agent.

```python
from splunklib.ai.registry import ToolContext, ToolRegistry
from splunklib.results import JSONResultsReader

registry = ToolRegistry()


@registry.tool()
def run_splunk_query(ctx: ToolContext) -> list[str]:
    stream = ctx.service.jobs.oneshot(
        "| makeresults count=10 | streamstats count as row_num",
        output_mode="json",
    )

    result = JSONResultsReader(stream)
    output: list[str] = []
    for r in result:
        if isinstance(r, dict):
            output.append(r["row_num"])

    return output


if __name__ == "__main__":
    registry.run()
```

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

### Add external dependencies to App script

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Inserts the 'lib' directory into the Python path so that external dependencies installed to bin/lib/ can be imported in your App script files.

```python
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "lib"))
```

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

### Enable local tools with Agent and ToolSettings

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to configure an Agent to use local tools. Set local=True to enable all local tools, or pass a LocalToolSettings instance with an allowlist to enable only specific tools.

```python
from splunklib.ai.tool_settings import LocalToolSettings, ToolAllowlist, ToolSettings

async with Agent(
    model=model,
    service=service,
    system_prompt="...",
    tool_settings=ToolSettings(
        # local=True,  # enable all local tools
        local=LocalToolSettings(allowlist=ToolAllowlist(names=["tool1"], tags=["tag1"])),
        remote=None,
    ),
) as agent:
    ...
```

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

### Configure Agent with local MCP tools

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to create an Agent with local MCP tools enabled by passing ToolSettings(local=True, remote=None). Requires an OpenAIModel and a connected Splunk service.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.ai.tool_settings import ToolSettings
from splunklib.client import connect

model = OpenAIModel(...)
service = connect(...)

async with Agent(
    model=model,
    system_prompt="Your name is Stefan",
    service=service,
    tool_settings=ToolSettings(local=True, remote=None),
) as agent:
    ...
```

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

### Basic Agent usage with OpenAIModel

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to create an Agent with an OpenAI model and invoke it with a human message. Requires a Splunk service connection and an OpenAI API key. The agent's response is printed as the final message content.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.ai.messages import HumanMessage
from splunklib.client import connect

service = connect(
    scheme="https",
    host="localhost",
    port=8089,
    username="user",
    password="password",
    autologin=True,
)

model = OpenAIModel(
    model="gpt-4o-mini",
    base_url="https://api.openai.com/v1",
    api_key="SECRET",
)

async with Agent(
    model=model,
    system_prompt="Your name is Stefan",
    service=service,
) as agent:
    result = await agent.invoke([HumanMessage(content="What is your name?")])

    print(result.final_message.content)  # My name is Stefan
```

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

### Create a subagent with input_schema and output_schema

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to define a subagent with input and output schemas, and then use it in a parent agent. Input schemas are only for subagents; they receive input via invoke_with_data to reduce prompt injection risk.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.client import connect
from pydantic import BaseModel

model = OpenAIModel(...)
service = connect(...)


class Input(BaseModel): ...


class Output(BaseModel): ...


async with Agent(
    model=model,
    service=service,
    system_prompt="...",
    name="...",
    description="...",
    input_schema=Input,
    output_schema=Output,
) as subagent:
    async with Agent(
        model=model,
        service=service,
        system_prompt="...",
        agents=[subagent],
    ) as agent:
        await agent.invoke(...)
```

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

### Decorator-based model middleware (redact_system_prompt)

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Example of a decorator-based model middleware using @model_middleware. It replaces 'SECRET' with '[REDACTED]' in the system message before passing the request to the handler.

```python
from splunklib.ai.middleware import (
    model_middleware,
    ModelMiddlewareHandler,
    ModelRequest,
    ModelResponse,
)


@model_middleware
async def redact_system_prompt(
    request: ModelRequest, handler: ModelMiddlewareHandler
) -> ModelResponse:
    return await handler(
        ModelRequest(
            system_message=request.system_message.replace("SECRET", "[REDACTED]"),
            state=request.state,
        )
    )
```

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

### Configure Agent with remote MCP tools and allowlist

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to enable remote MCP tools by passing a RemoteToolSettings instance with a ToolAllowlist. The allowlist specifies tool names and tags to whitelist.

```python
from splunklib.ai.tool_settings import RemoteToolSettings, ToolAllowlist, ToolSettings

async with Agent(
    model=model,
    service=service,
    system_prompt="...",
    tool_settings=ToolSettings(
        remote=RemoteToolSettings(
            allowlist=ToolAllowlist(names=["splunk_get_indexes"], tags=["tag1"])
        )
    ),
) as agent:
    ...
```

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

### connect

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/binding.rst

Establishes a connection to a Splunk instance and returns a Context object. This is the primary entry point for creating a connection.

```APIDOC
## connect

### Description
Establishes a connection to a Splunk instance and returns a Context object. This is the primary entry point for creating a connection.

### Method
Function

### Signature
`connect(**kwargs)`

### Parameters
- **kwargs** (dict) - Optional - Connection parameters such as host, port, username, password, etc.

### Returns
- **Context** - A configured Context object for making requests.
```

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

### dispatch(command_class[, argv=sys.argv, input_file=sys.stdin, output_file=sys.stdout, module_name=None, allow_empty_input=True])

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Dispatches a search command class to handle input from stdin and write output to stdout. This is the main entry point for custom search commands.

```APIDOC
## dispatch(command_class[, argv=sys.argv, input_file=sys.stdin, output_file=sys.stdout, module_name=None, allow_empty_input=True])

### Description
Dispatches a search command class to handle input from stdin and write output to stdout. This is the main entry point for custom search commands.

### Parameters
- **command_class** (class) - Required - The search command class to dispatch.
- **argv** (list) - Optional - Command-line arguments. Defaults to sys.argv.
- **input_file** (file) - Optional - Input stream. Defaults to sys.stdin.
- **output_file** (file) - Optional - Output stream. Defaults to sys.stdout.
- **module_name** (str) - Optional - Module name for the command. Defaults to None.
- **allow_empty_input** (bool) - Optional - Whether to allow empty input. Defaults to True.
```

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

### Create and use subagents with Agent constructor

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to define two specialized subagents (debugging_agent and log_analyzer_agent) with different models and tool settings, then pass them to a supervisor agent via the agents parameter. The supervisor uses each subagent's name and description to decide when to call it.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.ai.messages import HumanMessage
from splunklib.ai.tool_settings import LocalToolSettings, ToolAllowlist, ToolSettings
from splunklib.client import connect

model = OpenAIModel(...)
service = connect(...)

async with (
    Agent(
        model=highly_specialized_model,
        service=service,
        system_prompt=(
            "You are a highly specialized debugging agent, your job is to provide as much"
            "details as possible to resolve issues."
            "You have access to debugging-related tools, which you should leverage for your job."
        ),
        name="debugging_agent",
        description="Agent, that provided with logs will analyze and debug complex issues",
        tool_settings=ToolSettings(
            local=LocalToolSettings(allowlist=ToolAllowlist(tags=["debugging"])),
            remote=None,
        ),
    ) as debugging_agent,
    Agent(
        model=low_cost_model,
        service=service,
        system_prompt=(
            "You are a log analyzer agent. Your job is to query logs, based on the details that you receive and"
            "return a summary of interesting logs, that can be used for further analysis."
        ),
        name="log_analyzer_agent",
        description="Agent, that provided with a problem details will return logs, that could be related to the problem",
        tool_settings=ToolSettings(
            local=LocalToolSettings(allowlist=ToolAllowlist(tags=["spl"])),
            remote=None,
        ),
    ) as log_analyzer_agent,
):
    async with Agent(
        model=low_cost_model,
        service=service,
        system_prompt="You are a supervisor agent, use available subagents to perform requested operations.",
        agents=[debugging_agent, log_analyzer_agent],
    ) as agent:
        result = await agent.invoke(
            [
                HumanMessage(
                    content=(
                        "We are facing a production issue, users report that some pages do not exist, but it seems like the 404 are not deterministic."
                        "Query the logs in the index 'main', and try to debug the root cause of this issue."
                    ),
                )
            ]
        )
```

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

### Shorthand to enable all local tools

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows the shorthand for loading all local tools with no filtering by passing local=True to ToolSettings.

```python
tool_settings = ToolSettings(local=True, remote=None)
```

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

### Run test suite and unit tests

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Commands to run the entire test suite or only the unit tests using make targets.

```sh
# Run entire test suite:
make test

# Run only the unit tests:
make test-unit
```

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

### Enable debug logging in splunklib

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Shows how to change the logging level in splunklib using setup_logging(). The default level is WARNING; passing logging.DEBUG enables debug and above logs. Optionally, custom log and date format strings can be provided.

```python
import logging
from splunklib import setup_logging

# To see debug and above level logs
setup_logging(logging.DEBUG)
```

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

### Pass middleware to Agent

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to pass a list of middleware instances to the Agent constructor. The middleware list includes redact_system_prompt, mock_temperature, and mock_subagent.

```python
async with Agent(
    model=model,
    service=service,
    system_prompt="...",
    middleware=[redact_system_prompt, mock_temperature, mock_subagent],
) as agent:
    ...
```

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

### Create .env file from template

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Command to duplicate the .env.template file as .env for development configuration. The .env file is not part of the Splunk platform and should not be used for production credentials.

```sh
cp .env.template .env
```

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

### Run unit and AI tests before declaring change done

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/AGENTS.md

Run `make test-unit` and `make test-ai` before declaring a change done. The comment `# testing` is part of the displayed block.

```sh
# testing
make test-unit
make test-ai
```

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

### Use gen_record to generate events properly

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Shows the recommended way to generate events in a generating command. Use gen_record() from SearchCommand with comma-separated key=value pairs instead of yielding dictionaries directly.

```diff
@Configuration()
class GeneratorTest(GeneratingCommand):
    def generate(self):
-        yield {'_time': time.time(), 'one': 1}
-        yield {'_time': time.time(), 'two': 2}
+        yield self.gen_record(_time=time.time(), one=1)
+        yield self.gen_record(_time=time.time(), two=2)
```

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

### ConfigurationFile

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Represents a configuration file.

```APIDOC
## ConfigurationFile

### Description
Represents a configuration file.
```

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

### Build Structured Prompt with create_structured_prompt

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

If you prefer to build the message manually, create_structured_prompt gives the same separation of instructions and data and can be used directly inside a HumanMessage.

```python
from splunklib.ai import create_structured_prompt
from splunklib.ai.messages import HumanMessage

result = await agent.invoke(
    [
        HumanMessage(
            content=create_structured_prompt(
                instructions="Summarize this security alert and assess its severity.",
                data=alert_payload,
            )
        )
    ]
)
```

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

### Subagent with ConversationStore

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Shows how to create a subagent with its own InMemoryStore and a supervisor agent that can resume conversations with the subagent across invocations.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.ai.conversation_store import InMemoryStore
from splunklib.ai.messages import HumanMessage
from splunklib.client import connect

model = OpenAIModel(...)
service = connect(...)

async with (
    Agent(
        model=model,
        service=service,
        system_prompt=(
            "You are a log analysis expert. When asked to analyze a problem, "
            "ask clarifying questions if needed before querying logs."
        ),
        name="log_analyzer_agent",
        description="Analyzes logs and can ask follow-up questions to narrow down a problem.",
        conversation_store=InMemoryStore(),
    ) as log_analyzer_agent,
):
    async with Agent(
        model=model,
        service=service,
        system_prompt="You are a supervisor. Use the log analyzer agent to investigate issues.",
        agents=[log_analyzer_agent],
    ) as agent:
        # The supervisor calls the subagent and may continue the
        # same conversation with a subagent in the agentic loop and
        # across multiple agent loop invocations.
        await agent.invoke(...)
```

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

### GoogleModel with Vertex AI service account

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Use GoogleModel with Vertex AI using service account credentials. No api_key needed. Credentials must be google.auth.credentials.Credentials-compatible.

```python
from google.oauth2 import service_account
from splunklib.ai import Agent, GoogleModel

credentials = service_account.Credentials.from_service_account_file(
    "path/to/service-account.json",
    scopes=["https://www.googleapis.com/auth/cloud-platform"],
)

model = GoogleModel(
    model="gemini-2.0-flash",
    project="your-gcp-project-id",
    credentials=credentials,
    # location="us-central1",  # optional, defaults to us-central1
)

async with Agent(model=model) as agent:
    ...
```

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

### connect

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Establishes a connection to a Splunk service and returns a Service object.

```APIDOC
## connect

### Description
Establishes a connection to a Splunk service and returns a Service object.

### Method
connect

### Signature
connect(host, port, username, password, ...)

### Parameters
- **host** (string) - Required - The hostname of the Splunk server.
- **port** (int) - Required - The port number of the Splunk management port.
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Returns
- **Service** - A Service object representing the connected Splunk instance.
```

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

### ToolSettings

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Base class for tool settings.

```APIDOC
## ToolSettings

### Description
Base class for tool settings.
```

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

### OpenAIModel with Ollama

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Use OpenAIModel with Ollama's OpenAI-compatible endpoint. api_key is required but ignored.

```python
from splunklib.ai import Agent, OpenAIModel

model = OpenAIModel(
    model="llama3.2:3b",
    base_url="http://localhost:11434/v1",
    api_key="",  # required but ignored
)

async with Agent(model=model) as agent: ....
```

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

### Configuration

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Configuration class for search commands. Provides configuration settings for command behavior.

```APIDOC
## Configuration

### Description
Configuration class for search commands. Provides configuration settings for command behavior.
```

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

### Format code with make lint

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/AGENTS.md

Run `make lint` after editing any Python file to format it with Ruff and isort.

```sh
make lint
```

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

### LocalToolSettings

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Settings for local tools.

```APIDOC
## LocalToolSettings

### Description
Settings for local tools.
```

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

### ToolAllowlist

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Configuration for allowing specific tools.

```APIDOC
## ToolAllowlist

### Description
Configuration for allowing specific tools.
```

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

### Connect with session key

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Connects to a Splunk Enterprise instance using a session key with autologin enabled.

```python
import splunklib.client as client

service = client.connect(host=<HOST_URL>, token=<SESSION_KEY>, autologin=True)
```

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

### GoogleModel with Vertex AI API key

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Use GoogleModel with Vertex AI backend by providing a project. api_key is required, location is optional and defaults to us-central1.

```python
from splunklib.ai import Agent, GoogleModel

model = GoogleModel(
    model="gemini-2.0-flash",
    api_key="YOUR_VERTEX_API_KEY",
    project="your-gcp-project-id",
    # location="us-central1",  # optional, defaults to us-central1
)

async with Agent(model=model) as agent:
    ...
```

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

### Configurations

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Represents a collection of configurations. Provides create and delete operations.

```APIDOC
## Configurations

### Description
Represents a collection of configurations. Provides create and delete operations.

### Methods
- **create** - Creates a new configuration.
- **delete** - Deletes a configuration.
```

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

### Environment helpers

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Environment helper variables for search command development.

```APIDOC
## Environment helpers

### Description
Environment helper variables for search command development.

### Variables
- **app_file** - Path to the application file.
- **app_root** - Root directory of the application.
- **logging_configuration** - Logging configuration.
- **splunk_home** - Splunk home directory.
- **splunklib_logger** - Logger for splunklib.
```

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

### Access modular input metadata from InputDefinition

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Shows how to access modular input app metadata such as server_host, server_uri, and checkpoint_dir from the InputDefinition object within stream_events. This metadata is available from the inputs parameter.

```python
def stream_events(self, inputs, ew):
    # [...]

    # Access the modular input app's metadata (like server_host, server_uri, etc) from `InputDefinition` object
    server_host = inputs.metadata["server_host"]
    server_uri = inputs.metadata["server_uri"]
    checkpoint_dir = inputs.metadata["checkpoint_dir"]
```

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

### create_structured_prompt

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/index.rst

The create_structured_prompt function is used to create a structured prompt for AI models, incorporating security measures.

```APIDOC
## create_structured_prompt

### Description
The create_structured_prompt function is part of the Splunk SDK for Python AI security module. It is used to create a structured prompt for AI models, incorporating security measures.

### Function
`splunklib.ai.security.create_structured_prompt`

### Parameters
No parameters are explicitly documented in the source.

### Returns
No return value is explicitly documented in the source.

### Usage
Call this function to generate a structured prompt that includes security considerations.
```

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

### tool_middleware

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Decorator for creating tool middleware.

```APIDOC
## tool_middleware

### Description
Decorator for creating tool middleware.
```

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

### GoogleModel with Gemini API

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Use GoogleModel with the Gemini API backend. Only model and api_key are required.

```python
from splunklib.ai import Agent, GoogleModel

model = GoogleModel(
    model="gemini-2.0-flash",
    api_key="YOUR_GOOGLE_API_KEY",
)

async with Agent(model=model) as agent:
    ...
```

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

### InputDefinition

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/modularinput.rst

Represents the definition of a modular input instance. Use this class to access the configuration of the input.

```APIDOC
## InputDefinition

### Description
Represents the definition of a modular input instance. Use this class to access the configuration of the input.

### Methods
- **__init__** - Constructor for InputDefinition.
- **parse** - Parses the XML definition of the input.

### Attributes
- **metadata** (dict) - Metadata about the input.
- **parameters** (dict) - Parameters of the input.
- **single_instance** (bool) - Whether the input runs as a single instance.

### Example
```python
from splunklib.modularinput import InputDefinition
# Typically obtained from Script.get_input_definition()
```
```

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

### Configure Agent with Logger for Debugging

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Pass a Python logging.Logger to the Agent constructor to enable detailed tracing and debugging. The agent emits logs for model interactions, tool calls, and subagent calls, and local tool logs are also forwarded to this logger.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.client import connect
import logging

model = OpenAIModel(...)
service = connect(...)

logger = logging.getLogger("test")
logger.setLevel(logging.DEBUG)

async with Agent(
    model=model,
    service=service,
    system_prompt="...",
    logger=logger,
) as agent:
    ...
```

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

### Settings

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Represents service settings. Provides update method.

```APIDOC
## Settings

### Description
Represents service settings. Provides update method.

### Methods
- **update** - Updates the settings.
```

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

### Workaround for CA certificate file not found

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Add this snippet to your code to handle the case where the CA certificate file specified by SSL_CERT_FILE does not exist. It sets SSL_CERT_FILE to an empty string, causing the system CAs to be used instead.

```python
CA_TRUST_STORE = "/opt/splunk/openssl/cert.pem"
if os.environ.get("SSL_CERT_FILE") == CA_TRUST_STORE and not os.path.exists(CA_TRUST_STORE):
    os.environ["SSL_CERT_FILE"] = ""
```

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

### Connect with username/password

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/README.md

Connects to a Splunk Enterprise instance using a username and password with autologin enabled.

```python
import splunklib.client as client

service = client.connect(host=<HOST_URL>, username=<USERNAME>, password=<PASSWORD>, autologin=True)
```

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

### EventingCommand

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Base class for eventing search commands. Provides the transform method and a process method for handling input and output.

```APIDOC
## EventingCommand

### Description
Base class for eventing search commands. Provides the transform method and a process method for handling input and output.

### Methods
#### transform()
Transforms incoming events. Must be implemented by subclasses.

#### process(args=sys.argv[, input_file=sys.stdin, output_file=sys.stdout])
Processes input and writes output. This is the main entry point for the command.

### ConfigurationSettings
Configuration settings for EventingCommand. Excludes configuration_settings, fix_up, items, keys.
```

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

### agent_middleware

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Decorator for creating agent middleware.

```APIDOC
## agent_middleware

### Description
Decorator for creating agent middleware.
```

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

### PredefinedModel

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Base class for predefined AI models.

```APIDOC
## PredefinedModel

### Description
Base class for predefined AI models.
```

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

### NoSuchCapability

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Exception raised when a capability does not exist.

```APIDOC
## NoSuchCapability

### Description
Exception raised when a capability does not exist.
```

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

### model_middleware

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Decorator for creating model middleware.

```APIDOC
## model_middleware

### Description
Decorator for creating model middleware.
```

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

### execute

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Executes a search command. This is a function that runs the command.

```APIDOC
## execute

### Description
Executes a search command. This is a function that runs the command.
```

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

### Option

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Option class for defining command options. Provides a way to declare and parse command-line options.

```APIDOC
## Option

### Description
Option class for defining command options. Provides a way to declare and parse command-line options.
```

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

### RemoteToolSettings

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Settings for remote tools.

```APIDOC
## RemoteToolSettings

### Description
Settings for remote tools.
```

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

### HttpLib

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/binding.rst

Provides low-level HTTP methods for making requests. This class is used internally by Context but can be used directly for custom HTTP operations.

```APIDOC
## HttpLib

### Description
Provides low-level HTTP methods for making requests. This class is used internally by Context but can be used directly for custom HTTP operations.

### Methods

#### delete
- **Description**: Sends a DELETE request.
- **Signature**: `delete(url, **kwargs)`
- **Parameters**:
  - url (str) - Required - The URL.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.

#### get
- **Description**: Sends a GET request.
- **Signature**: `get(url, **kwargs)`
- **Parameters**:
  - url (str) - Required - The URL.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.

#### post
- **Description**: Sends a POST request.
- **Signature**: `post(url, **kwargs)`
- **Parameters**:
  - url (str) - Required - The URL.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.

#### request
- **Description**: Sends a generic HTTP request.
- **Signature**: `request(method, url, **kwargs)`
- **Parameters**:
  - method (str) - Required - The HTTP method.
  - url (str) - Required - The URL.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.
```

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

### Script

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/modularinput.rst

Base class for modular input scripts. Subclass this class and implement the stream_events method to create a modular input.

```APIDOC
## Script

### Description
Base class for modular input scripts. Subclass this class and implement the stream_events method to create a modular input.

### Methods
- **get_scheme** - Returns the scheme of the input.
- **stream_events** - Streams events to Splunk. Must be implemented by subclasses.
- **run** - Runs the script.
- **get_input_definition** - Parses the input definition from stdin.
- **get_validation_definition** - Parses the validation definition from stdin.
- **validate_input** - Validates the input. Override to provide custom validation.

### Example
```python
from splunklib.modularinput import Script, EventWriter, Event

class MyScript(Script):
    def get_scheme(self):
        return Scheme("my_input")

    def stream_events(self, inputs, ew):
        event = Event()
        event.data = "Hello"
        ew.write_event(event)

if __name__ == "__main__":
    script = MyScript()
    script.run()
```
```

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

### ReportingCommand

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Base class for reporting search commands. Provides map and reduce methods and a process method for handling input and output.

```APIDOC
## ReportingCommand

### Description
Base class for reporting search commands. Provides map and reduce methods and a process method for handling input and output.

### Methods
#### map()
Maps incoming events. Must be implemented by subclasses.

#### reduce()
Reduces mapped events. Must be implemented by subclasses.

#### process(args=sys.argv[, input_file=sys.stdin, output_file=sys.stdout])
Processes input and writes output. This is the main entry point for the command.

### ConfigurationSettings
Configuration settings for ReportingCommand. Excludes configuration_settings, fix_up, items, keys.
```

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

### AnthropicModel with Ollama

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Use AnthropicModel with Ollama's Anthropic-compatible endpoint. api_key is required but ignored.

```python
from splunklib.ai import Agent, AnthropicModel

model = AnthropicModel(
    model="llama3.2:3b",
    base_url="http://localhost:11434",
    api_key="",  # required but ignored
)

async with Agent(model=model) as agent: ....
```

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

### GeneratingCommand

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/searchcommands.rst

Base class for generating search commands. Provides the generate method and a process method for handling input and output.

```APIDOC
## GeneratingCommand

### Description
Base class for generating search commands. Provides the generate method and a process method for handling input and output.

### Methods
#### generate()
Generates events. Must be implemented by subclasses.

#### process(args=sys.argv[, input_file=sys.stdin, output_file=sys.stdout, allow_empty_input=True])
Processes input and writes output. This is the main entry point for the command.

### ConfigurationSettings
Configuration settings for GeneratingCommand. Excludes configuration_settings, fix_up, items, keys.
```

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

### Stanza

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/client.rst

Represents a stanza in a configuration file. Provides submit method.

```APIDOC
## Stanza

### Description
Represents a stanza in a configuration file. Provides submit method.

### Methods
- **submit** - Submits data to the stanza.
```

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

### Use InMemoryStore to persist conversation history

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/splunklib/ai/README.md

Creates an Agent with an InMemoryStore so that message history is retained across invocations. The second invoke recalls the name set in the first, demonstrating stateful behavior.

```python
from splunklib.ai import Agent, OpenAIModel
from splunklib.ai.conversation_store import InMemoryStore
from splunklib.ai.messages import HumanMessage
from splunklib.client import connect

model = OpenAIModel(...)
service = connect(...)

async with Agent(
    model=model,
    service=service,
    system_prompt="",
    conversation_store=InMemoryStore(),
) as agent:
    await agent.invoke([HumanMessage(content="Hi, my name is Chris.")])
    result = await agent.invoke([HumanMessage(content="What is my name?")])
    print(result.final_message.content)  # Chris
```

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

### Context

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/binding.rst

Represents a connection to a Splunk instance and provides methods for making HTTP requests, managing authentication, and handling cookies.

```APIDOC
## Context

### Description
Represents a connection to a Splunk instance and provides methods for making HTTP requests, managing authentication, and handling cookies.

### Methods

#### connect
- **Description**: Establishes a connection to the Splunk instance.
- **Signature**: `connect(**kwargs)`
- **Parameters**: kwargs (dict) - Optional - Connection parameters.
- **Returns**: Context - The connected context.

#### delete
- **Description**: Sends a DELETE request to the specified path.
- **Signature**: `delete(path_segment, **kwargs)`
- **Parameters**:
  - path_segment (str) - Required - The URL path.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.

#### get
- **Description**: Sends a GET request to the specified path.
- **Signature**: `get(path_segment, **kwargs)`
- **Parameters**:
  - path_segment (str) - Required - The URL path.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.

#### get_cookies
- **Description**: Returns the cookies associated with the context.
- **Signature**: `get_cookies()`
- **Returns**: dict - The cookies.

#### has_cookies
- **Description**: Checks if the context has cookies.
- **Signature**: `has_cookies()`
- **Returns**: bool - True if cookies exist, False otherwise.

#### login
- **Description**: Performs authentication and obtains a session token.
- **Signature**: `login(**kwargs)`
- **Parameters**: kwargs (dict) - Optional - Login parameters.
- **Returns**: None

#### logout
- **Description**: Ends the session and clears authentication.
- **Signature**: `logout()`
- **Returns**: None

#### post
- **Description**: Sends a POST request to the specified path.
- **Signature**: `post(path_segment, **kwargs)`
- **Parameters**:
  - path_segment (str) - Required - The URL path.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.

#### request
- **Description**: Sends a generic HTTP request.
- **Signature**: `request(method, path_segment, **kwargs)`
- **Parameters**:
  - method (str) - Required - The HTTP method (GET, POST, etc.).
  - path_segment (str) - Required - The URL path.
  - kwargs (dict) - Optional - Additional request parameters.
- **Returns**: Response - The response object.
```

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

### Agent.invoke

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Invokes the agent with a given input and returns the agent's response.

```APIDOC
## Agent.invoke

### Description
Invokes the agent with the provided input and returns the agent's response.

### Method
invoke

### Signature
`invoke(input)`

### Parameters
- **input** (any) - Required - The input to the agent.

### Returns
- The agent's response.
```

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

### AgentMiddleware

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Base class for agent middleware.

```APIDOC
## AgentMiddleware

### Description
Base class for agent middleware.
```

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

### ToolRequest

Source: https://github.com/splunk/splunk-sdk-python/blob/develop/docs/ai.rst

Request object for tool middleware.

```APIDOC
## ToolRequest

### Description
Request object for tool middleware.
```
Tokens:
Raw