### Get and Execute Archived Tool

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Demonstrates how to retrieve metadata for an archived tool and then execute it with specific input data. Ensure WORKSPACE_ID and TOOL_ID are defined.

```python
tool_info = svc.get_archived_tool(
    GetArchivedToolRequest(workspace_id=WORKSPACE_ID, id=TOOL_ID)
)
print("tool name:", tool_info.name)
print("tool description:", tool_info.description)

result = svc.exec_archived_tool(
    ExecArchivedToolRequest(
        workspace_id=WORKSPACE_ID,
        plugin_id=tool_info.plugin_id,
        tool_id=TOOL_ID,
        config="",  # JSON string of credentials if required
        input_data=json.dumps({"query": "latest AI papers"}),
    )
)
if result.success:
    print("output:", result.output)
else:
    print("error:", result.reason)
```

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

### Asynchronous Agent Invocation

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes and invokes an Agent asynchronously to get a response. This example shows the async interface for agent initialization and invocation, suitable for non-blocking operations.

```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.chat import ChatService
from hiagent_components.agent.base import Agent

load_dotenv()

svc = ChatService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_AGENT_APP_KEY")

# --- Async invocation ---
async def run_async_agent():
    agent = await Agent.ainit(
        svc=svc,
        app_key=APP_KEY,
        user_id="user-42",
        variables={"name": "weather_assistant"},
    )
    answer = await agent.ainvoke({"query": "What is the UV index today?"})
    print(answer)

asyncio.run(run_async_agent())
```

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

### Run Workflow Asynchronously and Poll Status

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initiates an asynchronous workflow run and then polls its status until completion. This example demonstrates the async interface for starting a workflow and checking its status periodically.

```python
import os, json, asyncio
from hiagent_api.workflow import WorkflowService
from hiagent_api.workflow_types import (
    GetWorkflowRequest, RunWorkflowRequest, QueryWorkflowStatusRequest,
)

svc = WorkflowService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_APP_KEY")

# --- Asynchronous run + poll ---
async def run_async():
    async_resp = await svc.arun_workflow_async(
        APP_KEY,
        RunWorkflowRequest(
            input_data=json.dumps({"query": "Translate to English"}),
            user_id="user-001",
            app_key=APP_KEY,
            no_debug=True,
        ),
    )
    run_id = async_resp.run_id
    print("started run_id:", run_id)

    # poll until finished
    import time
    while True:
        status_resp = await svc.aquery_workflow_status(
            APP_KEY,
            QueryWorkflowStatusRequest(app_key=APP_KEY, user_id="user-001", run_id=run_id),
        )
        if status_resp.status in ("succeed", "failed"):
            print("final status:", status_resp.status)
            print("output:", status_resp.output)
            break
        time.sleep(1)

asyncio.run(run_async())
```

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

### Integrate MCP Server Tools with HiAgent

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Wraps an MCP server's tool as a HiAgent BaseTool, enabling invocation through the standard BaseTool interface. Requires the 'mcp' extra to be installed.

```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.tool import ToolService
from hiagent_components.integrations.mcp.tool import MCPTool  # requires mcp extra

load_dotenv()

async def run_mcp():
    # MCPTool wraps an MCP server's tool as a HiAgent BaseTool
    mcp_tool = await MCPTool.ainit(
        server_url="http://localhost:8080",  # MCP server endpoint
        tool_name="get_current_time",
    )
    print("name:", mcp_tool.name)
    print("schema:", mcp_tool.input_schema)
    result = await mcp_tool.ainvoke(input={"timezone": "America/New_York"})
    print("result:", result)

asyncio.run(run_mcp())

```

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

### Synchronous Agent Invocation

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes and invokes an Agent synchronously to get a response. Requires setting up ChatService and Agent, and providing user ID and variables. The input is a dictionary, and the output is the full text response.

```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.chat import ChatService
from hiagent_components.agent.base import Agent

load_dotenv()

svc = ChatService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_AGENT_APP_KEY")

# --- Synchronous invocation ---
agent = Agent.init(
    svc=svc,
    app_key=APP_KEY,
    user_id="user-42",
    variables={"name": "weather_assistant"},
)
answer = agent.invoke({"query": "Is it going to rain in Beijing tomorrow?"})
print(answer)  # Full text response
```

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

### Get Evaluation Task Report

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Fetches the evaluation report for a completed task. Includes built-in retry logic.

```python
report = eva_client.get_task_report(task_id="task-id-here")
print("rules:", [r.RuleID for r in (report.Rules or [])])
print("targets:", [t.TargetID for t in (report.Targets or [])])
```

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

### Agent Invoke (Synchronous)

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Interacts with a conversational agent synchronously to get a response.

```APIDOC
## Agent Invoke (Synchronous)

### Description
This method allows for synchronous invocation of an Agent, sending a query and receiving a full text response.

### Method
`agent.invoke()`

### Parameters
#### Request Body
- **query** (string) - Required - The user's query or input to the agent.
- Other key-value pairs can be passed as part of the input dictionary.

### Request Example
```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.chat import ChatService
from hiagent_components.agent.base import Agent

