Python SDK

Use the Python SDK to submit actions, check status, and approve or deny from your agent code.

Installation

Setup

Set your API URL and key (or use a token for self-hosted):

export FARAMESH_URL="https://api.faramesh.io"  # or your Horizon URL
export FARAMESH_API_KEY="your-api-key"        # from the dashboard

export FARAMESH_URL="https://api.faramesh.io"  # or your Horizon URL
export FARAMESH_API_KEY="your-api-key"        # from the dashboard

export FARAMESH_URL="https://api.faramesh.io"  # or your Horizon URL
export FARAMESH_API_KEY="your-api-key"        # from the dashboard

Submit an action

from faramesh.sdk import submit_action

action = submit_action(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"}
)
print(f"Status: {action['status']}, Decision: {action['decision']}")

from faramesh.sdk import submit_action

action = submit_action(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"}
)
print(f"Status: {action['status']}, Decision: {action['decision']}")

from faramesh.sdk import submit_action

action = submit_action(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"}
)
print(f"Status: {action['status']}, Decision: {action['decision']}")

If the policy requires approval, status will be pending_approval and you'll get an approval_token.

List and get actions

from faramesh.sdk import list_actions, get_action

actions = list_actions(status="pending_approval", limit=10)
action = get_action(action_id="...")

from faramesh.sdk import list_actions, get_action

actions = list_actions(status="pending_approval", limit=10)
action = get_action(action_id="...")

from faramesh.sdk import list_actions, get_action

actions = list_actions(status="pending_approval", limit=10)
action = get_action(action_id="...")

Approve or deny

from faramesh.sdk import approve_action, reject_action

approve_action(action_id="...", token="...", reason="Approved")
reject_action(action_id="...", token="...", reason="Rejected")

from faramesh.sdk import approve_action, reject_action

approve_action(action_id="...", token="...", reason="Approved")
reject_action(action_id="...", token="...", reason="Rejected")

from faramesh.sdk import approve_action, reject_action

approve_action(action_id="...", token="...", reason="Approved")
reject_action(action_id="...", token="...", reason="Rejected")

Use the approval_token from the action when status is pending_approval.

Decide-only (no execution)

Ask what the gate would do without creating an action or executing anything:

from faramesh import gate_decide

decision = gate_decide(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"},
    context={}
)
print(decision.outcome)   # "EXECUTE", "ABSTAIN", or "HALT"
print(decision.reason_code, decision.reason)

from faramesh import gate_decide

decision = gate_decide(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"},
    context={}
)
print(decision.outcome)   # "EXECUTE", "ABSTAIN", or "HALT"
print(decision.reason_code, decision.reason)

from faramesh import gate_decide

decision = gate_decide(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"},
    context={}
)
print(decision.outcome)   # "EXECUTE", "ABSTAIN", or "HALT"
print(decision.reason_code, decision.reason)

Use this for pre-checks, tests, or logging "would allow/deny" without side effects.

Execute only if allowed

Run your own executor only when the gate allows:

from faramesh import execute_if_allowed

def my_executor(params):
    # Your tool implementation
    return {"result": "ok"}

result = execute_if_allowed(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"},
    executor=my_executor
)
# If allowed: result contains your executor's return value
# If denied or approval needed: raises or returns error; executor is not called

from faramesh import execute_if_allowed

def my_executor(params):
    # Your tool implementation
    return {"result": "ok"}

result = execute_if_allowed(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"},
    executor=my_executor
)
# If allowed: result contains your executor's return value
# If denied or approval needed: raises or returns error; executor is not called

from faramesh import execute_if_allowed

def my_executor(params):
    # Your tool implementation
    return {"result": "ok"}

result = execute_if_allowed(
    agent_id="my-agent",
    tool="shell",
    operation="exec",
    params={"cmd": "ls -la"},
    executor=my_executor
)
# If allowed: result contains your executor's return value
# If denied or approval needed: raises or returns error; executor is not called

The executor is invoked only when the decision is EXECUTE. Otherwise Faramesh returns the decision (or raises); your code never runs.

Error handling

If the server is unreachable, the SDK may raise or return an error. Handle timeouts and connection errors in your agent (e.g. retry with backoff, or fail closed). Invalid request bodies or auth failures return structured errors; check the response or exception message and code (e.g. invalid_action, unauthorized).

Framework integration

Faramesh has adapters for LangChain, CrewAI, and AutoGen. See Framework Integrations.

Table of content