# Understanding the Response Shape of agent.complete() in Needle

> Explore the response shape of agent.complete() in Needle. Understand the mandatory type and content keys, plus optional function_calls and confidence fields. Optimize your integration now.

- Repository: [Cactus Compute, Inc./needle](https://github.com/cactus-compute/needle)
- Tags: api-reference
- Published: 2026-09-12

---

**The `agent.complete()` method returns a Python dictionary containing mandatory keys `type` and `content`, with optional fields including `function_calls`, `confidence`, and engine-specific metadata.**

The `agent.complete()` method serves as the high-level entry point for executing completion requests in the Needle library, a native-engine agent framework maintained by cactus-compute. When you invoke this API, you receive a structured Python dictionary that encapsulates the native engine's JSON output along with Needle's post-processing enrichments, making the `agent.complete()` response shape predictable yet extensible for diverse use cases.

## Core Response Structure

The response dictionary always includes two mandatory fields derived directly from the parsed JSON envelope. The **`type`** key returns a string describing the reply nature—typically `"completion"` for plain text or `"call"` when the model requests function invocation. The **`content`** key provides the generated text output as a string.

Beyond these required fields, the dictionary may include several optional entries:

- **`function_calls`**: A `list[dict]` containing tool invocations the model requests. Each dictionary specifies the tool **`name`** and an **`arguments`** dictionary mapping parameter names to values.
- **`confidence`**: A `float` representing the model-reported confidence score, or `None` when using fine-tuned weights.
- **`results`**: A `list` populated only after executing the `run()` loop, containing accumulated outputs from executed tool calls.
- **Engine-specific metadata**: Any additional keys returned by the underlying engine—such as `model_version` or `tokens_used`—pass through unchanged.

## Internal Response Construction Pipeline

Understanding how Needle assembles this dictionary requires examining the internal execution flow defined in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py).

### The Wrapper and Telemetry Layer

The public `Needle.complete()` method acts as a telemetry-enabled wrapper around the private `_complete` implementation. According to lines 21-27 of [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), this entry point first invokes telemetry tracking (implemented in [`needle/_telemetry.py`](https://github.com/cactus-compute/needle/blob/main/needle/_telemetry.py) at line 24), prepares optional audio payloads, and forwards the request to `_complete`.

### Native Engine Integration

The `_complete` method handles the heavy lifting of engine communication. Lines 52-57 validate audio support, bind the native library if necessary, and dispatch to either the fine-tuning worker defined in [`needle/_worker.py`](https://github.com/cactus-compute/needle/blob/main/needle/_worker.py) (lines 284-291) or the compiled library (`lib.needle_complete`). The raw string response undergoes parsing via `json.loads` to produce the initial dictionary structure.

### Post-Processing and Enrichment

After parsing, Needle applies two critical modifications before returning control to the caller. Lines 58-59 inject `response["confidence"] = None` when the agent detects fine-tuned weights, as the confidence head remains unupdated in these configurations. Finally, unless grounding is explicitly disabled, the `_annotate_ungrounded` function mutates the dictionary in-place to flag any ungrounded tool calls.

## Function Calls and Tool Execution

When the model determines that external tools are necessary, the `function_calls` field becomes populated with structured call descriptors governed by schemas defined in [`needle/agent/tools.py`](https://github.com/cactus-compute/needle/blob/main/needle/agent/tools.py). Each entry in this list contains at minimum the tool `name` and an `arguments` dictionary.

Needle's `run()` method subsequently consumes these descriptors to execute the actual Python functions, accumulating results back into the response dictionary under the `results` key during successive completion cycles.

## Practical Usage Examples

The following patterns demonstrate how to interact with different response shapes in production code.

Simple text completion:

```python
from needle import Needle

agent = Needle()
resp = agent.complete("Explain quantum tunnelling in one sentence.")

print(resp["type"])     # → "completion"

print(resp["content"])  # → "Quantum tunnelling …"

```

Completion triggering tool execution:

```python
def weather(city: str) -> str:
    return f"The weather in {city} is sunny."

agent = Needle(tools=[weather])
resp = agent.complete("What's the weather in Paris?")

# Inspect potential function calls

print(resp.get("function_calls"))

# → [{'name': 'weather', 'arguments': {'city': 'Paris'}}]

```

Using fine-tuned weights (confidence disabled):

```python
agent = Needle(weights="my_finetuned.cact")
resp = agent.complete("Summarise the article.")

# Confidence is explicitly set to None with custom weights

print(resp["confidence"])  # → None

```

## Summary

- **`agent.complete()` returns a Python dictionary** parsed from the engine's JSON envelope.
- **Mandatory fields** include `type` (reply classification) and `content` (generated text).
- **Optional fields** encompass `function_calls` for tool invocations, `confidence` scores (unless using fine-tuned weights), and engine-specific metadata.
- **Post-processing occurs** in [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py), where confidence injection and ungrounded call annotation modify the response before return.
- **Tool execution results** populate the `results` key only after `run()` processes function calls.

## Frequently Asked Questions

### What are the mandatory fields in the agent.complete() response?

Every response dictionary returned by `agent.complete()` must contain the `type` and `content` keys. The `type` field indicates whether the output represents a plain text completion or a function call request, while `content` holds the actual generated text string.

### Why is the confidence field set to None when using fine-tuned weights?

When you initialize the Needle agent with custom weights via the `weights` parameter, the `_complete` method forces `response["confidence"] = None` at lines 58-59 of [`needle/__init__.py`](https://github.com/cactus-compute/needle/blob/main/needle/__init__.py). This occurs because the fine-tuning process does not update the model's confidence head, making score reporting unreliable for these configurations.

### How does Needle handle function calls in the response?

The engine populates the optional `function_calls` field with a list of dictionaries describing requested tool invocations. Each dictionary specifies the target tool's `name` and its `arguments` as a parameter mapping. The `run()` method subsequently processes these descriptors to execute the actual Python functions and accumulate outputs.

### Can the response contain additional engine-specific metadata?

Yes. Any extra fields returned by the underlying native engine—such as `model_version`, `tokens_used`, or provider-specific diagnostics—pass through the JSON parsing layer unchanged and appear in the final dictionary alongside Needle's standard fields.