Core concepts

Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see Get started.

Your company contains the records and permissions a connection can use. A person can belong to several companies; an MCP connection acts in the single company selected at consent.

Concept	Meaning
Company	The shared boundary for records, membership, permissions, and configuration. API field names retain `workspace`.
Task	A durable conversation with instructions, messages, and review history. Store its ID for follow-ups.
Run	One execution attempt within a Task. Retries and follow-ups can create successor Runs.
Interaction	A question or approval that needs a person’s response.
Area	Additional instructions and resources inside Melso Agents; available internally or by private invitation.
Artifact	A versioned file or static app produced by Agents work, with explicit publication and access settings.

Completion has several meanings

Task status summarizes a conversation. Run status describes an execution attempt. Fiscal state records a separate human service process. There is no automatic mapping from a Task or Run status to fiscal authorization or filing.

Task status

Task status is derived from lifecycle fields, Runs, interactions and delivery state. The first matching row wins, in this order. A failed Run is an attention reason, not a Task status. These values describe responses; see Task list filtering for accepted filters and the endpoint reference for write commands.

Task status	Condition	Relationship to Runs and review
`cancelled`	Task cancellation is recorded.	Closing the Task takes precedence over Run signals.
`done`	Task completion is recorded.	An explicit lifecycle action closed the Task; this is not fiscal filing.
`working`	A Run is queued, deferred, dispatched or running.	Active work takes precedence over a paused Run, pending interaction or older delivery.
`paused`	No active Run, but a paused Run exists.	Resume or otherwise resolve the paused execution.
`needs_you`	No active/paused Run and a pending interaction exists.	The intended person needs to respond.
`to_review`	No higher-priority condition and a delivery is recorded.	A substantive result is ready for review. A completed Run alone need not produce this state.
`idle`	None of the preceding conditions applies.	The open conversation has no active execution or review marker.

Run status

This is the complete RunResponse.status vocabulary, also used by Task-stream Run events.

Run status	Meaning	What to do
`queued`	An execution attempt is waiting.	Keep observing the Task.
`deferred`	Execution is waiting for capacity or a later start.	Keep observing; inspect available context.
`dispatched`	Execution has been assigned.	Wait for it to start or resolve.
`running`	The attempt is executing.	Follow progress and pending interactions.
`paused`	Execution is suspended.	Resume when appropriate; a successor can have a new Run ID.
`completed`	This execution attempt ended successfully.	Read its assistant message or attachments and review the result.
`failed`	This attempt failed.	Read `error` and `failure_reason`, then look for an active successor.
`cancelled`	This attempt stopped by cancellation.	Inspect the reason and any successor; the Task may remain open.

delivered is not a Run status. The task.delivered webhook marks substantive work ready for review. task.completed means the Task was closed; neither event establishes fiscal filing.

Fiscal state

These are service stages, not additional Task or Run enum values.

Fiscal stage	Required evidence	Relationship to Tasks and Runs
Preparation and professional review	The current draft and its review.	A generated result may support this work but does not authorize it.
Autorizado · en revisión (authorized, under review)	The customer authorized the exact saved version and opened a case for professional review and filing; it stays in this state until the actual result is recorded.	No Task or Run status substitutes for that authorization or establishes filing.
Submission	A professional submits the authorized version with the required authority.	An import file, approval or completed Run is not proof of submission.
Filed with receipt	The actual external filing reference and receipt have been recorded.	Verify this evidence independently of Task completion.

A changed fiscal draft requires fresh authorization. See Approvals and filing.

Tasks

Create and continue a durable conversation.

Runs

Follow execution attempts and their successors.

MCP setup

Authorize an assistant for your company.

API quickstart

Make a first request with an existing Agents key.

Start here

Your business

Concepts

Technical connections

Core concepts

Completion has several meanings

Task status

Run status

Fiscal state

Tasks

Runs

MCP setup

API quickstart

​Completion has several meanings

​Task status

​Run status

​Fiscal state

Tasks

Runs

MCP setup

API quickstart

Completion has several meanings

Task status

Run status

Fiscal state