load_dotenv()

svc = ChatService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_AGENT_APP_KEY")

agent = Agent.init(
    svc=svc,
    app_key=APP_KEY,
    user_id="user-42",
    variables={"name": "weather_assistant"},
)
answer = agent.invoke({"query": "Is it going to rain in Beijing tomorrow?"})
print(answer)
```

### Response
#### Success Response (200)
- **answer** (string) - The full text response from the agent.
```

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

### Agent Invoke (Asynchronous)

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Interacts with a conversational agent asynchronously to get a response.

```APIDOC
## Agent Invoke (Asynchronous)

### Description
This method allows for asynchronous invocation of an Agent, sending a query and receiving a full text response without blocking the execution thread.

### Method
`agent.ainvoke()`

### Parameters
#### Request Body
- **query** (string) - Required - The user's query or input to the agent.
- Other key-value pairs can be passed as part of the input dictionary.

### Request Example
```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.chat import ChatService
from hiagent_components.agent.base import Agent

load_dotenv()

svc = ChatService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_AGENT_APP_KEY")

async def run_async_agent():
    agent = await Agent.ainit(
        svc=svc,
        app_key=APP_KEY,
        user_id="user-42",
        variables={"name": "weather_assistant"},
    )
    answer = await agent.ainvoke({"query": "What is the UV index today?"})
    print(answer)

asyncio.run(run_async_agent())
```

### Response
#### Success Response (200)
- **answer** (string) - The full text response from the agent.
```

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

### Initialize Agent as a Tool

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes an agent and converts it into a tool for use in agent pipelines. Requires service, app key, and user ID.

```python
agent_tool = Agent.init(
    svc=svc, app_key=APP_KEY, user_id="user-tool",
    variables={\"name\": \"research_agent\"},
)
tool = agent_tool.as_tool()
print("tool name:", tool.name)
print("tool schema:", tool.input_schema)
result = tool.invoke({\"query\": "Latest advances in quantum computing?"})
print(result)
```

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

### start_trace — Context Manager for Manual Spans

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

A context manager providing a clean interface for manually setting span attributes and status codes.

```APIDOC
## start_trace — Context Manager for Manual Spans

### Description
`start_trace` is a context manager that yields a `TracedSpan` wrapper, providing a clean interface for manually setting span attributes and status codes without managing the raw OTel `Span` API.

### Method
```python
from hiagent_observe.helper import start_trace
from hiagent_observe import client
from opentelemetry.trace import StatusCode
import os

provider = client.init(
    trace_endpoint=os.getenv("HIAGENT_TRACE_ENDPOINT"),
    top_endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"),
    ak=os.getenv("VOLC_ACCESSKEY"),
    sk=os.getenv("VOLC_SECRETKEY"),
    workspace_id=os.getenv("WORKSPACE_ID"),
    app_id=os.getenv("CUSTOM_APP_ID"),
)

with start_trace("rag-pipeline", provider=provider) as span:
    span.set_attribute("pipeline.stage", "retrieval")
    # ... do retrieval work ...
    span.set_attributes({
        "retrieval.docs_found": 5,
        "retrieval.top_score": "0.92",
    })
    # On failure:
    # span.set_status(StatusCode.ERROR, "retrieval timeout")
```
```

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

### Initialize HiAgent SDK Services and Agent

Source: https://github.com/volcengine/hiagent-python-sdk/blob/main/README.md

This snippet demonstrates how to initialize various HiAgent services (ToolService, ChatService, KnowledgebaseService) and an Agent. It requires environment variables for endpoint, app base URL, and app key. Ensure these are set before running.

