Skip to main content

Run Agent | SVAHNAR AI Developer Docs

To execute the agents you deployed, you can use 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

Agent Access Control (only for Teams and Enterprise plans): If you are using the Teams or Enterprise plan, you can set up access control for your agents. This allows you to restrict access to specific users or groups within your organization. You can manage access control settings through the SVAHNAR Platform.

Basic Execution (Without History)​

Use this for single-turn tasks where context from previous messages is not required.

Python
from svahnar import Svahnar

client = Svahnar()
response = client.agents.run(
    agent_id="b06b8e39-51a7-4b6a-8474-e6340a6b9fa6",
    message="Tell me about Stargate Project"
)
print(response)

Request Parameters​

  • agent_id: The unique identifier of the agent you want to execute. This ID is assigned when you create the agent.
  • 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. If not provided, a new UUID will be generated automatically.
  • hitl_decision: Optional. The Human-in-the-Loop decision. Accepts "approve", "edit", or "reject". Required when resuming an agent that was paused for HITL.

Response​

json
{
    "response": [
        {
            "supervisor_agent_1": {
                "reasoning": "Determined that search tool is needed.",
                "toolcalls": [
                    {
                        "name": "Web_Search_Agent",
                        "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": "supervisor_agent_1",
                "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"
    }
}
info

The response may vary based on the agent's configuration and the input message provided. The example above is a sample output to illustrate the structure of the response. The actual content and the credits consumed may differ based on the agent's functionality and the input message.

Response Parameters​

  • response: A list containing dictionaries for each agent execution step. Each step includes reasoning, toolcalls, toolresponse, llmresponse, and hitl state.
  • usage: Information about the credits charged for the agent execution, including details about each agent involved in the process and the total credits consumed.
  • additional_metadata: Contains metadata like the thread_id to continue the conversation.
  • request_metadata: Contains the unique request_id.

Human-in-the-Loop (HITL) Handling​

When an agent attempts to execute a tool configured with Human-In-The-Loop (hitl: true), it pauses execution. The API will return an immediate response where the hitl field contains the tool call details awaiting approval.

To resume the agent's execution, you must send the same request back to the /run 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 the message field.
  • "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

client = Svahnar()

# 1. Initial Request
response = client.agents.run(
    agent_id="b06b8e39-51a7-4b6a-8474-e6340a6b9fa6",
    message="Search for recent news about AI",
    thread_id="my-unique-session-id"
)

# 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.run(
    agent_id="b06b8e39-51a7-4b6a-8474-e6340a6b9fa6",
    message=None,                              # Message is not needed when approving/rejecting
    thread_id="my-unique-session-id",          # Must use the exact same thread_id
    hitl_decision="approve"                    # The HITL decision
)

print(resume_response)

# OR: Resuming with an edit (providing new arguments)
edit_response = client.agents.run(
    agent_id="b06b8e39-51a7-4b6a-8474-e6340a6b9fa6",
    message={"query": "Latest breakthroughs in Quantum Computing"}, # The edited tool arguments
    thread_id="my-unique-session-id",
    hitl_decision="edit"
)