Test Agent | SVAHNAR AI Developer Docs
You can tempororily test the functionality of an agent using the following code. This API allows you to run a specific agent and perform its designated tasks. You can also specify the input data for the agent to process.
info
When working with complex agent configurations:
- The process of building and responding may require additional time
- Use the timeout parameter to accommodate longer processing times
- Adjust the timeout value as needed based on your configuration complexity
With YAML file
You can test the agent using a YAML file. This is useful for testing complex agents in a single YAML file.
Python
from svahnar import Svahnar
from pathlib import Path
client = Svahnar()
response = client.agents.test(
yaml_file=Path("agent.yaml"),
message="Tell me about the Stargate Project",
timeout=600 # 5 minutes
)
print(response)
With Chat History
When you need to test how the agent handles follow-up questions or context, provide the agent_history.
tip
You can learn how to generate the chat history object automatically or manually in the Chat History Guide.
Python
from svahnar import Svahnar
from pathlib import Path
client = Svahnar()
# Example pre-existing history
history = [
{"role": "user", "content": "Who is the CEO of OpenAI?"},
{"role": "assistant", "content": "information search agent - Sam Altman is the CEO of OpenAI."}
]
response = client.agents.test(
yaml_file=Path("agent.yaml"),
message="How old is he?",
agent_history=history,
timeout=600
)
print(response)
With YAML string
You can use a YAML string to test the agent. This is useful for quick tests or when you don't want to create a separate YAML file.
Python
from svahnar import Svahnar
client = Svahnar()
response = client.agents.test(
yaml_string="""create_agent_network:
agent-1:
agent_name: information search agent
agent_function:
- It is used to search for the information on web or internet and provide the result
LLM_config:
params:
model: gpt-5-mini
max_tokens: 1000
request_timeout: 600
tools:
tool_assigned:
- name: Tavily
incoming_edge:
- Start
outgoing_edge: []
""",
message="Tell me about the Stargate Project",
timeout=600 # Adjusted timeout for processing
)
print(response)
Request Parameters
yaml_file: The YAML configuration file you want to upload. (Provide eitheryaml_fileoryaml_string).yaml_string: The YAML configuration string that defines the agent's context and settings. (Provide eitheryaml_fileoryaml_string).message: The input data or message you want to send to the agent for processing. Can be a string or a JSON dictionary.agent_history: Optional. List of prior messages; defaults to an empty list.thread_id: Optional. A unique identifier for the chat session.hitl_decision: Optional. The Human-in-the-Loop decision. Accepts"approve","edit", or"reject". Required when resuming an agent that was paused for HITL.timeout: The maximum time (in seconds) to wait for the agent to respond. This is useful for complex agents that may take longer to process.
Response
The response format is identical to the standard agent execution.
json
{
"response": [
{
"information_search_agent": {
"reasoning": "Determined that search tool is needed.",
"toolcalls": [
{
"name": "Tavily",
"arguments": {"query": "Stargate Project"},
"id": "call_abc123"
}
],
"toolresponse": ["Search results..."],
"llmresponse": "The Stargate Project was a secret U.S. Army unit...",
"hitl": null
}
}
],
"usage": {
"credits_charged": [
{
"agent_name": "information_search_agent",
"number_of_runs": 1,
"credit_consumed": 1
}
],
"total_credits_charged": 1
},
"additional_metadata": {
"thread_id": "000000-00000-00000-00000"
},
"request_metadata": {
"request_id": "req_123456"
}
}
Response Parameters
response: A list containing dictionaries for each agent execution step. Each step includesreasoning,toolcalls,toolresponse,llmresponse, andhitlstate.usage: Information about the credits charged for the agent execution.additional_metadata: Contains metadata like thethread_idto continue the conversation.request_metadata: Contains the uniquerequest_id.
Human-in-the-Loop (HITL) Handling
When testing an agent configured with Human-In-The-Loop (hitl: true), the execution will pause when the tool is called. The API will return a response where the hitl field contains the tool call details awaiting approval.
To resume the agent's execution, you must send the same request (including the YAML file/string) back to the /test endpoint, but include the hitl_decision parameter:
"approve": Allow the agent to execute the tool with the originally proposed arguments."edit": Allow execution, but use the modified arguments you provide in themessagefield."reject": Deny the tool execution. The agent receives feedback that the tool was denied and will attempt to proceed without it.
Example: Resuming after HITL Pause
Python
from svahnar import Svahnar
from pathlib import Path
client = Svahnar()
yaml_path = Path("agent.yaml")
# 1. Initial Request
response = client.agents.test(
yaml_file=yaml_path,
message="Tell me about the Stargate Project",
thread_id="my-test-session-123",
timeout=600
)
# Suppose the agent pauses here and returns hitl data in the response.
# You inspect the tool call and decide to approve it.
# 2. Resuming the agent with an approval
resume_response = client.agents.test(
yaml_file=yaml_path, # Must provide the exact same YAML
message=None, # Message is not needed when approving/rejecting
thread_id="my-test-session-123", # Must use the exact same thread_id
timeout=600,
hitl_decision="approve" # The HITL decision
)
print(resume_response)
# OR: Resuming with an edit (providing new arguments)
edit_response = client.agents.test(
yaml_file=yaml_path,
message={"query": "Declassified UFO documents"}, # The edited tool arguments
thread_id="my-test-session-123",
timeout=600,
hitl_decision="edit"
)