```python
import os

from dotenv import load_dotenv
from hiagent_api.chat import ChatService
from hiagent_api.knowledgebase import KnowledgebaseService
from hiagent_api.tool import ToolService
from hiagent_components.agent import Agent
from hiagent_components.integrations.langchain import LangChainTool
from hiagent_components.retriever import KnowledgeRetriever
from hiagent_components.tool import Tool
from langchain.agents import AgentExecutor, create_structured_chat_agent
from langchain.callbacks import StdOutCallbackHandler
from langchain_openai import ChatOpenAI
from langsmith import Client

load_dotenv()

def get_tool_svc() -> ToolService:
    svc = ToolService(
        endpoint=os.getenv("HIAGENT_TOP_ENDPOINT") or "", region="cn-north-1"
    )
    return svc

def get_chat_svc() -> ChatService:
    svc = ChatService(
        endpoint=os.getenv("HIAGENT_TOP_ENDPOINT") or "", region="cn-north-1"
    )
    svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL") or "")

    return svc

def get_knowledgebase_svc() -> KnowledgebaseService:
    svc = KnowledgebaseService(
        endpoint=os.getenv("HIAGENT_TOP_ENDPOINT") or "", region="cn-north-1"
    )

    return svc

if __name__ == "__main__":
    tool = Tool.init(
        svc=get_tool_svc(),
        workspace_id="cuq0pp9s7366bfl0cns0",
        tool_id="5njoa3j2m2t5cpaotjlg"
    )

    app_key = os.getenv("HIAGENT_AGENT_APP_KEY") or ""
    agent = Agent.init(
        svc=get_chat_svc(),
        app_key=app_key,
        user_id="test",
        variables={"name": "weather_assistant"},
    )

    retriever = KnowledgeRetriever(
        svc=get_knowledgebase_svc(),
        name="knowledge_tool",
        description="knowledge retriever, used to search knowledge about pandas",
        workspace_id="cuq0pp9s7366bfl0cns0",
        dataset_ids=["019613e3-f37b-7b80-8e0a-579435bb9870"],
        top_k=3,
        score_threshold=0.4,
        retrieval_search_method=0,
    )

    ocr_tool = LangChainTool.from_tool(tool)
    agent_tool = LangChainTool.from_tool(agent.as_tool())
    retriever_tool = LangChainTool.from_tool(retriever.as_tool())
    tools = [ocr_tool, agent_tool, retriever_tool]


    # Pull the prompt template from the hub
    # ReAct = Reason and Action
    # https://smith.langchain.com/hub/hwchase17/react
    client = Client()
    prompt = client.pull_prompt("hwchase17/structured-chat-agent")
    prompt.messages[0].prompt.template += "\n\n## Notice\n\n tool's action_input must be json object rather than string"

    callbacks = [StdOutCallbackHandler()]

    # export OPENAI_API_KEY=xxxx
    # Initialize a ChatOpenAI model
    llm = ChatOpenAI(
        model=os.getenv("OPENAI_MODEL"),  # pro
        base_url="https://ark.cn-beijing.volces.com/api/v3",
        callbacks=callbacks,
    )
    agent = create_structured_chat_agent(
        llm=llm,
        tools=tools,
        prompt=prompt,
    )
    # Create an agent executor from the agent and tools
    agent_executor = AgentExecutor.from_agent_and_tools(
        agent=agent,
        tools=tools,
        verbose=False,
        callbacks=callbacks,
    )
    # Run the agent with a test query
    response = agent_executor.invoke(
        {"input": "Is the weather in Shenzhen suitable for going out today?"},
    )

    # Print the response from the agent
    print("response:", response)
```

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

### Manual Span Creation with start_trace Context Manager

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Provides a clean interface for manually setting span attributes and status codes without directly using the raw OTel Span API.

```python
from hiagent_observe.helper import start_trace
from hiagent_observe import client
from opentelemetry.trace import StatusCode
import os

provider = client.init(
    trace_endpoint=os.getenv("HIAGENT_TRACE_ENDPOINT"),
    top_endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"),
    ak=os.getenv("VOLC_ACCESSKEY"),
    sk=os.getenv("VOLC_SECRETKEY"),
    workspace_id=os.getenv("WORKSPACE_ID"),
    app_id=os.getenv("CUSTOM_APP_ID"),
)

with start_trace("rag-pipeline", provider=provider) as span:
    span.set_attribute("pipeline.stage", "retrieval")
    # ... do retrieval work ...
    span.set_attributes({
        "retrieval.docs_found": 5,
        "retrieval.top_score": "0.92",
    })
    # On failure:
    # span.set_status(StatusCode.ERROR, "retrieval timeout")
```

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

### Initialize and Use Knowledge Retriever Components

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes specialized retriever components for knowledge retrieval. Supports direct invocation, asynchronous operations, and conversion to agent tools. Requires service, workspace ID, and dataset IDs.

```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.knowledgebase import KnowledgebaseService
from hiagent_components.retriever.base import KnowledgeRetriever, QARetriever

load_dotenv()

svc = KnowledgebaseService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))

retriever = KnowledgeRetriever(
    svc=svc,
    name="panda_knowledge",
    description="Retrieve facts about giant pandas",
    workspace_id=os.getenv("WORKSPACE_ID"),
    dataset_ids=["019613e3-f37b-7b80-8e0a-579435bb9870"],
    top_k=5,
    score_threshold=0.4,
    retrieval_search_method=0,  # 0=semantic, 1=full-text, 2=hybrid
)

# --- Direct invocation ---
result = retriever.invoke({"query": "giant panda diet"})
for doc in result.docs:
    print(f"[{doc.score:.3f}] {doc.content[:100]}")

# --- Async ---
async def run():
    result = await retriever.ainvoke({"query": "panda conservation"})
    for doc in result.docs:
        print(doc.content[:80])
asyncio.run(run())

# --- Convert to tool for agent use ---
tool = retriever.as_tool()
print("schema:", tool.input_schema)
tool_result = tool.invoke({"query": "panda habitat"})
print(tool_tool_result)
```

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

### Client.init / Client — AI Evaluation Client

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes the AI Evaluation Client, which orchestrates the complete evaluation lifecycle including task creation, inference, and result submission.

```APIDOC
## hiagent-eva

### `client.init` / `Client` — AI Evaluation Client

The `hiagent-eva` package provides a `Client` class that orchestrates the complete evaluation lifecycle: creating tasks, fetching dataset conversations, running inference via a user-provided function, submitting results, and retrieving evaluation reports.

```python
import os, json
from typing import List
from dotenv import load_dotenv
from hiagent_api import eva_types
from hiagent_eva import client

