Getting Started

This walkthrough takes you from an empty tenant to a completed workflow run. Everything below can be done in the Agentfleet app at agentfleet.co.za or via the REST API.

Prerequisites

• An Agentfleet account with the right roles. agentfleet:workflow-author covers resources, tools, steps, workflows and runs; creating an agent also needs agentfleet:identity-admin (or an administrator to create it for you). See roles and personas.
• An MCP server you want to orchestrate against (its base URL and path, e.g. https://api.example.com + /mcp).
• A configured model provider with at least one active model.

1. Register a resource

A resource is an MCP server the platform can call.

1. Go to Build → Resources and choose Create Resource.
2. Enter a name, description, the Base URL, and the Path (e.g. /mcp).
3. Save. Agentfleet automatically registers the resource with the identity provider and binds its audience — tokens issued for this resource are valid only there.

2. Import its tools

1. Open the resource and choose Import Tools.
2. Agentfleet discovers the tools the MCP server advertises and registers each one, including its OAuth scope.
3. Re-import at any time to refresh tool schemas and scopes.

Filtered listings

Discovery asks the MCP server as Agentfleet's own client, not as you. If the server filters its tool listing per caller and expected tools are missing, that client lacks access to them on the server: grant it there, or register the missing tools individually. See Importing.

3. Create an agent

1. Go to Build → Agents and create an agent: a name, description, provider, model and version label. The model must be one the provider offers.
2. Agentfleet registers the agent in the identity provider as a delegated agent with its own confidential client and a per-agent signing key. No client secrets are created or stored — the agent authenticates with short-lived signed assertions.

4. Define steps

A step is a reusable unit of work: a natural-language instruction plus an allowlist of the tools it may call.

1. Go to Build → Steps and create a step of kind Model.
2. Write the instruction — what the step should accomplish and what to return. Be explicit about the success condition; the instruction is the model's contract. Optionally adjust max rounds, the token budget, an output schema, or a model override.
3. Open the step and Add tool for each tool it uses. Leave a tool on Auto, or switch it to Needs confirmation if a person should approve each call before it runs.

Example instruction: "Call MatchAdvisor with the candidate FSP number and name from the run inputs. Return the match verdict and its supporting evidence."

5. Compose and publish a workflow

1. Go to Build → Workflows and choose Create Workflow; name and describe it. A new workflow is Active.
2. Add step for each step, in execution order. These edits change the workflow's draft.
3. In the Versions card, Publish the draft as v1, with optional release notes. Runs execute the latest published version by default, and each run stays pinned to the version it started on.

A workflow that has never been published runs its draft, so you can test before publishing. Once v1 exists, further edits only reach runs after the next publish (or in an explicit draft run). See Draft and published versions.

6. Run it

1. Open the workflow and choose Run.
2. Pick the agent that will execute it.
3. Pick the version: the latest published version (the default), a specific version, or the draft for a test run.
4. Optionally add initial context — key/value inputs visible to the first step. Two keys are reserved: task_id and purpose, which are stamped into every step's delegated token as claims. If the workflow requires a purpose, the run is refused without one.
5. Queue the run. It executes in the background; track it under Run → Workflow instances.

From the API, PUT /api/workflowinstances/run can omit the agent when the workflow's run policy names a default agent (PUT /api/workflows/run-policy). See Launching a run.

7. Inspect the results

Open the run to see:

• State — Running, Waiting (for a confirmation, a clarification or a wait step), Completed, Failed (with reason), or Cancelled.
• Context — every input and every promoted output (toolResult_<n>, modelResponse_<n>) with provenance.
• Summary — steps completed, total tokens, estimated cost, and average model latency.
• Per-step detail — each model call (input/output, tokens, latency, round) and each tool call.
• Purpose & delegation — every token exchange the run made: who delegated, which agent acted, where, and with which scopes.

Next steps

• Understand the identity model — what the delegated token carries and why.
• Learn the reserved run inputs for task- and purpose-bound sessions.
• Add control flow with workflow design: conditions, loops, parallel groups, waits and sub-workflows.
• Automate the workflow — fire it on a schedule, an inbound event or a webhook instead of by hand.
• Guard it with evals — score the workflow against expected cases, compare models, and gate promotion to auto-apply.
• Let people chat with an assistant that uses the same tools and agents.
• Set usage limits on model spend.
• Explore the REST API to queue runs programmatically.