agents

Documentation

Overview

Package agents is the resource module for the AI-agent surface that vxcli exposes via `vxcli agent {coding, devops, git, parallel, presets, tool, tools}`.

IMPORTANT: vxcli's agent commands run *client-side* — they read provider credentials (Anthropic / OpenAI / Google / OpenClaw) from the Vault via /api/v2/setup/ai-get-all-credentials and call the provider directly. This package mirrors that pattern, so SDK consumers don't need to vendor a provider client; the SDK reads creds and dispatches.

Each agent kind = a system prompt + a tool set. The kinds enumerated below match vxcli's verbs.

Index

• type Client
  • func (c *Client) Coding(ctx context.Context, task, lang string) (*RunOutput, error)
  • func (c *Client) Devops(ctx context.Context, task string) (*RunOutput, error)
  • func (c *Client) Git(ctx context.Context, task string) (*RunOutput, error)
  • func (c *Client) Parallel(ctx context.Context, preset, task string) (*RunOutput, error)
  • func (c *Client) Presets(ctx context.Context) ([]map[string]interface{}, error)
  • func (c *Client) Run(ctx context.Context, in RunInput) (*RunOutput, error)
  • func (c *Client) Tool(ctx context.Context, name string, args map[string]interface{}) (map[string]interface{}, error)
  • func (c *Client) Tools(ctx context.Context, kind Kind) ([]map[string]interface{}, error)
• type Kind
• type RunInput
• type RunOutput

Types

type Client

type Client struct {
	T              *transport.Transport
	NodeURL        string
	AuthedUsername string
}

Client is the entry point. Construct via:

c.Agents()

func (*Client) Coding

func (c *Client) Coding(ctx context.Context, task, lang string) (*RunOutput, error)

Coding — multi-language code generation. Convenience wrapper over Run.

func (*Client) Devops

func (c *Client) Devops(ctx context.Context, task string) (*RunOutput, error)

Devops — multi-tool DevOps orchestration (git + docker + VM + pipeline).

func (*Client) Git

func (c *Client) Git(ctx context.Context, task string) (*RunOutput, error)

Git — AI-powered git operations.

func (*Client) Parallel

func (c *Client) Parallel(ctx context.Context, preset, task string) (*RunOutput, error)

Parallel runs N sub-agents in parallel using a named preset.

func (*Client) Presets

func (c *Client) Presets(ctx context.Context) ([]map[string]interface{}, error)

Presets returns the available parallel-agent presets, if the server exposes the catalog endpoint.

func (*Client) Run

func (c *Client) Run(ctx context.Context, in RunInput) (*RunOutput, error)

Run dispatches an agent invocation against the platform's agent orchestrator. The platform routes to the appropriate AI provider using credentials stored under /api/v2/setup/ai-*.

Endpoint: POST /api/v2/agents/run (planned; soft-fails today).

func (*Client) Tool

func (c *Client) Tool(ctx context.Context, name string, args map[string]interface{}) (map[string]interface{}, error)

Tool calls a specific tool directly with no LLM in the loop — deterministic, useful in CI scripts.

func (*Client) Tools

func (c *Client) Tools(ctx context.Context, kind Kind) ([]map[string]interface{}, error)

Tools returns the available tools an agent can invoke.

type Kind

type Kind string

Kind enumerates the agent verbs vxcli supports.

const (
	KindCoding   Kind = "coding"
	KindDevops   Kind = "devops"
	KindGit      Kind = "git"
	KindParallel Kind = "parallel"
)

type RunInput

type RunInput struct {
	Kind Kind
	// Task — the user's natural-language request.
	Task string
	// Lang, only used by KindCoding (python / go / ts / terraform / dockerfile / sh).
	Lang string
	// Provider — anthropic | openai | google | openclaw. Empty = first
	// available in the workspace.
	Provider string
	// Model — provider-specific identifier (e.g. claude-opus-4-7).
	Model string
	// Context — extra k/v passed to the agent (file paths, repo state, …).
	Context map[string]string
}

RunInput is the request shape for any agent invocation.

type RunOutput

type RunOutput struct {
	Output   string                 `json:"output"`
	Provider string                 `json:"provider,omitempty"`
	Model    string                 `json:"model,omitempty"`
	Tokens   int                    `json:"tokens,omitempty"`
	Raw      map[string]interface{} `json:"-"`
}

RunOutput is the response envelope every agent invocation returns.