load_dotenv()

# --- Initialize ---
euro_client = client.init(
    endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"),
    ak=os.getenv("VOLC_ACCESSKEY"),
    sk=os.getenv("VOLC_SECRETKEY"),
    workspace_id=os.getenv("WORKSPACE_ID"),
    app_id=os.getenv("CUSTOM_APP_ID"),
)

# --- Define your inference function ---
def my_inference(case_data_list: List[eva_types.CaseData]) -> List[eva_types.InferenceResult]:
    results = []
    for case in case_data_list:
        # case["input"].Text contains the user input text
        user_input = case["input"].Text or ""
        answer = f"Echo: {user_input}"  # replace with your model call
        results.append(eva_types.InferenceResult(
            Content=answer,
            CostTokens=50,
            TTFT=200,  # time to first token in ms
        ))
    return results

# --- Run full inference + evaluation pipeline ---
report = eva_client.run_inference_and_evaluation(
    dataset_id="ds-abc123",
    dataset_version_id="v1",
    task_name="my-eval-task-001",
    inference_function=my_inference,
    ruleset_id="rs-xyz456",      # use None + rule_params for custom rules
    max_conversations=100,
)

print("Created at:", report.CreatedAt)
for target in (report.Targets or []):
    print(f"Target {target.TargetID}: avg_tokens={target.AvgCostTokens}, avg_ttft={target.AvgTTFT}ms")
for rule in (report.Rules or []):
    for rt in rule.Targets:
        print(f"Rule {rule.RuleID} / {rt.TargetDetail.TargetName}: avg_score={rt.AvgScore}, pct={rt.Percent}%")
```
```

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

### Run Full Inference and Evaluation Pipeline

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Executes the complete AI evaluation pipeline, including running inference with a provided function and evaluating against a specified dataset and ruleset. Requires an initialized eva_client.

```python
from hiagent_api import eva_types

# Assuming eva_client and my_inference are defined elsewhere
# --- Run full inference + evaluation pipeline ---
report = eva_client.run_inference_and_evaluation(
    dataset_id="ds-abc123",
    dataset_version_id="v1",
    task_name="my-eval-task-001",
    inference_function=my_inference,
    ruleset_id="rs-xyz456",      # use None + rule_params for custom rules
    max_conversations=100,
)

print("Created at:", report.CreatedAt)
for target in (report.Targets or []):
    print(f"Target {target.TargetID}: avg_tokens={target.AvgCostTokens}, avg_ttft={target.AvgTTFT}ms")
for rule in (report.Rules or []):
    for rt in rule.Targets:
        print(f"Rule {rule.RuleID} / {rt.TargetDetail.TargetName}: avg_score={rt.AvgScore}, pct={rt.Percent}%")

```

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

### Initialize HiAgent Components and LangChain Agent

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes HiAgent tools, agents, and knowledge retrievers, then wraps them as LangChain tools to build and execute a ReAct agent.

```python
from volcengine.hiagent.tool import Tool, Agent, KnowledgeRetriever
from langchain_volcengine.tools import LangChainTool
from langchain_openai import ChatOpenAI
from langchain.agents import create_structured_chat_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
from volcengine.client import Client
import os

# Assume svc, chat_svc, kb_svc are initialized elsewhere
# Example initialization (replace with actual service objects):
class MockService:
    pass
tool_svc = MockService()
chat_svc = MockService()
kb_svc = MockService()

# Build HiAgent components
ha_tool = Tool.init(svc=tool_svc, workspace_id=os.getenv("WORKSPACE_ID"), tool_id="TOOL_ID")
ha_agent = Agent.init(svc=chat_svc, app_key=os.getenv("HIAGENT_AGENT_APP_KEY"),
                      user_id="lc-user", variables={})
ha_retriever = KnowledgeRetriever(
    svc=kb_svc, name="kb", description="Company knowledge base",
    workspace_id=os.getenv("WORKSPACE_ID"),
    dataset_ids=["DATASET_ID"], top_k=3, score_threshold=0.4,
)

# Wrap as LangChain tools
lc_tools = [
    LangChainTool.from_tool(ha_tool),
    LangChainTool.from_tool(ha_agent.as_tool()),
    LangChainTool.from_tool(ha_retriever.as_tool()),
]

# Build a LangChain ReAct agent
llm = ChatOpenAI(model=os.getenv("OPENAI_MODEL"),
                 base_url="https://ark.cn-beijing.volces.com/api/v3")
# Assuming Client().pull_prompt is available and returns a prompt template
# Example placeholder for prompt:
class MockPromptTemplate:
    def __init__(self, template):
        self.template = template

# Mocking the pull_prompt call
class MockClient:
    def pull_prompt(self, name):
        return ChatPromptTemplate.from_template("A mock prompt template for {input}")

client_instance = MockClient()
prompt = client_instance.pull_prompt("hwchase17/structured-chat-agent")

agent = create_structured_chat_agent(llm=llm, tools=lc_tools, prompt=prompt)
executor = AgentExecutor.from_agent_and_tools(agent=agent, tools=lc_tools, verbose=True)

response = executor.invoke({"input": "What is the weather in Shenzhen today?"})
print(response["output"])

```

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

