agent

agent is an agent harness with a command-line interface. It provides rudimentary scaffolding around the Agent Harness library in the form of command-line options and JSON settings. Agent transcripts are streamed to standard output and can also be streamed to a web browser with Markdown formatting applied.

Installing libcurl

agent requires libcurl in order to build and run.

Windows

On Windows, you can install libcurl using Microsoft's vcpkg package manager.

For convenience, you can run share\download-libcurl-vcpkg.bat to clone the vcpkg repository, bootstrap it and use it to install libcurl. This will clone vcpkg to the ..\vcpkg directory relative to Plywood's root directory.

macOS

On macOS, libcurl can be installed using the Homebrew package manager. [More details coming soon.]

Linux

On Linux distributions based on apt, such as Debian and Ubuntu, libcurl can be installed using the following command line. For other distributions, follow your package manager's instructions.

$ sudo apt-get install libcurl4-openssl-dev libssl-dev

Building and Running

If CMake and libcurl are both installed, the following command will build and run agent. On Windows, use share\build-app.bat instead.

$ share/build-app.sh agent -r [-c <settings-path>] [-p <provider>] [-m <model>] [-x[=<port>]] [-a] [-l] [-r] [-s] [-b] [prompt]

For example:

$ OPENAI_API_KEY=<key> share/build-app.sh agent -r -p openai "Hello!"

Or, if the app is already built:

$ OPENAI_API_KEY=<key> bin/agent -p openai "Hello!"

Available command-line options:

The -p/--provider option selects an endpoint from a list of known providers. The known provider list is loaded from known-providers.json. The choice of model can be overridden using -m/--model.

The agent reads its API key from the environment variable named by the endpoint's apiKeyEnv property. If this property is NONE, authentication is omitted.

When -x/--proxy is specified, a named provider must be selected in JSON or with -p/--provider. The agent connects to agent-proxy on IPv4 loopback, skips the environment variable lookup and omits authentication. The default port is 8082; pass an inline value such as --proxy=8088 to select a different port.

Configuration

By default, the app searches for a file named agent.json in the current working directory. If none is found, it checks each ancestor directory, loading the first agent.json file it finds.

If -c/--config is specified, the app loads settings from the specified path instead. If the specified path is a directory, the app tries to load agent.json from that directory.

{
    "provider": "openai",
    "systemPrompt": "You are a helpful assistant.",
    "readableDirs": ["../reference"],
    "writableDirs": ["."],
    "tools": [
        "read", "list_dir", "find_in_files", "write", "edit", "shell"
    ],
    "shellAuthorizer": {
        "policy": "The agent may build and run the existing sample applications.",
        "tools": ["read", "list_dir", "find_in_files"]
    }
}

The settings file must contain a single JSON object with these optional properties:

The shellAuthorizer subobject is used to configure a ShellAuthorizationPolicy instance as described in the Agent Harness library. It accepts the following optional properties: