evolv Agent SDK for Python

Python SDK for evolv Code, an AI coding assistant with full bidirectional streaming support.

Installation

pip install evolv-agent-sdk

Note: The evolv Code CLI must be installed separately. Build from source at /Users/jdnewhouse/repos/evolv-code or set EVOLV_CODE_CLI_PATH environment variable.

Quick Start

Simple Query

import asyncio
from evolv_agent_sdk import query, EvolvAgentOptions, AssistantMessage, TextBlock

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(f"evolv: {block.text}")

asyncio.run(main())

Multi-Query Client

import asyncio
from evolv_agent_sdk import EvolvSDKClient, EvolvAgentOptions, AssistantMessage, TextBlock

async def main():
    async with EvolvSDKClient() as client:
        # First query
        await client.query("What files are in this directory?")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

        # Second query (note: each query is independent)
        await client.query("How many are Python files?")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

asyncio.run(main())

Bidirectional Streaming Mode

evolv Code CLI supports full bidirectional streaming with --input-format stream-json:

import asyncio
from evolv_agent_sdk import query, EvolvAgentOptions
from evolv_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

async def my_can_use_tool(tool_name, tool_input, context):
    """Custom tool permission callback."""
    if tool_name == "Bash" and "rm" in tool_input.get("command", ""):
        return PermissionResultDeny(message="Destructive command blocked")
    return PermissionResultAllow()

async def main():
    options = EvolvAgentOptions(
        can_use_tool=my_can_use_tool,
    )

    async for message in query(
        prompt=my_async_input_generator(),  # AsyncIterable for streaming
        options=options,
    ):
        print(message)

asyncio.run(main())

API Reference

query()

One-shot query function for simple, stateless interactions.

async for message in query(
    prompt="Your question here",
    options=EvolvAgentOptions(
        cwd="/path/to/working/directory",
        model="your-model",
    )
):
    print(message)

EvolvSDKClient

Client for running multiple queries. Each query spawns a new process.

async with EvolvSDKClient(options) as client:
    await client.query("First question")
    async for msg in client.receive_response():
        print(msg)

    await client.query("Second question")
    async for msg in client.receive_response():
        print(msg)

EvolvAgentOptions

Configuration options for the SDK:

Option	Type	Description
cli_path	str | Path	Path to evolv CLI binary
cwd	str | Path	Working directory for commands
model	str	Model to use
connection	str	Snowflake connection name
resume	str	Session ID to resume
continue_conversation	bool	Continue most recent session
env	dict[str, str]	Environment variables
can_use_tool	Callable	Tool permission callback (bidirectional mode)
hooks	dict	SDK hooks for PreToolUse, PostToolUse, etc.
mcp_servers	dict	SDK MCP servers (in-process)

Environment Variables

Variable	Description
EVOLV_CODE_CLI_PATH	Path to evolv CLI binary
EVOLV_CODE_ENTRYPOINT	SDK entrypoint identifier
EVOLV_AGENT_SDK_SKIP_VERSION_CHECK	Skip CLI version check
EVOLV_CODE_STREAM_CLOSE_TIMEOUT	Timeout for stream close (ms)

Message Types

The SDK yields several message types:

• AssistantMessage - Response from evolv with content blocks
• UserMessage - User input messages
• SystemMessage - System notifications
• ResultMessage - Final result with metadata

Content Blocks

AssistantMessage.content contains a list of content blocks:

• TextBlock - Text response
• ThinkingBlock - Internal reasoning (if enabled)
• ToolUseBlock - Tool invocation
• ToolResultBlock - Tool execution result

Features

Bidirectional Streaming

evolv Code CLI supports --input-format stream-json for full bidirectional communication:

Feature	evolv Code	Cortex Code
--input-format stream-json	✅ Supported	❌ Not available
can_use_tool callback	✅ Supported	❌ Not available
interrupt()	✅ Supported	❌ Not available
set_permission_mode()	✅ Supported	❌ Not available
set_model()	✅ Supported	❌ Not available
SDK Hooks	✅ Supported	❌ Not available
SDK MCP Servers	✅ Supported	❌ Not available

Fallback Mode

When using Cortex CLI (without bidirectional support), the SDK falls back to print mode:

# Use --continue to resume the most recent session
options = EvolvAgentOptions(continue_conversation=True)

# Or resume a specific session
options = EvolvAgentOptions(resume="session-id-here")

Backward Compatibility

For migration from Claude Agent SDK or Cortex Agent SDK:

from evolv_agent_sdk import (
    # Claude aliases
    ClaudeSDKClient,      # Alias for EvolvSDKClient
    ClaudeAgentOptions,   # Alias for EvolvAgentOptions
    ClaudeSDKError,       # Alias for EvolvSDKError

    # Cortex aliases
    CortexSDKClient,      # Alias for EvolvSDKClient
    CortexAgentOptions,   # Alias for EvolvAgentOptions
    CortexSDKError,       # Alias for EvolvSDKError
)

License

MIT License - see LICENSE for details.

Links

• evolv Code CLI
• GitHub Repository
• Issue Tracker