### Initialize and Use Tool Component

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes a Tool component for synchronous and asynchronous operations. Requires service, workspace ID, and tool ID. Supports credential injection for OAuth tools.

```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.tool import ToolService
from hiagent_components.tool.tool import Tool

load_dotenv()

svc = ToolService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))

WORKSPACE_ID = os.getenv("WORKSPACE_ID")
TOOL_ID = "rgnadh3poolns0v5sa10"  # e.g. arxiv search tool

# --- Synchronous ---
tool = Tool.init(svc=svc, workspace_id=WORKSPACE_ID, tool_id=TOOL_ID)
print("name:", tool.name)
print("schema:", tool.input_schema)
output = tool.invoke(input={"query": "large language models"})
print("result:", output)

# --- Async ---
async def run_async_tool():
    tool = await Tool.ainit(svc=svc, workspace_id=WORKSPACE_ID, tool_id=TOOL_ID)
    output = await tool.ainvoke(input={"query": "reinforcement learning"})
    print("async result:", output)

asyncio.run(run_async_tool())

# --- With credentials (for OAuth tools) ---
cred_tool = Tool.init(
    svc=svc,
    workspace_id=WORKSPACE_ID,
    tool_id="some-oauth-tool-id",
    credentials={"api_key": "sk-xxxx"},
)
output = cred_tool.invoke(input={"url": "https://example.com"})
print(output)
```

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

### client.init — Initialize OpenTelemetry Tracing

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Configures an OpenTelemetry TracerProvider to export spans via HTTP/protobuf to the HiAgent trace backend, handling token-based authentication.

```APIDOC
## client.init — Initialize OpenTelemetry Tracing

### Description
`hiagent_observe.client.init` configures an OpenTelemetry `TracerProvider` that exports spans via HTTP/protobuf to the HiAgent trace backend. It handles token-based authentication automatically, refreshing credentials every hour via the HiAgent Observe API.

### Method
```python
import os, time
from dotenv import load_dotenv
from hiagent_observe import client
from opentelemetry import trace

load_dotenv()

provider = client.init(
    trace_endpoint=os.getenv("HIAGENT_TRACE_ENDPOINT"),  # e.g. "https://trace.hiagent.example.com"
    top_endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"),
    ak=os.getenv("VOLC_ACCESSKEY"),
    sk=os.getenv("VOLC_SECRETKEY"),
    workspace_id=os.getenv("WORKSPACE_ID"),
    app_id=os.getenv("CUSTOM_APP_ID"),
)

tracer = trace.get_tracer("my-service")

# --- Manual span instrumentation ---
with tracer.start_as_current_span("handle-request") as root:
    root.set_attribute("http.method", "POST")
    root.set_attribute("user.id", "user-001")
    with tracer.start_as_current_span("call-llm") as span:
        span.set_attribute("llm.model", "doubao-pro-4k")
        span.set_attribute("llm.prompt_tokens", 128)
        time.sleep(0.1)  # simulate LLM call
        span.set_attribute("llm.completion_tokens", 64)
print("trace exported")
```
```

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

### Run Workflow Synchronously

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Executes a workflow synchronously and prints the status and output. Requires setting up endpoint, AK/SK, app base URL, and app key. Input data should be a JSON string.

```python
import os, json, asyncio
from hiagent_api.workflow import WorkflowService
from hiagent_api.workflow_types import (
    GetWorkflowRequest, RunWorkflowRequest, QueryWorkflowStatusRequest,
)

svc = WorkflowService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_APP_KEY")

# --- Synchronous blocking run ---
resp = svc.run_workflow(
    APP_KEY,
    RunWorkflowRequest(
        input_data=json.dumps({"query": "Summarize today's news"}),
        user_id="user-001",
        app_key=APP_KEY,
        no_debug=True,
    ),
)
print("status:", resp.status, "output:", resp.output)
```

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

### Initialize HiAgent AI Evaluation Client

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initializes the AI evaluation client using provided endpoint, credentials, and workspace information. This client orchestrates the full evaluation lifecycle.

```python
import os, json
from typing import List
from dotenv import load_dotenv
from hiagent_api import eva_types
from hiagent_eva import client

load_dotenv()

# --- Initialize ---
euro_client = client.init(
    endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"),
    ak=os.getenv("VOLC_ACCESSKEY"),
    sk=os.getenv("VOLC_SECRETKEY"),
    workspace_id=os.getenv("WORKSPACE_ID"),
    app_id=os.getenv("CUSTOM_APP_ID"),
)

```

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

### Initialize OpenTelemetry Client for HiAgent

Source: https://github.com/volcengine/hiagent-python-sdk/blob/main/libs/observe/README.md

