Skip to main content
Experience Search is Acontext’s advanced search abilty to find the revelant skills for Agent. It can use Embedding or Agent to find relevant content from skills space.

​
Quick Start

from acontext import AcontextClient

client = AcontextClient(
    api_key="sk-ac-your-root-api-bearer-token",
    base_url="http://localhost:8029/api/v1"
)
client.ping()
# Fast mode - quick semantic search
result = client.spaces.experience_search(
    space_id="space-uuid",
    query="How to implement authentication?",
    limit=10,
    mode="fast"
)

# Access results
for block in result.cited_blocks:
    print(f"{block.title} (distance: {block.distance})")

​
Search Modes

Fast Mode

Quick semantic search using embeddings.

Agentic Mode

Agentic iterative search using space agent.

​
Fast Mode Details

  • Speed: ~100-500ms response time
  • Output: Relevant blocks only
  • Best for: Simple lookups, known information retrieval
  • Use when: You need quickly search the skills and latency matters.

​
Agentic Mode Details

  • Speed: ~2-10s depending on iterations
  • Output: Relevant blocks with iterative refinement
  • Best for: Complex queries, research, analysis
  • Use when: You want AI to deeply understand it’s own past and go through its skills like human.
# Agentic mode with advanced parameters
result = client.spaces.experience_search(
    space_id="space-uuid",
    query="What are the best practices for API security?",
    mode="agentic",
    semantic_threshold=0.8,
    max_iterations=20,
    limit=15
)

​
Response Example

{
  "cited_blocks": [
    {
      "block_id": "block-uuid",
      "title": "Authentication Guide", 
      "type": "page",
      "props": {
        "use_when": "...", 
        "preferences": "...", 
        "tool_sops": [{"action": "...", "tool_name": "..."}]},
      "distance": 0.23
    }
  ]
}

​
Parameters

​
query
string
required
Your search question in natural language
​
mode
string
default:"fast"
Search mode: "fast" or "agentic"
​
limit
integer
default:"10"
Maximum results to return (1-50)
​
semantic_threshold
number
Distance threshold for agentic mode (0=identical, 2=opposite)
​
max_iterations
integer
default:"16"
Maximum iterations for agentic mode (1-100)

​
Distance Scores

  • 0.0-0.5: Very similar content
  • 0.5-1.0: Related content
  • 1.0+: Less relevant content
Lower distance scores indicate higher semantic similarity to your query.

​
Using Results in Agent Prompts

Pack search results into prompts for your Agent: 
def build_prompt_with_context(query: str, search_results):
    """Build a prompt with search context for Agent models."""
    
    # Build context from search results
    context_parts = []
    for block in search_results.cited_blocks:
        context_parts.append(f"""
Use when: {block.title}
Skill: {block.props}
""")
    
    context = "\n---\n".join(context_parts)
    
    # Build final prompt
    prompt = f"""SKILLS REFERENCES:
{context}

USER REQUEST: {query}

Please Act to complete the request"""
    
    return prompt

# Example usage
result = client.spaces.experience_search(
    space_id="space-uuid",
    query="How should I handle user authentication?",
    mode="fast",
    limit=5
)

prompt = build_prompt_with_context(
    "How should I handle user authentication?", 
    result
)

# Send to your AI
# response = openai_client.chat.completions.create(...)

​
Understanding SOP Blocks

SOP (Standard Operating Procedure) blocks are structured skill components that contain actionable procedures and tool usage patterns. When you search for skills, the results include SOP blocks that define specific workflows and tool interactions.

​
SOP Block Structure

Each skill block can contain tool_sops - an array of standard operating procedures that define:
  • Action: The specific action or step to perform
  • Tool Name: The tool or system to use for this action
  • Context: When and how to apply this procedure
sop block example
{
    "use_when": "star a github repo",
    "preferences": "use personal account. star but not fork",
    "tool_sops": [
        {"tool_name": "goto", "action": "goto the user given github repo url"},
        {"tool_name": "click", "action": "find login button if any, and start to login first"},
        ...
    ]
}
A SOP block has not only some text summaries about task and preferences, but also the exact tool chain to achieve that. We also prepare some util sdks to manage the tools, in order you may change some tools and invalidate some sops.