Agents API

Core classes for building and managing Strix agents

Overview

The Agents API provides the foundation for building autonomous security testing agents. The BaseAgent class handles the agent lifecycle, tool execution, and interaction with the LLM.

BaseAgent

The base class for all Strix agents. Manages the agent loop, tool execution, and state management.

Constructor

from strix.agents import BaseAgent

agent = BaseAgent(config: dict[str, Any])

config · dict[str, Any] · required

Configuration dictionary for the agent.

Show config properties

llm_config · LLMConfig · required

LLM configuration for the agent

state · AgentState · default: "None"

Existing agent state to restore from

max_iterations · int · default: "300"

Maximum number of iterations before stopping

llm_config_name · str · default: "'default'"

Name of the LLM configuration

local_sources · list[dict[str, str]] · default: "[]"

Local source directories to mount in the sandbox

non_interactive · bool · default: "False"

Whether to run in non-interactive mode

Properties

agent_name · str

The name of the agent class

max_iterations · int · default: "300"

Maximum number of iterations allowed

state · AgentState

Current agent state including messages and context

llm · LLM

The LLM instance used by the agent

config · dict[str, Any]

Agent configuration dictionary

Methods

agent_loop

async def agent_loop(task: str) -> dict[str, Any]

Runs the main agent loop until completion or max iterations.

task · str · required

The task for the agent to accomplish

return · dict[str, Any]

Final result containing success status and any output

Example:

agent = BaseAgent({
    "llm_config": llm_config,
    "max_iterations": 100
})

result = await agent.agent_loop("Scan example.com for vulnerabilities")
print(result)  # {'success': True, ...}

cancel_current_execution

def cancel_current_execution() -> None

Cancels the currently running execution task.

Example:

agent.cancel_current_execution()

set_agent_identity

def set_agent_identity(agent_name: str | None, agent_id: str | None) -> None

Sets the agent’s identity metadata.

agent_name · str | None

Human-readable agent name

agent_id · str | None

Unique agent identifier

AgentState

Manages the state of an agent including messages, context, and execution status.

Constructor

from strix.agents.state import AgentState

state = AgentState(
    agent_name: str = "Strix Agent",
    max_iterations: int = 300
)

agent_name · str · default: "'Strix Agent'"

Name of the agent

max_iterations · int · default: "300"

Maximum iterations allowed

Properties

agent_id · str

Unique identifier (auto-generated)

agent_name · str

Agent name

parent_id · str | None

Parent agent ID for sub-agents

sandbox_id · str | None

Docker container ID for the sandbox

task · str

Current task description

iteration · int

Current iteration count

completed · bool

Whether the task is completed

messages · list[dict[str, Any]]

Conversation history

context · dict[str, Any]

Additional context storage

Methods

add_message

def add_message(
    role: str,
    content: Any,
    thinking_blocks: list[dict[str, Any]] | None = None
) -> None

Adds a message to the conversation history.

role · str · required

Message role: “user” or “assistant”

content · Any · required

Message content

thinking_blocks · list[dict[str, Any]] | None

Optional thinking blocks from reasoning models

increment_iteration

def increment_iteration() -> None

Increments the iteration counter.

set_completed

def set_completed(final_result: dict[str, Any] | None = None) -> None

Marks the agent as completed.

final_result · dict[str, Any] | None

Final result data

get_conversation_history

def get_conversation_history() -> list[dict[str, Any]]

Returns the full conversation history.

return · list[dict[str, Any]]

List of message dictionaries

get_execution_summary

def get_execution_summary() -> dict[str, Any]

Returns a summary of the agent’s execution.

return · dict[str, Any]

Dictionary containing agent_id, task, iteration count, completion status, etc.

Example:

state = AgentState(agent_name="Scanner", max_iterations=50)
state.add_message("user", "Find vulnerabilities in the API")
state.increment_iteration()

if state.iteration >= state.max_iterations:
    state.set_completed({"success": False, "reason": "max_iterations"})

summary = state.get_execution_summary()
print(summary["iteration"])  # Current iteration count

Usage Example

import asyncio
from strix.agents import BaseAgent
from strix.llm import LLMConfig

async def main():
    # Configure LLM
    llm_config = LLMConfig(
        model_name="claude-3-5-sonnet-20241022",
        scan_mode="standard"
    )
    
    # Create agent
    agent = BaseAgent({
        "llm_config": llm_config,
        "max_iterations": 100,
        "non_interactive": True
    })
    
    # Run agent
    result = await agent.agent_loop(
        "Scan the web application at https://example.com"
    )
    
    print(f"Success: {result.get('success')}")
    print(f"Iterations: {agent.state.iteration}")

if __name__ == "__main__":
    asyncio.run(main())