Initializes the OpenTelemetry client with HiAgent endpoints and authentication headers. The authentication headers are refreshed hourly. Ensure all required environment variables are set.

```python
import os
import time

from dotenv import load_dotenv
from hiagent_observe import client
from opentelemetry import trace

load_dotenv()


if __name__ == "__main__":
  try:
    # Initialize OpenTelemetry Client, and inject authentication headers
    # Authentication headers are refreshed every hour
    client.init(
      # Configure to HiAgent's OpenTelemetry Endpoint
      trace_endpoint=os.getenv("HIAGENT_TRACE_ENDPOINT"),
      # Configure to HiAgent's Top Endpoint
      top_endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"),
      # Configure to the access key obtained from HiAgent's personal center
      ak=os.getenv("VOLC_ACCESSKEY"),
      # Configure to the secret key obtained from HiAgent's personal center
      sk=os.getenv("VOLC_SECRETKEY"),
      # Configure to the workspace ID of HiAgent's custom application
      workspace_id=os.getenv("WORKSPACE_ID"),
      # Configure to the app ID of HiAgent's custom application
      app_id=os.getenv("CUSTOM_APP_ID"),
    )
  except Exception as e:
    raise RuntimeError(e)

  tracer = trace.get_tracer("example-tracer") # Create a Tracer

  for i in range(100000):
    with tracer.start_as_current_span("main-operation") as root_span:
      with tracer.start_as_current_span("do-work") as span:
        span.set_attributes(
          {
            "http.method": "GET",
            "http.route": "/api/work",
            "http.status_code": 200,
          }
        )
    print("push trace")
    time.sleep(2)
```

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

### Initialize OpenTelemetry Tracing with HiAgent

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Configures an OpenTelemetry TracerProvider to export spans via HTTP/protobuf to the HiAgent trace backend. Handles token-based authentication and credential refreshing.

```python
import os, time
from dotenv import load_dotenv
from hiagent_observe import client
from opentelemetry import trace

load_dotenv()

provider = client.init(
    trace_endpoint=os.getenv("HIAGENT_TRACE_ENDPOINT"),  # e.g. "https://trace.hiagent.example.com"
    top_endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"),
    ak=os.getenv("VOLC_ACCESSKEY"),
    sk=os.getenv("VOLC_SECRETKEY"),
    workspace_id=os.getenv("WORKSPACE_ID"),
    app_id=os.getenv("CUSTOM_APP_ID"),
)

tracer = trace.get_tracer("my-service")

# --- Manual span instrumentation ---
with tracer.start_as_current_span("handle-request") as root:
    root.set_attribute("http.method", "POST")
    root.set_attribute("user.id", "user-001")
    with tracer.start_as_current_span("call-llm") as span:
        span.set_attribute("llm.model", "doubao-pro-4k")
        span.set_attribute("llm.prompt_tokens", 128)
        time.sleep(0.1)  # simulate LLM call
        span.set_attribute("llm.completion_tokens", 64)
print("trace exported")
```

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

### KnowledgebaseService Query

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Demonstrates how to query the HiAgent knowledge base using the KnowledgebaseService for semantic, full-text, or hybrid retrieval.

```APIDOC
## KnowledgebaseService Query

### Description
This operation allows you to query the HiAgent knowledge base using various retrieval methods.

### Method
`svc.query()`

### Parameters
#### Request Body
- **workspace_id** (string) - Required - The ID of the workspace.
- **dataset_ids** (list of strings) - Required - A list of dataset IDs to query.
- **keywords** (list of strings) - Required - Keywords to use for the query.
- **top_k** (integer) - Optional - The number of top results to return.
- **score_threshold** (float) - Optional - The minimum score threshold for results.
- **retrieval_search_method** (integer) - Optional - The search method (0=semantic, 1=full-text, 2=hybrid).
- **type** (integer) - Optional - The type of content to retrieve (1=knowledge, 2=QA, 3=terminology).

### Request Example
```python
from hiagent_api.knowledgebase import KnowledgebaseService
from hiagent_api.knowledgebase_types import QueryRequest

svc = KnowledgebaseService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))

resp = svc.query(
    QueryRequest(
        workspace_id=os.getenv("WORKSPACE_ID"),
        dataset_ids=["019613e3-f37b-7b80-8e0a-579435bb9870"],
        keywords=["giant panda habitat"],
        top_k=3,
        score_threshold=0.4,
        retrieval_search_method=0,
        type=1,
    )
)
```

### Response
#### Success Response (200)
- **docs** (list of objects) - A list of document objects, each containing:
  - **content** (string) - The content of the document.
  - **score** (float) - The relevance score of the document.
```

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

### Query Knowledge Base

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Use KnowledgebaseService for semantic, full-text, or hybrid retrieval from knowledge base datasets. Requires setting up endpoint, AK/SK, and providing dataset IDs and keywords. Retrieval parameters like top_k and score_threshold can be adjusted.

