Documentation

Standalone Agents

Direct access to AI agents without chat sessions — for search, synthesis, analysis, and organization

Two Agent Resources

The SDK exposes five standalone agent methods across two resources:

client.agent_search — Image search and document search (see Semantic Search)
client.agent_operations — Report synthesis, document analysis, and file organization

When to Use Standalone Agents

Single Operations: One search, synthesis, or analysis without conversation context
Structured Results: Machine-readable results with scores, metadata, and typed responses
Custom UI: Build your own interface with result refs and action details
Batch Processing: Run many operations programmatically
Lower Overhead: No session management required

Async vs Sync

This page shows async examples. For sync applications, use SyncAionVision — the API is identical without async/await. See Sync Client Usage below.

Search Agents

Access via client.agent_search — see the Semantic Search guide for full documentation.

result = await client.agent_search.images("damaged utility poles")
print(f"Found {result.count} images")

docs = await client.agent_search.documents("safety procedures")
print(f"Found {docs.count} document sections")

Report Synthesis

Access via client.agent_operations

Basic Synthesis

result = await client.agent_operations.synthesize(
    "Summarize the key findings across all inspection reports",
    document_ids=["doc_report_q1", "doc_report_q2"]
)

print(f"Report ({result.execution_time_ms}ms):")
print(result.report)
print(f"\nSummary: {result.summary}")

With Images and Auto-Save

result = await client.agent_operations.synthesize(
    "Write a damage assessment report with photo evidence",
    image_ids=["img_damage_01", "img_damage_02", "img_damage_03"],
    document_ids=["doc_inspection_checklist"],
    auto_save=True
)

print(f"Images included: {result.image_count}")
print(f"Documents included: {result.document_count}")
if result.saved_document_id:
    print(f"Report saved as document: {result.saved_document_id}")

Document Analysis

result = await client.agent_operations.analyze_documents(
    "Compare the warranty terms between these two contracts",
    document_ids=["doc_contract_2024", "doc_contract_2025"]
)

print(f"Analysis: {result.analysis}")
print(f"Summary: {result.summary}")
print(f"Documents analyzed: {result.document_count}")

# Chunk references show exactly which parts were cited
for ref in result.chunk_references:
    print(f"  Cited: {ref.document_filename} p{ref.page_numbers}")

File Organization

Organize by Category

result = await client.agent_operations.organize(
    "Sort these equipment photos by damage type",
    image_ids=["img_001", "img_002", "img_003", "img_004", "img_005"]
)

print(f"Summary: {result.summary}")
print(f"Folders created: {result.folders_created}")
print(f"Files moved: {result.files_moved}")

for action in result.actions:
    print(f"  {action.action}: {action.folder_name} ({action.file_count} files)")

Into a Parent Folder

result = await client.agent_operations.organize(
    "Group these documents by project phase",
    document_ids=["doc_a", "doc_b", "doc_c", "doc_d"],
    parent_folder_id="fld_projects_2024"
)
print(f"Created {result.folders_created} sub-folders under parent")

Response Types

Search Results

@dataclass(frozen=True)
class ImageSearchAgentResult:
    success: bool
    results: list[ImageSearchResultItem]
    count: int
    result_ids: list[str]
    summary: str
    summary_raw: str
    result_refs: dict[str, ResultRefData]
    execution_time_ms: int
    iterations: int

@dataclass(frozen=True)
class DocumentSearchAgentResult:
    success: bool
    results: list[DocumentChunkResultItem]
    count: int
    chunk_ids: list[str]
    document_ids: list[str]
    summary: str
    summary_raw: str
    result_refs: dict[str, ResultRefData]
    search_mode: str
    execution_time_ms: int
    iterations: int

Operation types (SynthesizeResult, DocumentAnalysisResult, OrganizeResult) are documented in the SDK Types Reference.

Sync Client Usage

from aion import SyncAionVision

with SyncAionVision(api_key="aion_...") as client:
    # Search agents
    result = client.agent_search.images("damaged equipment")
    print(f"Found {result.count} images")

    docs = client.agent_search.documents("safety procedures")
    print(f"Found {docs.count} document chunks")

    # Operation agents
    report = client.agent_operations.synthesize(
        "Summarize findings",
        image_ids=result.result_ids[:5]
    )
    print(report.report)

    analysis = client.agent_operations.analyze_documents(
        "Extract key dates",
        document_ids=["doc_contract"]
    )
    print(analysis.analysis)

Complete Workflow

Search and Synthesize

from aion import AionVision

async with AionVision.from_env() as client:
    # Step 1: Search for relevant images
    images = await client.agent_search.images(
        "equipment showing signs of wear or damage", limit=20
    )
    print(f"Found {images.count} images")

    # Step 2: Search for related documents
    docs = await client.agent_search.documents(
        "maintenance and inspection reports", document_types=["pdf"]
    )
    print(f"Found {docs.count} document sections")

    # Step 3: Synthesize a report from the findings
    report = await client.agent_operations.synthesize(
        "Write a maintenance status report based on the equipment "
        "photos and inspection documents",
        image_ids=images.result_ids[:10],
        document_ids=list(set(docs.document_ids))[:5],
        auto_save=True
    )

    print(f"\nReport ({report.execution_time_ms}ms):")
    print(report.report)
    if report.saved_document_id:
        print(f"\nSaved as: {report.saved_document_id}")

Prefer Pipelines for Multi-Step Workflows

The example above makes 3 separate HTTP calls and requires manual ID plumbing. The Pipeline builder does the same thing in a single call with automatic data wiring:

result = await (
    client.pipeline()
    .search_images("equipment showing signs of wear or damage")
    .search_documents("maintenance and inspection reports")
    .synthesize(
        "Write a maintenance status report",
        depends_on=[0, 1],
    )
    .run()
)
print(result.final.summary)