Run And Review Your First Agent

After creating your first agent, run one small test before giving it more access.

The goal is not to automate everything immediately. The goal is to confirm that the agent uses the right provider, follows its instructions, requests permission when expected, and only touches the workspace you intended.

Before You Start

Make sure:

• Docker is running.
• The agent has a working provider and model.
• The agent has clear instructions.
• Any folder access was added intentionally.
• Permissions are set conservatively, preferably Ask for Approval.

Send A First Message

Open the agent chat and start with a simple request:

Summarize what you can help me with based on your current configuration.

If you mounted a folder, use a read-only inspection request:

Inspect the mounted project folder and summarize the main areas. Do not modify files.

This gives you a low-risk first run that still exercises the agent configuration.

Handle Permission Prompts

If the agent wants to use a tool, Apprentice may show a permission prompt.

A permission prompt shows what the agent wants to do, such as reading a file, writing a file, running a command, searching files, or using an MCP tool.

Common choices include:

• Allow: approve this request.
• Deny: block this request.
• Always Allow: save a grant pattern for future matching requests.

For a first run, prefer Allow or Deny. Use Always Allow only when the pattern is narrow and you understand what future requests it will approve.

If a permission request is unexpected, deny it and adjust the agent instructions or permissions before trying again.

What To Watch During The Run

Check whether the agent:

• Uses the expected provider and model.
• Follows the role you gave it.
• Stays within the mounted folder.
• Requests permission before sensitive actions.
• Avoids file changes unless you asked for them.
• Gives an answer that matches the task.

If the agent immediately tries to do too much, stop and narrow the instructions or permissions.

Review Activity

After the run, open the agent's Activity view.

Activity has two useful views:

• Timeline: a chronological view of important events.
• Runs: individual agent runs and sessions.

Use Timeline when you want to understand what happened around the agent.

Use Runs when you want to inspect one specific execution.

If a run is queued or currently running, the Activity view can also show queue state for that agent.

Open Run Detail

From the Runs view, open the run detail.

Run detail helps you inspect:

• Trigger type.
• Conversation history.
• Tools used.
• Input tokens.
• Output tokens.
• Estimated cost.
• Duration.
• Runtime events and errors.

This is the best place to debug a first run because it shows more than the final answer.

Decide What To Adjust

After reviewing the run, tune one thing at a time.

Adjust instructions if:

• The answer is too broad.
• The agent misunderstood its job.
• It modified or attempted to modify something too eagerly.
• It did not ask before acting.

Adjust permissions if:

• The agent could not access a folder it needed.
• The agent asked for tools it should never use.
• You want read-only access instead of read-write access.
• You need command or website allow/block rules.

Adjust the provider or model if:

• The response quality is poor.
• The model is too slow.
• The run is too expensive.
• The provider failed or rate-limited.

Adjust budget settings if:

• You are testing a paid API model.
• The agent may run from schedules, tasks, integrations, or webhooks.
• You want a hard stop or warning after a spending limit.

A Good First Run

A good first run usually looks like this:

• The agent answers the simple test request.
• No unexpected tools are used.
• Any permission prompts are understandable.
• The response matches the agent's instructions.
• The Activity and Run Detail views show a clear record of what happened.

Once that works, expand gradually.

Troubleshooting

If the agent does not respond, check that Docker is running and the provider is still connected.

If the model fails, return to Settings > AI Integration and test the provider.

If the agent cannot see files, check the mounted volumes in the agent configuration.

If the agent asks for too many permissions, narrow the prompt or switch to a more restrictive permission mode.

If the agent uses the wrong provider or model, check the agent's model settings and the global default provider.

If the run is expensive, lower the scope, choose a cheaper model, or configure a budget.

Next Step

After the first run works, tune the agent's permissions and folder access.