Class: AgentsID::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/agentsid/client.rb

Overview

AgentsID client -- register agents, validate tokens, manage permissions.

Instance Method Summary collapse

Constructor Details

#initialize(project_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT) ⇒ Client

Returns a new instance of Client.

Parameters:

  • project_key (String) —

    Your AgentsID project key (aid_proj_...)

  • base_url (String) (defaults to: DEFAULT_BASE_URL) —

    AgentsID server URL

  • timeout (Integer) (defaults to: DEFAULT_TIMEOUT) —

    HTTP timeout in seconds

Raises:



18
19
20
21
22
23
24
 
# File 'lib/agentsid/client.rb', line 18

def initialize(project_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
  raise AgentsIDError.new("project_key is required", code: "CONFIG_ERROR") if project_key.nil? || project_key.empty?

  @project_key = project_key
  @base_url = base_url.chomp("/")
  @timeout = timeout
end

Instance Method Details

#check_permission(agent_id, tool, params: nil) ⇒ Hash

Parameters:

  • agent_id (String)
  • tool (String)
  • params (Hash, nil) (defaults to: nil)

Returns:

  • (Hash) 


104
105
106
107
108
109
110
 
# File 'lib/agentsid/client.rb', line 104

def check_permission(agent_id, tool, params: nil)
  request(:post, "/check", {
    agent_id: agent_id,
    tool: tool,
    params: params
  })
end

#get_agent(agent_id) ⇒ Hash

Parameters:

  • agent_id (String)

Returns:

  • (Hash) 


50
51
52
 
# File 'lib/agentsid/client.rb', line 50

def get_agent(agent_id)
  request(:get, "/agents/#{agent_id}")
end

#get_audit_log(agent_id: nil, tool: nil, action: nil, since: nil, limit: 100) ⇒ Hash

Parameters:

  • agent_id (String, nil) (defaults to: nil)
  • tool (String, nil) (defaults to: nil)
  • action (String, nil) (defaults to: nil)
  • since (String, nil) (defaults to: nil) —

    ISO 8601 timestamp

  • limit (Integer) (defaults to: 100)

Returns:

  • (Hash) 


138
139
140
141
142
143
144
145
146
147
 
# File 'lib/agentsid/client.rb', line 138

def get_audit_log(agent_id: nil, tool: nil, action: nil, since: nil, limit: 100)
  params = {}
  params[:agent_id] = agent_id if agent_id
  params[:tool] = tool if tool
  params[:action] = action if action
  params[:since] = since if since
  params[:limit] = limit
  qs = URI.encode_www_form(params)
  request(:get, "/audit/?#{qs}")
end

#get_permissions(agent_id) ⇒ Array<Hash>

Parameters:

  • agent_id (String)

Returns:

  • (Array<Hash>) 


95
96
97
98
 
# File 'lib/agentsid/client.rb', line 95

def get_permissions(agent_id)
  data = request(:get, "/agents/#{agent_id}/permissions")
  data.fetch("rules", [])
end

#list_agents(status: nil, limit: 50) ⇒ Array<Hash>

Parameters:

  • status (String, nil) (defaults to: nil) —

    Filter by status

  • limit (Integer) (defaults to: 50) —

    Max results (default 50)

Returns:

  • (Array<Hash>) 


57
58
59
60
61
62
63
64
 
# File 'lib/agentsid/client.rb', line 57

def list_agents(status: nil, limit: 50)
  params = {}
  params[:status] = status if status
  params[:limit] = limit if limit != 50
  qs = URI.encode_www_form(params)
  path = qs.empty? ? "/agents/" : "/agents/?#{qs}"
  request(:get, path)
end

#register_agent(name:, on_behalf_of:, permissions: nil, ttl_hours: nil, metadata: nil) ⇒ Hash

Register a new agent identity and issue a token.

Parameters:

  • name (String)
  • on_behalf_of (String)
  • permissions (Array<String>, nil) (defaults to: nil)
  • ttl_hours (Integer, nil) (defaults to: nil)
  • metadata (Hash, nil) (defaults to: nil)

Returns:

  • (Hash) 


38
39
40
41
42
43
44
45
46
 
# File 'lib/agentsid/client.rb', line 38

def register_agent(name:, on_behalf_of:, permissions: nil, ttl_hours: nil, metadata: nil)
  request(:post, "/agents/", {
    name: name,
    on_behalf_of: on_behalf_of,
    permissions: permissions,
    ttl_hours: ttl_hours,
    metadata: metadata
  })
end

#revoke_agent(agent_id) ⇒ Hash

Parameters:

  • agent_id (String)

Returns:

  • (Hash) 


68
69
70
 
# File 'lib/agentsid/client.rb', line 68

def revoke_agent(agent_id)
  request(:delete, "/agents/#{agent_id}")
end

#set_permissions(agent_id, rules) ⇒ Hash

Set permission rules for an agent.

Parameters:

  • agent_id (String)
  • rules (Array<Hash>) —

    Each rule: { tool_pattern: "...", action: "allow"|"deny" }

Returns:

  • (Hash) 


81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/agentsid/client.rb', line 81

def set_permissions(agent_id, rules)
  body = rules.map do |r|
    {
      tool_pattern: r[:tool_pattern] || r["tool_pattern"] || r[:toolPattern] || r["toolPattern"] || "",
      action: r[:action] || r["action"] || "allow",
      conditions: r[:conditions] || r["conditions"],
      priority: r[:priority] || r["priority"] || 0
    }
  end
  request(:put, "/agents/#{agent_id}/permissions", body)
end

#validate_token(token, tool: nil, params: nil) ⇒ Hash

Parameters:

  • token (String)
  • tool (String, nil) (defaults to: nil)
  • params (Hash, nil) (defaults to: nil)

Returns:

  • (Hash) 


120
121
122
123
124
125
126
 
# File 'lib/agentsid/client.rb', line 120

def validate_token(token, tool: nil, params: nil)
  request(:post, "/validate", {
    token: token,
    tool: tool,
    params: params
  })
end