Create an agent

An effective agent starts with a narrow responsibility and a result you can evaluate. Avoid creating a universal assistant with a page of conflicting instructions.

Create the definition

Open Agents and choose Create Agent. Enter a name and purpose that explain the job without internal jargon.

Choose a model, then write instructions that cover:

• the role the agent should play;
• the inputs it can expect;
• the process or constraints it must follow;
• the required output format;
• when it should ask for clarification or stop.

Make structured output enforceable

Instructions describe what you want; an output schema makes the shape machine-checkable. Use the agent's output contract when another app or workflow depends on exact JSON. Guest Machines accepts a bounded, object-rooted JSON Schema Draft 2020-12 profile and rejects an invalid schema when the agent is saved.

For example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "summary": { "type": "string", "minLength": 1 },
    "risk_level": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    }
  },
  "required": ["summary", "risk_level"]
}

List every mandatory field in required. Set additionalProperties to false when undeclared fields must fail; JSON Schema allows them by default. A default value is descriptive only—Guest Machines neither inserts it nor coerces a value to another JSON type.

The model provider may use structured generation to help produce a matching answer. Guest Machines still parses one exact JSON object and validates it against your original schema. A mismatch fails the run. Passing this check proves structure, not factual accuracy or task quality.

Add capabilities deliberately

Assign only the tools and MCP servers needed for the job. Every capability expands what the agent can do and what you need to test and govern.

Knowledge, environment variables, execution limits, network policy, and delegation rules should reflect the same least-privilege approach.

For visual work, assign Generate an Image to create or edit images and save the results as run files. See generate and edit images for model choices, references, and transparent backgrounds.

Choose knowledge access

In the agent editor, open Knowledge Access. Leave Restrict knowledge access off to allow all Knowledge that the agent's existing permissions make visible. This does not grant access to other people's private files.

To limit the sources:

1. Turn on Restrict knowledge access and choose Select Knowledge, or Edit Selection for an existing selection.
2. Use Knowledge source to switch between My Files and Workspace Library. Select files or folders from either source; switching sources keeps your selections.
3. Choose Apply, then save the agent.

A selected folder includes its subfolders and their current and future files, subject to visibility permissions. Selecting individual files keeps the scope narrower. With restrictions on, an empty selection means the agent has no Knowledge access. Turn the restriction off to restore default access.

Selecting a file does not publish it or change who can use it. If a shared file is unpublished, a saved selection does not preserve access for other members. See add knowledge for publishing and storage behavior.

Test the boundary cases

Use a chat to test realistic input, missing information, invalid input, requests outside the agent's role, and every important output-schema boundary. Test a missing required field, a wrong JSON type, an unexpected field when additionalProperties is false, and any formats or limits you rely on. Inspect the run's Result checks when the result is surprising.

Make it reusable

Once the agent is reliable, use it as a pipeline step or team member. Keep its contract narrow enough that another person—or another agent—can predict what it will return.