```python
import os
from hiagent_api.knowledgebase import KnowledgebaseService
from hiagent_api.knowledgebase_types import QueryRequest

svc = KnowledgebaseService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))

resp = svc.query(
    QueryRequest(
        workspace_id=os.getenv("WORKSPACE_ID"),
        dataset_ids=["019613e3-f37b-7b80-8e0a-579435bb9870"],
        keywords=["giant panda habitat"],
        top_k=3,
        score_threshold=0.4,
        retrieval_search_method=0,  # 0=semantic, 1=full-text, 2=hybrid
        type=1,                     # 1=knowledge, 2=QA, 3=terminology
    )
)
for doc in resp.docs:
    print(doc.content, doc.score)
```

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

### MCP Tool Integration

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

This section demonstrates how to wrap MCP server tools as HiAgent BaseTools, enabling them to be invoked through the HiAgent interface.

```APIDOC
## MCP Tool Integration

`hiagent_components.integrations.mcp.tool` bridges the Model Context Protocol (MCP) server tools into the HiAgent tool interface, allowing MCP-enabled tool servers to be invoked through the same `BaseTool` interface.

```python
import os, asyncio
from dotenv import load_dotenv
from hiagent_api.tool import ToolService
from hiagent_components.integrations.mcp.tool import MCPTool  # requires mcp extra

load_dotenv()

async def run_mcp():
    # MCPTool wraps an MCP server's tool as a HiAgent BaseTool
    mcp_tool = await MCPTool.ainit(
        server_url="http://localhost:8080",  # MCP server endpoint
        tool_name="get_current_time",
    )
    print("name:", mcp_tool.name)
    print("schema:", mcp_tool.input_schema)
    result = await mcp_tool.ainvoke(input={"timezone": "America/New_York"})
    print("result:", result)

asyncio.run(run_mcp())
```
```

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

### Integrate HiAgent Components with LangChain

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Converts HiAgent components (Tool, Agent.as_tool, KnowledgeRetriever.as_tool) into LangChain StructuredTools. This enables their use within LangChain agents and chains. Requires setting up HiAgent services and LangChain components.

```python
import os
from dotenv import load_dotenv
from langchain.agents import AgentExecutor, create_structured_chat_agent
from langchain_openai import ChatOpenAI
from langsmith import Client

from hiagent_api.chat import ChatService
from hiagent_api.tool import ToolService
from hiagent_api.knowledgebase import KnowledgebaseService
from hiagent_components.agent.base import Agent
from hiagent_components.tool.tool import Tool
from hiagent_components.retriever.base import KnowledgeRetriever
from hiagent_components.integrations.langchain import LangChainTool

load_dotenv()

chat_svc = ChatService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
chat_svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
chat_svc.set_sk(os.getenv("VOLC_SECRETKEY"))
chat_svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

tool_svc = ToolService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
tool_svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
tool_svc.set_sk(os.getenv("VOLC_SECRETKEY"))

kb_svc = KnowledgebaseService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
kb_svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
kb_svc.set_sk(os.getenv("VOLC_SECRETKEY"))

```

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

### Client.create_task — Create Evaluation Task

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Creates a new evaluation task for a dataset version with a specified ruleset. The task can be configured to run immediately or be created without running.

```APIDOC
### `Client.create_task` — Create Evaluation Task

`create_task` creates a new evaluation task against a dataset version with a specified ruleset, optionally running immediately. It automatically builds the target configuration from the `app_id` provided at init.

```python
task_resp = eva_client.create_task(
    dataset_id="ds-abc123",
    dataset_version_id="v1",
    task_name="baseline-eval",
    ruleset_id="rs-xyz456",
    description="Baseline evaluation for Q1",
    run_immediately=False,  # create without running immediately
)
print("task_id:", task_resp.TaskID)
```
```

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

### Create an AI Evaluation Task

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Creates a new AI evaluation task against a specific dataset version and ruleset. The task can be configured to run immediately or created without running.

```python
task_resp = eva_client.create_task(
    dataset_id="ds-abc123",
    dataset_version_id="v1",
    task_name="baseline-eval",
    ruleset_id="rs-xyz456",
    description="Baseline evaluation for Q1",
    run_immediately=False,  # create without running immediately
)
print("task_id:", task_resp.TaskID)

```

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

### Manage Evaluation Tasks (Pause, Re-run, Delete)

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Provides methods for lifecycle management of evaluation tasks, including pausing, re-running evaluations, and deleting tasks.

```python
# Pause a running task
eva_client.pause_task(task_name="my-eval-task-001")

# Re-run only the rule evaluation (inference results already submitted)
report = eva_client.run_evaluation(task_name="my-eval-task-001")
print("re-evaluation report:", report.CreatedAt)

# Delete a task
eva_client.delete_task(task_name="my-eval-task-001")
```

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

### WorkflowService Run Workflow (Synchronous)

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Executes a workflow synchronously and returns the result immediately.

```APIDOC
## WorkflowService Run Workflow (Synchronous)

### Description
This operation runs a workflow synchronously, blocking until the workflow completes and returns its output.

### Method
`svc.run_workflow()`

### Parameters
#### Path Parameters
- **app_key** (string) - Required - The application key for the workflow.

#### Request Body
- **input_data** (string) - Required - JSON string representing the input data for the workflow.
- **user_id** (string) - Required - The ID of the user initiating the workflow.
- **app_key** (string) - Required - The application key.
- **no_debug** (boolean) - Optional - If true, disables debug mode.

### Request Example
```python
import os, json
from hiagent_api.workflow import WorkflowService
from hiagent_api.workflow_types import RunWorkflowRequest

svc = WorkflowService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_APP_KEY")

resp = svc.run_workflow(
    APP_KEY,
    RunWorkflowRequest(
        input_data=json.dumps({"query": "Summarize today's news"}),
        user_id="user-001",
        app_key=APP_KEY,
        no_debug=True,
    ),
)
```

### Response
#### Success Response (200)
- **status** (string) - The status of the workflow run.
- **output** (string) - The output of the workflow.
```

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

### Client.get_task_report

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Fetches the evaluation report for a completed task. Includes built-in retry logic.

```APIDOC
## Client.get_task_report — Get Evaluation Report

### Description
Fetches the evaluation report for a completed task. It uses a built-in tenacity retry decorator (3 attempts, 1-second intervals).

### Method
```python
report = eva_client.get_task_report(task_id="task-id-here")
print("rules:", [r.RuleID for r in (report.Rules or [])])
print("targets:", [t.TargetID for t in (report.Targets or [])])
```
```

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

### WorkflowService Run Workflow (Asynchronous)

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Initiates an asynchronous workflow run and allows for status polling.

```APIDOC
## WorkflowService Run Workflow (Asynchronous)

### Description
This operation starts a workflow asynchronously and returns a run ID. You can then poll for the status and output of the workflow using its run ID.

### Method
`svc.arun_workflow_async()` and `svc.aquery_workflow_status()`

### Parameters for `arun_workflow_async`
#### Path Parameters
- **app_key** (string) - Required - The application key for the workflow.

#### Request Body for `arun_workflow_async`
- **input_data** (string) - Required - JSON string representing the input data for the workflow.
- **user_id** (string) - Required - The ID of the user initiating the workflow.
- **app_key** (string) - Required - The application key.
- **no_debug** (boolean) - Optional - If true, disables debug mode.

### Parameters for `aquery_workflow_status`
#### Path Parameters
- **app_key** (string) - Required - The application key.

#### Request Body for `aquery_workflow_status`
- **app_key** (string) - Required - The application key.
- **user_id** (string) - Required - The ID of the user.
- **run_id** (string) - Required - The ID of the workflow run to query.

### Request Example
```python
import os, json, time, asyncio
from hiagent_api.workflow import WorkflowService
from hiagent_api.workflow_types import RunWorkflowRequest, QueryWorkflowStatusRequest

svc = WorkflowService(endpoint=os.getenv("HIAGENT_TOP_ENDPOINT"), region="cn-north-1")
svc.set_ak(os.getenv("VOLC_ACCESSKEY"))
svc.set_sk(os.getenv("VOLC_SECRETKEY"))
svc.set_app_base_url(os.getenv("HIAGENT_APP_BASE_URL"))

APP_KEY = os.getenv("HIAGENT_APP_KEY")

async def run_async():
    async_resp = await svc.arun_workflow_async(
        APP_KEY,
        RunWorkflowRequest(
            input_data=json.dumps({"query": "Translate to English"}),
            user_id="user-001",
            app_key=APP_KEY,
            no_debug=True,
        ),
    )
    run_id = async_resp.run_id
    print("started run_id:", run_id)

    while True:
        status_resp = await svc.aquery_workflow_status(
            APP_KEY,
            QueryWorkflowStatusRequest(app_key=APP_KEY, user_id="user-001", run_id=run_id),
        )
        if status_resp.status in ("succeed", "failed"):
            print("final status:", status_resp.status)
            print("output:", status_resp.output)
            break
        time.sleep(1)

asyncio.run(run_async())
```

### Response
#### Success Response (200) for `arun_workflow_async`
- **run_id** (string) - The ID of the asynchronous workflow run.

#### Success Response (200) for `aquery_workflow_status`
- **status** (string) - The current status of the workflow run.
- **output** (string) - The output of the workflow if completed.
```

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

### Client.pause_task / Client.delete_task / Client.run_evaluation

Source: https://context7.com/volcengine/hiagent-python-sdk/llms.txt

Lifecycle management methods for evaluation tasks: pause, delete, or re-run rule evaluation.

```APIDOC
## Client.pause_task / Client.delete_task / Client.run_evaluation

### Description
Lifecycle management methods for evaluation tasks — pause a running task, delete it, or re-run only the rule evaluation phase on previously-submitted inference results.

### Methods
```python
# Pause a running task
eva_client.pause_task(task_name="my-eval-task-001")

# Re-run only the rule evaluation (inference results already submitted)
report = eva_client.run_evaluation(task_name="my-eval-task-001")
print("re-evaluation report:", report.CreatedAt)

# Delete a task
eva_client.delete_task(task_name="my-eval-task-001")
```
```